From: Sandro Santilli Date: Mon, 31 Jan 2005 12:32:48 +0000 (+0000) Subject: Markus Shaber version. X-Git-Tag: pgis_1_0_0RC3~81 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=0bb53a237ea4bba72cf85a0fe74186eb6e916973;p=postgis Markus Shaber version. git-svn-id: http://svn.osgeo.org/postgis/trunk@1358 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/jdbc2/README b/jdbc2/README index 426e20410..e12bbb40c 100644 --- a/jdbc2/README +++ b/jdbc2/README @@ -1,17 +1,174 @@ -** 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: org.postgis.DriverWrapper + +- 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!