head	1.4;
access;
symbols
	REL7_2_8:1.3
	REL7_2_7:1.3
	REL7_2_6:1.3
	REL7_2_5:1.3
	REL7_2_4:1.3
	REL7_2_3:1.3
	REL7_3_STABLE:1.3.0.4
	REL7_2_STABLE:1.3.0.2
	REL7_2:1.3
	REL7_2_RC2:1.3
	REL7_2_RC1:1.3
	REL7_2_BETA5:1.3
	REL7_2_BETA4:1.3
	REL7_2_BETA3:1.3
	REL7_2_BETA2:1.3
	REL7_2_BETA1:1.3
	REL7_1_2:1.2
	REL7_1_STABLE:1.2.0.2
	REL7_1_BETA:1.1
	REL7_1_BETA3:1.1
	REL7_1_BETA2:1.1
	REL7_1:1.2
	REL7_0_PATCHES:1.1.0.4
	REL7_0:1.1
	REL6_5_PATCHES:1.1.0.2
	REL6_5:1.1;
locks; strict;
comment	@# @;


1.4
date	2002.10.20.00.10.55;	author barry;	state dead;
branches;
next	1.3;

1.3
date	2001.07.21.18.52.10;	author momjian;	state Exp;
branches
	1.3.4.1;
next	1.2;

1.2
date	2001.01.18.14.50.14;	author peter;	state Exp;
branches;
next	1.1;

1.1
date	99.01.17.04.51.49;	author momjian;	state Exp;
branches;
next	;

1.3.4.1
date	2002.11.04.21.24.29;	author tgl;	state dead;
branches;
next	;


desc
@@


1.4
log
@Applied patch submitted by Mike Beachy to give a better error message if
configure hasn't been run before trying to build.
Also cleaned up the README file and removed some obsolete files.

 Modified Files:
 	jdbc/README jdbc/build.xml
 Removed Files:
 	jdbc/CHANGELOG jdbc/Implementation jdbc/jdbc.jpx
@
text
@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

@


1.3
log
@JDBC encoding additions.

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
@
text
@@


1.3.4.1
log
@Back-patch recent file removals into REL7_3_STABLE branch.
@
text
@@


1.2
log
@Thu Jan 18 12:24:00 GMT 2001 peter@@retep.org.uk
        - These methods in org.postgresql.jdbc2.ResultSet are now implemented:
            getBigDecimal(int) ie: without a scale (why did this get missed?)
            getBlob(int)
            getCharacterStream(int)
            getConcurrency()
            getDate(int,Calendar)
            getFetchDirection()
            getFetchSize()
            getTime(int,Calendar)
            getTimestamp(int,Calendar)
            getType()
          NB: Where int represents the column name, the associated version
              taking a String were already implemented by calling the int
              version.
        - These methods no longer throw the not implemented but the new noupdate
          error. This is in preparation for the Updateable ResultSet support
          which will overide these methods by extending the existing class to
          implement that functionality, but needed to show something other than
          notimplemented:
            cancelRowUpdates()
            deleteRow()
        - Added new error message into errors.properties "postgresql.noupdate"
          This is used by jdbc2.ResultSet when an update method is called and
          the ResultSet is not updateable. A new method notUpdateable() has been
          added to that class to throw this exception, keeping the binary size
          down.
        - Added new error message into errors.properties "postgresql.psqlnotimp"
          This is used instead of unimplemented when it's a feature in the
          backend that is preventing this method from being implemented.
        - Removed getKeysetSize() as its not part of the ResultSet API

Thu Jan 18 09:46:00 GMT 2001 peter@@retep.org.uk
        - Applied modified patch from Richard Bullington-McGuire
          <rbulling@@microstate.com>. I had to modify it as some of the code
          patched now exists in different classes, and some of it actually
          patched obsolete code.

Wed Jan 17 10:19:00 GMT 2001 peter@@retep.org.uk
        - Updated Implementation to include both ANT & JBuilder
        - Updated README to reflect the changes since 7.0
	- Created jdbc.jpr file which allows JBuilder to be used to edit the
          source. JBuilder _CAN_NOT_ be used to compile. You must use ANT for
          that. It's only to allow JBuilders syntax checking to improve the
          drivers source. Refer to Implementation for more details
@
text
@d154 1
@


1.1
log
@As the email posted to the announce and interfaces list, attached is a tar
file containing the latest version of the JDBC driver, allowing it to be
compiled and used under JDK 1.2 and later.

NB: None (well almost none) of the new methods actually do anything. This
release only handles getting it to compile and run. Now this is done, I'll
start working on implementing the new stuff.

Now this tar file replaces everything under src/interfaces/jdbc. I had to
do it this way, rather than diffs, because most of the classes under the
postgresql subdirectory have moved to a new directory under that one, to
enable the support of the two JDBC standards.

Here's a list of files in the tar file. Any file not listed here (in the
postgresql directory) will have to be deleted, otherwise it could cause
the driver to fail:

Peter Mount
@
text
@d4 22
d29 21
a49 5
All compilation must be done by using Make. This is because there are two
versions of the driver, one for JDBC1 (for JDK 1.1.x) and the other for JDBC2
(for JDK 1.2 or later). The makefile determines which version to compile by
using a helper class makeVersion. This class is only used by make, and is not
stored in the Jar file.
d51 2
a52 2
Note:	It is not sufficient to simply call javac on postgresql/Driver.java as
	some classes are dynamically loaded, so javac will not compile them.
d57 15
a71 2
This jar file is produced by make, and contains the driver for your JDK
platform.
d73 12
a84 4
Note:	It is possible to compile the driver under say JDK1.1.7, then under
	JDK 1.2. Because make doesn't remove the old classes before compiling,
	jar will simply package both sets together. When the driver is loaded,
	the postgresql.Driver class will sort out which set of classes to use.
d112 8
a119 7
postgresql			core classes, common to both JDBC 1 & 2
postgresql.jdbc1		classes used only in implementing JDBC 1
postgresql.jdbc2		classes used only in implementing JDBC 2
postgresql.fastpath		FastPath to backend functions
postgresql.geometric		2D Geometric types mapped to Java Objects
postgresql.largeobject		Low level Large Object access
postgresql.util			Utility classes
d122 1
a122 1
Package postgresql
d133 3
d143 13
a155 1
Package postgresql.fastpath
d161 1
a161 1
Package postgresql.geometric
d172 1
a172 1
Package postgresql.jdbc1
d178 1
a178 1
Package postgresql.jdbc2
d184 1
a184 1
Package postgresql.largeobject
d190 1
a190 1
Package postgresql.util
@
