[postgis-devel] New JDBC README

[Markus Schaber]

This is a multi-part message in MIME format.
--------------050708050301050502020801
Content-Type: text/plain; charset=ISO-8859-15
Content-Transfer-Encoding: 8bit

Hi,

Please find a reworked version of the JDBC readme in the attachment.

Thanks,
Markus
--
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

--------------050708050301050502020801
Content-Type: text/plain;
 name="README"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="README"

*** PostGIS JDBC Driver extension README / FAQ***

$Revision:$

* 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:
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!

--------------050708050301050502020801--
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20050131/95cd1b24/attachment.sig>