postgis/java/ejb2

Using PostGIS Geometry Types with EJB2 -- Proof of Concept
----------------------------------------------------------
Copyright (C) 2006 by the Geodetix s.r.l. Company. See
http://www.geodetix.it/ for further information.

Version 1.0.0 (2006/08/29)

Table of Contents
-----------------

0. Licensing
1. Introduction
2. Directory Contents
3. Software Requirements
4. Installation
5. Running
6. Code Details


0. Licensing
------------
The "Using PostGIS Geometry Types with EJB2 -- Proof of Concept" software is
a short collection of examples related to the use of PostGIS Java API with
the EJB 2.x technology.
Copyright (C) 2006 by the Geodetix s.r.l. Company. See
http://www.geodetix.it/ for further information.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA


1. Introduction
---------------
Our software is a simple proof-of-concept application illustrating how the
PostGIS provided Java geometric types could be integrated with a set of
Enterprise Java Bean 2.x components.

To achieve such a goal, an attribute of type org.postgis.Geometry has been 
added to a BMP (Bean managed Persistence) Entity Bean. Furthermore, by using
the DAO (Data Access Object) Pattern, the persistence code has been clearly 
separated from the business logic.

Not to add further complexity, some proper programming behaviours were omitted.
For example the use of PostGIS geometric types directly inside the Entity Bean 
code could be avoided by using a WKT compliant string attribute. Another issue
is about security: table creational methods exposed in the 
com.geodetix.geo.ejb.GeometryBean home interface should be protected by
a proper role-base security policy, to avoid normal users deleting database 
tables.

Nevertheless our application, even if quite simple, still holds a lot of 
generality and some of the implemented patterns or components are readily 
usable in real-world applications.


2. Directory Contents
---------------------

  ./            Build scripts (build.*), README and licensing information
  ./src         Java source packages and files
  ./resources   EJB specific configuration files
  ./lib         JAR libraries needed to compile and run


3. Software Requirements
------------------------
We here list all third-party libraries with their versions tested to work
with the application.

PostGIS JDBC driver version 1.1.3
http://www.postgis.org/

PostgreSQL JDBC driver version 8.1-404 jdbc3
http://jdbc.postgresql.org/

XDoclet lib version 1.2.3
http://xdoclet.sourceforge.net

Apache ANT version 1.6.5
http://ant.apache.org/

JBOSS Application Server version 4.0.4.GA-Patch1
http://www.jboss.org/

Note that our tool is application server agnostic and could be easily ported
to any EJB 2.x compliant Container by modifying the provided deployment 
ant file which is, in turn, written for the JBoss Application Server.


4. Installation
---------------
After downloading (and compiling, if necessary) all of the required software,
follow these steps:

- copy the PostGIS driver (postgis_1.1.3.jar) into the ./lib/commonlib 
directory

- copy the PostgreSQL driver (postgresql-8.1-404.jdbc3.jar) into the 
./lib/compiletimelib directory

- copy the XDoclet libraries (contained in xdoclet-lib-1.2.3.tgz) into the 
./lib/xdocletlib directory

- install Apache ANT (follow the installation istructions provided 
with the tool)

- install the JBoss Application Server

- make sure that your JBOSS_HOME environment variable correctly points to
the JBoss installation directory (i.e. /opt/jboss-4.0.4.GA)

- create a new PostGIS database according to what specified in the
./resources/build.properties with the "database.name", "database.login",
"database.password" properties (eventually change them to fit your needs).


5. Running
----------
Start the JBoss application server with the provided scripts 
(run.bat or run.sh).

From the main application directory (./) execute these commands:

> ant install-JDBC-driver
This command installs the PostgreSQL driver into JBoss

> ant install-DataSource
This command installs the DataSource Connector into JBoss

> ant javadoc
This command generates the application API documentation into the ./javadoc
directory (use index.html to start).

> ant deploy
Installs the application into JBoss

> ant run-client
Allows to test the installed application


6. Code Details
---------------
The main components made available in the application are:

- GeometryBean.java
It is an entity bean containing a geometrical attribute of org.postgis.Geometry
type which could contain every geometrical type (i.e. POINT, LINESTRING, etc.).
The user can choose wether to create a NON-OpenGIS or an OpenGIS-compliant 
bean. The first ones can contain different geometric types in the same table
with undefined SRID (-1), while the second ones can only contain object of the 
same type and SRID in one table;

- PostgisGeometryDaoIml.java
A DAO (Data Access Object) implementing persistence operations for the 
GeometryBean EJB in a PostGIS database;

- GeometryFacadeBean.java
A stateless session bean implementing the interface between the geometric 
entity beans and the client applications;

- Client.java
It is a simple client executing some tests thus illustrating the use of the 
provided API.

Further informations could be gathered from the source code and by reading the
javadoc API documentation.