1
This short document is provided to help programmers through the internals of
2
the PostgreSQL JDBC driver.
4
Last update: January 17 2001 peter@retep.org.uk
9
As of 7.1, we now use the ANT build tool to build the driver. ANT is part of
10
the Apache/Jakarta project, and provides far superior build capabilities. You
11
can find ANT from http://jakarta.apache.org/ant/index.html and being pure java
12
it will run on any java platform.
14
So far I've tested it under JDK1.2.x & JDK1.3 (both Linux & NT) but not yet with
15
JDK1.1.8. Because of the latter the Makefile still works for now, but should be
18
Anyhow, to build, simply type ant and the .jar file will be created and put into
21
Tip: If you run ant from the sources root directory (ie: where the configure
22
script is located) you will find another build.xml file. It is advised to run
23
ant from that directory as it will then compile some auxilary Java/JDBC
24
utilities that are located under the /contrib/retep directory.
29
Prior to 7.1, all compilation must be done by using Make. This is because there
30
are three versions of the driver, one for JDBC1 (for JDK 1.1.x) and the others
31
for JDBC2 (for JDK 1.2 or later, one standard and one enterprise).
33
As of 7.1, ANT is the build tool of choice. Just compare Makefile and build.xml
34
to see why! Make just isn't suited to Java.
36
Building with just the JDK
37
--------------------------
39
This is not advised, simply because you have to make sure you include the
40
correct classes, and the fact that org.postgresql.Driver is built on the fly.
41
Also, javac won't pick up all the classes because some (org.postgresql.geometric
42
for example) are loaded dynamically.
44
org/postgresql/Driver.java.in
45
-----------------------------
47
Because there are three versions of the driver, the org.postgresql.Driver class
48
is built dynamically. To build correctly ANT copies the Driver.java.in file to
49
Driver.java replacing certain values according to the required driver.
51
The replaced values are of the format %VALUE%, ie: %MAJORVERSION% is replaced
52
with 7 in the 7.1 version of the driver.
57
This jar file is produced by ANT, and contains the driver for your JDK platform.
59
If you downloaded a precompiled binary from the web, you may find that the
60
jar file will be named differently. These are identical to this file but are
61
named according to the backend and jdk versions.
63
The naming convention is of the form: jdbc-#.#-#.##.jar
66
jdbc-7.1-1.1.jar JDBC Driver for JDK1.1.8
67
jdbc-7.1-1.2.jar JDBC Driver for JDK1.2 & JDK1.3
68
jdbc-7.1-1.2ent.jar JDBC Driver for JDK1.2 & JDK1.3 Enterprise Editions
70
If in the future there are any 1.3 specific classes then there will be two new
73
Note: All the precompiled binaries are built under Linux.
78
This is a JBuilder4 project file. It's here to allow JBuilder to be used to
79
develop the driver. Mainly for it's Editor's features like syntax checking and
82
IMPORTANT: You CAN NOT build the driver from within JBuilder. You must use ANT.
83
This is because of the three versions of the JDK. If you try to use
84
JBuilder, it will try to build everything, and it will just not work.
89
In user code, you may have to import one or more packages, if and only if you
90
are using the non jdbc extensions (like FastPath, or LargeObject).
92
DO NOT import the postgresql, postgresql.jdbc1 or postgresql.jdbc2 packages!
94
Internally, some classes will import the packages when there is a link between
95
them and the other packages. However, the above rule still applies. It's there
96
because Javac becomes confused between the different places that similar class
99
However, there are places where they need to refer to classes in the postgresql
100
package. In this case, import the individual classes, and not the entire
103
ie: import postgresql.Field
105
NOT import postgresql.*
110
The driver is split into several packages:
112
org.postgresql core classes that can be accessed by user code
113
org.postgresql.core core classes not normally used externally
114
org.postgresql.jdbc1 classes used only in implementing JDBC 1
115
org.postgresql.jdbc2 classes used only in implementing JDBC 2
116
org.postgresql.fastpath FastPath to backend functions
117
org.postgresql.geometric 2D Geometric types mapped to Java Objects
118
org.postgresql.largeobject Low level Large Object access
119
org.postgresql.util Utility classes
122
Package org.postgresql
125
This package holds the core classes.
127
Driver registers the driver when it's loaded, and determines which
128
Connection class (in jdbc1 or jdbc2 packages) to use when
129
connecting to a database.
131
Field Used internally to represent a Field
132
PG_Stream Used internally to manage the network stream.
134
Exists in the Java2 Enterprise edition driver only and is the
135
enterprise equivalent to Driver
137
These classes contains common code that is not dependent to the
138
two JDBC specifications.
140
Connection Common code used in Connections, mainly Network Protocol stuff.
141
ResultSet Common code used in ResultSet's
143
Package org.postgresql.core
144
-----------------------
146
New in 7.1, this is where core classes (common to all versions) will exist. Any
147
new class that would have gone into org.postgresql must go in here instead.
149
BytePoolDim1 Handles a pool of byte[] arrays.
150
BytePoolDim2 Handles a pool of byte[][] arrays
151
MemoryPool Interface for managing MemoryPools. Not used (yet).
152
ObjectPool Interface for an Object Pool
153
SimpleObjectPool Class that implements ObjectPool and used by BytePoolDim#
154
Encoding Character encoding logic, mainly for Connection and PG_Stream.
156
Package org.postgresql.fastpath
157
---------------------------
159
Fastpath Handles executing a function on the PostgreSQL Backend
160
FastpathArg Defines an argument for a function call
162
Package org.postgresql.geometric
163
----------------------------
165
PGbox Maps to postgresql type box
166
PGcircle Maps to postgresql type circle
167
PGline Maps to postgresql type line
168
PGlseg Maps to postgresql type lseg
169
PGpath Maps to postgresql type path
170
PGpoint Maps to postgresql type point
171
PGpolygon Maps to postgresql type polygon
173
Package org.postgresql.jdbc1
174
------------------------
176
The classes in this package handle the JDBC 1 Specification, for JDK 1.1.x
177
All interfaces in the java.sql package are present here.
179
Package org.postgresql.jdbc2
180
------------------------
182
The classes in this package handle the JDBC 2 Specification, for JDK 1.2
183
All interfaces in the java.sql, and javax.sql packages are present here.
185
Package org.postgresql.largeobject
186
------------------------------
188
LargeObject Represents an open LargeObject
189
LargeObjectManager Handles the opening and deleting of LargeObjects
191
Package org.postgresql.util
192
-----------------------
194
PGmoney Maps to postgresql type money
195
PGobject Used to represent postgresql types that have no Java equivalent
196
PGtokenizer Helper class for the geometric types
197
Serialize Used to serialise Java objects into tabes, rather than Blobs
198
UnixCrypt Used to handle crypt authentication
added
removed
src/interfaces/jdbc/Implementation
