[postgis-devel] New JDBC README
strk at refractions.net
strk at refractions.net
Mon Jan 31 05:17:13 PST 2005
Thanks. It's in CVS.
--strk;
On Mon, Jan 31, 2005 at 01:08:50PM +0100, Markus Schaber wrote:
> 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--
> _______________________________________________
> postgis-devel mailing list
> postgis-devel at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-devel
More information about the postgis-devel
mailing list