[postgis-devel] New JDBC README
schabios at logi-track.com
Mon Jan 31 04:08:50 PST 2005
This is a multi-part message in MIME format.
Content-Type: text/plain; charset=ISO-8859-15
Please find a reworked version of the JDBC readme in the attachment.
markus schaber | dipl. informatiker
logi-track ag | rennweg 14-16 | ch 8001 zürich
phone +41-43-888 62 52 | fax +41-43-888 62 53
mailto:schabios at logi-track.com | www.logi-track.com
*** PostGIS JDBC Driver extension README / FAQ***
* What is it all about? *
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:
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
* 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
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
* 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
- Of course, you can also manually register the Datatypes on your
pgjdbc connection. You have to cast your connection to PGConnection
and then call:
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
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 256 bytes
Desc: OpenPGP digital signature
More information about the postgis-devel