mirror of
https://github.com/postgres/postgres.git
synced 2025-09-03 15:22:11 +03:00
ff21a8e5c8
Here's a patch against the current CVS. The changes from the previous patch are mostly related to the changed interface for PG_Stream. Anders Bengtsson
200 lines
7.1 KiB
Plaintext
200 lines
7.1 KiB
Plaintext
This short document is provided to help programmers through the internals of
|
|
the PostgreSQL JDBC driver.
|
|
|
|
Last update: January 17 2001 peter@retep.org.uk
|
|
|
|
build.xml
|
|
---------
|
|
|
|
As of 7.1, we now use the ANT build tool to build the driver. ANT is part of
|
|
the Apache/Jakarta project, and provides far superior build capabilities. You
|
|
can find ANT from http://jakarta.apache.org/ant/index.html and being pure java
|
|
it will run on any java platform.
|
|
|
|
So far I've tested it under JDK1.2.x & JDK1.3 (both Linux & NT) but not yet with
|
|
JDK1.1.8. Because of the latter the Makefile still works for now, but should be
|
|
gone for 7.2.
|
|
|
|
Anyhow, to build, simply type ant and the .jar file will be created and put into
|
|
the jars directory.
|
|
|
|
Tip: If you run ant from the sources root directory (ie: where the configure
|
|
script is located) you will find another build.xml file. It is advised to run
|
|
ant from that directory as it will then compile some auxilary Java/JDBC
|
|
utilities that are located under the /contrib/retep directory.
|
|
|
|
Makefile
|
|
--------
|
|
|
|
Prior to 7.1, all compilation must be done by using Make. This is because there
|
|
are three versions of the driver, one for JDBC1 (for JDK 1.1.x) and the others
|
|
for JDBC2 (for JDK 1.2 or later, one standard and one enterprise).
|
|
|
|
As of 7.1, ANT is the build tool of choice. Just compare Makefile and build.xml
|
|
to see why! Make just isn't suited to Java.
|
|
|
|
Building with just the JDK
|
|
--------------------------
|
|
|
|
This is not advised, simply because you have to make sure you include the
|
|
correct classes, and the fact that org.postgresql.Driver is built on the fly.
|
|
Also, javac won't pick up all the classes because some (org.postgresql.geometric
|
|
for example) are loaded dynamically.
|
|
|
|
org/postgresql/Driver.java.in
|
|
-----------------------------
|
|
|
|
Because there are three versions of the driver, the org.postgresql.Driver class
|
|
is built dynamically. To build correctly ANT copies the Driver.java.in file to
|
|
Driver.java replacing certain values according to the required driver.
|
|
|
|
The replaced values are of the format %VALUE%, ie: %MAJORVERSION% is replaced
|
|
with 7 in the 7.1 version of the driver.
|
|
|
|
postgresql.jar
|
|
--------------
|
|
|
|
This jar file is produced by ANT, and contains the driver for your JDK platform.
|
|
|
|
If you downloaded a precompiled binary from the web, you may find that the
|
|
jar file will be named differently. These are identical to this file but are
|
|
named according to the backend and jdk versions.
|
|
|
|
The naming convention is of the form: jdbc-#.#-#.##.jar
|
|
|
|
ie: for 7.1
|
|
jdbc-7.1-1.1.jar JDBC Driver for JDK1.1.8
|
|
jdbc-7.1-1.2.jar JDBC Driver for JDK1.2 & JDK1.3
|
|
jdbc-7.1-1.2ent.jar JDBC Driver for JDK1.2 & JDK1.3 Enterprise Editions
|
|
|
|
If in the future there are any 1.3 specific classes then there will be two new
|
|
jar files.
|
|
|
|
Note: All the precompiled binaries are built under Linux.
|
|
|
|
jdbc.jpx
|
|
--------
|
|
|
|
This is a JBuilder4 project file. It's here to allow JBuilder to be used to
|
|
develop the driver. Mainly for it's Editor's features like syntax checking and
|
|
auto-completion etc.
|
|
|
|
IMPORTANT: You CAN NOT build the driver from within JBuilder. You must use ANT.
|
|
This is because of the three versions of the JDK. If you try to use
|
|
JBuilder, it will try to build everything, and it will just not work.
|
|
|
|
Importing packages
|
|
------------------
|
|
|
|
In user code, you may have to import one or more packages, if and only if you
|
|
are using the non jdbc extensions (like FastPath, or LargeObject).
|
|
|
|
DO NOT import the postgresql, postgresql.jdbc1 or postgresql.jdbc2 packages!
|
|
|
|
Internally, some classes will import the packages when there is a link between
|
|
them and the other packages. However, the above rule still applies. It's there
|
|
because Javac becomes confused between the different places that similar class
|
|
names are present.
|
|
|
|
However, there are places where they need to refer to classes in the postgresql
|
|
package. In this case, import the individual classes, and not the entire
|
|
package.
|
|
|
|
ie: import postgresql.Field
|
|
|
|
NOT import postgresql.*
|
|
|
|
Package Layout
|
|
--------------
|
|
|
|
The driver is split into several packages:
|
|
|
|
org.postgresql core classes that can be accessed by user code
|
|
org.postgresql.core core classes not normally used externally
|
|
org.postgresql.jdbc1 classes used only in implementing JDBC 1
|
|
org.postgresql.jdbc2 classes used only in implementing JDBC 2
|
|
org.postgresql.fastpath FastPath to backend functions
|
|
org.postgresql.geometric 2D Geometric types mapped to Java Objects
|
|
org.postgresql.largeobject Low level Large Object access
|
|
org.postgresql.util Utility classes
|
|
|
|
|
|
Package org.postgresql
|
|
------------------
|
|
|
|
This package holds the core classes.
|
|
|
|
Driver registers the driver when it's loaded, and determines which
|
|
Connection class (in jdbc1 or jdbc2 packages) to use when
|
|
connecting to a database.
|
|
|
|
Field Used internally to represent a Field
|
|
PG_Stream Used internally to manage the network stream.
|
|
PostgresqlDataSource
|
|
Exists in the Java2 Enterprise edition driver only and is the
|
|
enterprise equivalent to Driver
|
|
|
|
These classes contains common code that is not dependent to the
|
|
two JDBC specifications.
|
|
|
|
Connection Common code used in Connections, mainly Network Protocol stuff.
|
|
ResultSet Common code used in ResultSet's
|
|
|
|
Package org.postgresql.core
|
|
-----------------------
|
|
|
|
New in 7.1, this is where core classes (common to all versions) will exist. Any
|
|
new class that would have gone into org.postgresql must go in here instead.
|
|
|
|
BytePoolDim1 Handles a pool of byte[] arrays.
|
|
BytePoolDim2 Handles a pool of byte[][] arrays
|
|
MemoryPool Interface for managing MemoryPools. Not used (yet).
|
|
ObjectPool Interface for an Object Pool
|
|
SimpleObjectPool Class that implements ObjectPool and used by BytePoolDim#
|
|
Encoding Character encoding logic, mainly for Connection and PG_Stream.
|
|
|
|
Package org.postgresql.fastpath
|
|
---------------------------
|
|
|
|
Fastpath Handles executing a function on the PostgreSQL Backend
|
|
FastpathArg Defines an argument for a function call
|
|
|
|
Package org.postgresql.geometric
|
|
----------------------------
|
|
|
|
PGbox Maps to postgresql type box
|
|
PGcircle Maps to postgresql type circle
|
|
PGline Maps to postgresql type line
|
|
PGlseg Maps to postgresql type lseg
|
|
PGpath Maps to postgresql type path
|
|
PGpoint Maps to postgresql type point
|
|
PGpolygon Maps to postgresql type polygon
|
|
|
|
Package org.postgresql.jdbc1
|
|
------------------------
|
|
|
|
The classes in this package handle the JDBC 1 Specification, for JDK 1.1.x
|
|
All interfaces in the java.sql package are present here.
|
|
|
|
Package org.postgresql.jdbc2
|
|
------------------------
|
|
|
|
The classes in this package handle the JDBC 2 Specification, for JDK 1.2
|
|
All interfaces in the java.sql, and javax.sql packages are present here.
|
|
|
|
Package org.postgresql.largeobject
|
|
------------------------------
|
|
|
|
LargeObject Represents an open LargeObject
|
|
LargeObjectManager Handles the opening and deleting of LargeObjects
|
|
|
|
Package org.postgresql.util
|
|
-----------------------
|
|
|
|
PGmoney Maps to postgresql type money
|
|
PGobject Used to represent postgresql types that have no Java equivalent
|
|
PGtokenizer Helper class for the geometric types
|
|
Serialize Used to serialise Java objects into tabes, rather than Blobs
|
|
UnixCrypt Used to handle crypt authentication
|
|
|