-** This has to be reviewed! **
-To use the PostGIS types, you must:
-- have the postgis.jar in your CLASSPATH
-- have a PostgreSQL JDBC Connection instance
+*** PostGIS JDBC Driver extension README / FAQ ***
- Connection conn = new Connection();
- ((org.postgresql.Connection)conn).addDataType("geometry","org.postgis.PGgeometry");
- ((org.postgresql.Connection)conn).addDataType("box3d","org.postgis.PGbox3d");
+$Revision$
-To build the examples:
-- put the jar file containing the PostgreSQL JDBC under
- postgis/original/jars/postgresql.jar
- The file might be named jdbc7.1-1.2.jar originally
+* What is it all about? *
-- edit the file TestServer.java to adjust the connection information, run
- the test with 'make jtest'
+JDBC is an database driver specification for Java. Like ODBC in the C
+world, JDBC allows java applications to transparently use different
+JDBC compliant databases without any source code changes. PostgreSQL,
+the database PostGIS is written for, comes with a driver that
+follows this specification. For downloads and more info, see:
+http://gborg.postgresql.org/project/pgjdbc/projdisplay.php
+
+The purpose of the JDBC Driver extension is to give the PostgreSQL
+JDBC driver some understanding of the PostGIS data types (Geometry,
+Box3D, Box2D). Without this, the Application can only get byte arrays
+or strings (binary and text representation, rsp.) and has to parse it
+on its own. When registering this extension, the Application can
+simply call getObject(column) on the result of the query, and get a
+real java object that is modeled after the OpenGIS spec. It also can
+create or modify this objects itsself and then pass them into the
+database via the PreparedStatement.setObject() method.
+
+Currently, the code is tested with PostGIS 0.8.1, 0.9.1. 0.9.2 and
+1.0.0. It supports both the new hex-encoded EWKB canonical text
+representation used by PostGIS 1.0.0 lwgeom code, and the old, less
+efficient WKT like representation used by previous releases when
+reading data from the server. When sending data to the server, it
+currently always uses the latter form, which is compatible to all
+PostGIS versions.
+
+
+* Do I need it? *
+
+If you happen to write GIS applications, you can propably benefit.
+
+In case your applications are PostGIS specific, you can fully exploit
+the functionality, see "How to I use it" below for instructions and
+the src/examples directory for some code examples.
+
+If you rather prefer to stay OpenGIS compliant, then you cannot use
+the full driver embedding, as this is PostGIS specific functionality.
+But you can still use the geometry classes as a lightweight java
+geometry model if you do not want to use a full-blown GIS
+implementation like jts. Simply use the asText() and
+GeometryFromText() OpenGIS SQL functions against whichever OpenGIS
+compliant server you want, and use the WKT parsing constructors or
+PGgeometry.geomFromString() as well as Geometry.toString() to convert
+between WKT strings and geometry objects.
+
+
+* How do I build it? *
+
+You need a recent pgjdbc driver jar, see the gborg.postgresql link
+above. It is currently tested with 7.4 and 8.0 pgjdbc releases. Note
+that this does not constrain the PostgreSQL server version. As the
+JDBC drivers are downwards compatible against older servers, you can
+easily use e. G. a pgjdbc 8.0 against a PostgreSQL 7.3 server.
+
+Make shure the pgjdbc driver is available in your Java CLASSPATH,
+either by setting the environment variable, or by editing the
+Makefile.
+
+A "make jar" then compiles the code and creates two jar files. The
+"postgis.jar" is for normal usage and deployment, the
+"postgis_debug.jar" additionally includes the source code, for
+debugging purposes.
+
+
+* How do I use it? *
+
+To use the PostGIS types, you need the postgis.jar and the pgjdbc
+driver in your classpath.
+
+The PostGIS extension must be registered within the JDBC driver.
+There are three ways to do this:
+
+- If you use pgjdbc 8.0, the org/postgresql/postgresql.properties
+ file contained in the postgis.jar autoregisters the PostGIS
+ extension for the PostGIS data types (geometry, box2d, box3d)
+ within the pgjdbc driver.
+
+- You can use the org.postgis.DriverWrapper as replacement for the
+ jdbc driver. This class wraps the PostGreSQL Driver to
+ transparently add the PostGIS Object Classes. This method currently
+ works both with J2EE DataSources, and with the older DriverManager
+ framework. I's a thin wrapper around org.postgresql.Driver that
+ simply registers the extension on every new connection created.
+
+ To use it, you replace the "jdbc:postgresql:" with a
+ "jdbc:postgresql_postGIS" in the jdbc URL, and make your
+ environment aware of the new Driver class.
+
+ DriverManager users simply register org/postgis/DriverWrapper
+ instead of (or in addition to) org.postgresql.Driver, see
+ examples/TestBoxes.connect() for an working code.
+
+ DataSource users similarly have to configure their datasource to
+ use the different class. The following works for jboss, put it in
+ your-ds.xml: <driver-class>org.postgis.DriverWrapper</driver-class>
+
+- Of course, you can also manually register the Datatypes on your
+ pgjdbc connection. You have to cast your connection to PGConnection
+ and then call:
+
+ pgconn.addDataType("geometry", "org.postgis.PGgeometry");
+ pgconn.addDataType("box3d", "org.postgis.PGbox3d");
+ pgconn.addDataType("box2d", "org.postgis.PGbox2d");
+
+ You may need to dig through some wrappers when running in an
+ appserver. E. G. for JBoss, The datasource actually gives you a
+ instance of org.jboss.resource.adapter.jdbc.WrappedConnection and
+ have to call getUnderlyingConnection() on it to get the
+ PGConnection instance.)
+
+ Also note that the above addDataType() methods known from earlier
+ pgjdbc versions are deprecated in pgjdbc 8.0 (but still work), see
+ the commented code variants in the DriverWrapper.addGisTypes()
+ method for an alternative.
+
+Note: Even using pgjdbc 8.0, you may still want to use the second or
+third approach if you have several pgjdbc extensions that
+autoregister for the same PostGIS types, as the driver cannot guess
+which extension it should actually use on which connection. The
+current pgjdbc implementation simply parses all
+org/postgresql/postgresql.properties the classloader can find in his
+classpath, and later definitions override earlier ones.
+
+
+* How to I run the tests? Are they allowed to fail? *
+
+There are two types of tests provided, offline and online. Offline
+tests can run without a PostGIS server, the online tests need a
+PostGIS server to connect to.
+
+- Offline Tests
+
+ The easiest way to run the offline tests is "make offlinetests".
+
+ The offline tests should always complete without any failure. If
+ you happen to get a failure here, it is a bug in the PostGIS code
+ (or, very unlikely, in the JDK/JRE or Hardware you use). Please
+ contact the PostGIS developer list in this case.
+
+- Online tests
+
+ The online tests can be ran with "make onlinetests", but they need
+ a specially prepared database to connect against, and the pgjdbc
+ driver available in your classpath. The Makefile provides defaults
+ for PGHOST, PGPOR, PGDATABASE, PGUSER and PGPASS, you can override
+ them for your needs. For the jtest, the user needs to create and
+ drop table privileges, the two other tests do not use any table.
+ Make shure you have the PostGIS installed in the database.
+
+ Against PostGIS 1.0, none of the online tests should fail. If you
+ test against PostGIS 0.8.1 or 0.9.x, there should be 2 of the box
+ tests failing, due to those releasing not containing the box2d type
+ at all. Additionally, there should be exactly 22 failures for some
+ empty geometry representations in the parser test. This is a
+ PostGIS server side problem as the server fails to parse some
+ OpenGIS compliant WKT representations, and it is unlikely to be
+ fixed as users should migrate to PostGIS 1.0.
+
+ If you get different failures in the online tests, check whether
+ your really fulfil the prerequisites above. If yes, please contact
+ the PostGIS developer list.
+
+
+* Phew. That's all? *
+
+Yes. For now, at least.
+
+Happy Coding!
projects / postgis / commitdiff