数据库系统

开发平台：
Unix_Linux

jdbc.sgml：源码内容
							<Chapter Id="jdbc">
<Title>JDBC Interface</Title>
<para>
<note>
<title>Author</title>
<para>
Written by <ulink url="peter@retep.org.uk">Peter T. Mount</ulink>, the
author of the <acronym>JDBC</acronym> driver.
</para>
</note>
</para>
<para>
<acronym>JDBC</acronym> is a core <acronym>API</acronym> of Java 1.1 and later.
It provides a standard set of
interfaces to <acronym>SQL</acronym>-compliant databases.
</para>
<para>
<application>Postgres</application> provides 
a type 4 <acronym>JDBC</acronym> Driver. Type 4 indicates that the driver
is written in Pure Java, and communicates in the database's own network
protocol. Because of this, the driver is platform independent. Once compiled,
the driver can be used on any platform.
</para>
<sect1>
<title>Building the <acronym>JDBC</acronym> Interface</title>
<sect2>
<title>Compiling the Driver</title>
<para>
The driver's source is located in the <filename>src/interfaces/jdbc</filename>
 directory of the
source tree. To compile simply change directory to that directory, and type:
<programlisting>
% make
</programlisting>
</para>
<para>
Upon completion, you will find the archive <filename>postgresql.jar</filename>
 in the current
directory. This is the <acronym>JDBC</acronym> driver.
<note>
<para>
You must use <application>make</application>,
not <application>javac</application>, 
as the driver uses some dynamic
loading techniques for performance reasons, 
and <application>javac</application> cannot cope.
The <filename>Makefile</filename> will generate the jar archive.
</para>
</note>
</para>
</sect2>
<sect2>
<title>Installing the Driver</title>
<para>
To use the driver, the jar archive postgresql.jar needs to be included in
the CLASSPATH.
</para>
<para>
Example:
</para>
<para>
I have an application that uses the <acronym>JDBC</acronym> driver to access a large database
containing astronomical objects. I have the application and the jdbc driver
installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6.
</para>
<para>
To run the application, I would use:
</para>
<para>
export CLASSPATH = 
        /usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
java uk.org.retep.finder.Main
</para>
<para>
Loading the driver is covered later on in this chapter.
</para>
</sect2>
</sect1>
<sect1>
<title>Preparing the Database for <acronym>JDBC</acronym></title>
<para>
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
must be running with the -i flag.
</para>
<para>
Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA
directory. In a default installation, this file permits access only by UNIX
domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
to add something like:
</para>
<para>
host         all         127.0.0.1     255.255.255.255   password
</para>
<para>
Here access to all databases are possible from the local machine 
with <acronym>JDBC</acronym>.
</para>
<para>
The <acronym>JDBC</acronym> Driver supports trust, ident, 
password and crypt authentication methods.
</para>
</sect1>
<sect1>
<title>Using the Driver</title>
<para>
This section is not intended as a complete guide to 
<acronym>JDBC</acronym> programming, but
should help to get you started. For more information refer to the standard
<acronym>JDBC</acronym> <acronym>API</acronym> documentation.
</para>
<para>
Also, take a look at the examples included with the source. The basic
example is used here.
</para>
</sect1>
<sect1>
<title>Importing <acronym>JDBC</acronym></title>
<para>
Any source that uses <acronym>JDBC</acronym>
needs to import the java.sql package, using:
<programlisting>
import java.sql.*;
</programlisting>
<important>
<para>
Do not import the postgresql package. If you do, your source will not
compile, as javac will get confused.
</para>
</important>
</para>
</sect1>
<sect1>
<title>Loading the Driver</title>
<para>
Before you can connect to a database, you need to load the driver. There
are two methods available, and it depends on your code to the best one to use.
</para>
<para>
In the first method, your code implicitly loads the driver using the
Class.forName() method. For <application>Postgres</application>, you would use:
<programlisting>
Class.forName("postgresql.Driver");
</programlisting>
This will load the driver, and while loading, the driver will automatically
register itself with <acronym>JDBC</acronym>.
</para>
<para>
Note: The <function>forName()</function> method
 can throw a ClassNotFoundException, so you will
need to catch it if the driver is not available.
</para>
<para>
This is the most common method to use, but restricts your code to use just
<application>Postgres</application>. 
If your code may access another database in the future, and you
don't use our extensions, then the second method is advisable.
</para>
<para>
The second method passes the driver as a parameter to the JVM as it starts,
using the -D argument.
</para>
<para>
Example:
<programlisting>
% java -Djdbc.drivers=postgresql.Driver example.ImageViewer
</programlisting>
</para>
<para>
In this example, the JVM will attempt to load the driver as part of it's
initialisation. Once done, the ImageViewer is started.
</para>
<para>
Now, this method is the better one to use because it allows your code to
be used with other databases, without recompiling the code. The only thing
that would also change is the URL, which is covered next.
</para>
<para>
One last thing. When your code then tries to open a Connection, and you get
a <literal>No driver available</literal> SQLException being thrown,
 this is probably
caused by the driver not being in the classpath, or the value in the parameter
not being correct.
</para>
</sect1>
<sect1>
<title>Connecting to the Database</title>
<para>
With <acronym>JDBC</acronym>, a database is represented by a URL 
(Uniform Resource Locator).
With <application>Postgres</application>, this takes one of the following
forms:
<itemizedlist>
<listitem>
<para>
jdbc:postgresql:<replaceable class="parameter">database</replaceable>
</para>
</listitem>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
</para>
</listitem>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
</para>
</listitem>
</itemizedlist>
where:
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
The hostname of the server. Defaults to "localhost".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
The port number the server is listening on. Defaults to the Postgres
standard port number (5432).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">database</replaceable>
</term>
<listitem>
<para>
The database name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
To connect, you need to get a Connection instance from 
<acronym>JDBC</acronym>. To do this,
you would use the DriverManager.getConnection() method:
</para>
<para>
Connection db = DriverManager.getConnection(url,user,pwd);
</para>
</sect1>
<sect1>
<title>Issuing a Query and Processing the Result</title>
<para>
Any time you want to issue SQL statements to the database, you require a
Statement instance. Once you have a Statement, you can use the executeQuery()
method to issue a query. This will return a ResultSet instance, which contains
the entire result.
</para>
<sect2>
<title>Using the Statement Interface</title>
<para>
The following must be considered when using the Statement interface:
<itemizedlist>
<listitem>
<para>
You can use a Statement instance as many times as you want. You could
create one as soon as you open the connection, and use it for the connections
lifetime. You have to remember that only one ResultSet can exist per Statement.
</para>
</listitem>
<listitem>
<para>
If you need to perform a query while processing a ResultSet, you can
simply create and use another Statement.
</para>
</listitem>
<listitem>
<para>
If you are using Threads, and several are using the database, you must
use a separate Statement for each thread. Refer to the sections covering
Threads and Servlets later in this document if you are thinking of using them,
as it covers some important points.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
<title>Using the ResultSet Interface</title>
<para>
The following must be considered when using the ResultSet interface:
<itemizedlist>
<listitem>
<para>
Before reading any values, you must call <function>next()</function>. This returns true if
there is a result, but more importantly, it prepares the row for processing.
</para>
</listitem>
<listitem>
<para>
Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest
to stick to this rule, although at the current time, the <application>Postgres</application> driver
will allow you to access a field as many times as you want.
</para>
</listitem>
<listitem>
<para>
You must close a ResultSet by calling <function>close()</function> once you have finished with it.
</para>
</listitem>
<listitem>
<para>
Once you request another query with the Statement used to create a
ResultSet, the currently open instance is closed.
</para>
</listitem>
</itemizedlist>
</para>
<para>
An example is as follows:
<programlisting>
Statement st = db.createStatement();
ResultSet rs = st.executeQuery("select * from mytable");
while(rs.next()) {
    System.out.print("Column 1 returned ");
    System.out.println(rs.getString(1));
}
rs.close();
st.close();
</programlisting>
</para>
</sect2>
</sect1>
<sect1>
<title>Performing Updates</title>
<para>
To perform an update (or any other SQL statement that does not return a
result), you simply use the executeUpdate() method:
<programlisting>
st.executeUpdate("create table basic (a int2, b int2)");
</programlisting>
</para>
</sect1>
<sect1>
<title>Closing the Connection</title>
<para>
To close the database connection, simply call the close() method to the Connection:
<programlisting>
db.close();
</programlisting>
</para>
</sect1>
<sect1>
<title>Using Large Objects</title>
<para>
In <application>Postgres</application>, 
large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
the database that cannot be stored in a normal SQL table. They are stored as a
Table/Index pair, and are refered to from your own tables, by an OID value.
</para>
<para>
Now, there are you methods of using Large Objects. The first is the
standard <acronym>JDBC</acronym> way, and is documented here. The other, uses our own extension
to the api, which presents the libpq large object <acronym>API</acronym> to Java, providing even
better access to large objects than the standard. Internally, the driver uses
the extension to provide large object support.
</para>
<para>
In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
methods make the large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the object.
</para>
<para>
For example, suppose
you have a table containing the file name of an image, and a large object
containing that image:
<programlisting>
create table images (imgname name,imgoid oid);
</programlisting>
</para>
<para>
To insert an image, you would use:
<programlisting>
File file = new File("myimage.gif");
FileInputStream fis = new FileInputStream(file);
PreparedStatement ps = conn.prepareStatement("insert into images values (?,?)");
ps.setString(1,file.getName());
ps.setBinaryStream(2,fis,file.length());
ps.executeUpdate();
ps.close();
fis.close();
</programlisting>
</para>
<para>
Now in this example, setBinaryStream transfers a set number of bytes from a
stream into a large object, and stores the OID into the field holding a
reference to it.
</para>
<para>
Retrieving an image is even easier (I'm using PreparedStatement here, but
Statement can equally be used):
<programlisting>
PreparedStatement ps = con.prepareStatement("select oid from images where name=?");
ps.setString(1,"myimage.gif");
ResultSet rs = ps.executeQuery();
if(rs!=null) {
    while(rs.next()) {
        InputStream is = rs.getBinaryInputStream(1);
        // use the stream in some way here
        is.close();
    }
    rs.close();
}
ps.close();
</programlisting>
</para>
<para>
Now here you can see where the Large Object is retrieved as an InputStream.
You'll also notice that we close the stream before processing the next row in
the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any
InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
</para>
</sect1>
<sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>
<para>
<application>Postgres</application> is an extensible database system. 
You can add your own functions
to the backend, which can then be called from queries, or even add your own
data types.
</para>
<para>
Now, as these are facilities unique to us, we support them from Java, with
a set of extension <acronym>API</acronym>'s. Some features within 
the core of the standard driver
actually use these extensions to implement Large Objects, etc.
<!--
************************************************************
Nothing marked up from here on. It looks like it will be tricky:
what do we want to do with the class inheritance diagrams?
- thomas 1998-10-23
************************************************************
-->
<programlisting>
Accessing the extensions
To access some of the extensions, you need to use some extra methods 
in the postgresql.Connection class. In this case, you would need to 
case the return value of Driver.getConnection().
For example:
    Connection db = Driver.getConnection(url,user,pass);
    // later on
    Fastpath fp = ((postgresql.Connection)db).getFastpathAPI();
Class postgresql.Connection
                                
java.lang.Object
   |
   +----postgresql.Connection
   public class Connection extends Object implements Connection
These are the extra methods used to gain access to our extensions. I 
have not listed the methods defined by java.sql.Connection.
 public Fastpath getFastpathAPI() throws SQLException
          This returns the Fastpath <acronym>API</acronym> for the current connection.
          NOTE: This is not part of <acronym>JDBC</acronym>, but allows access to 
functions on the postgresql backend itself.
          It is primarily used by the LargeObject <acronym>API</acronym>
          The best way to use this is as follows:
 import postgresql.fastpath.*;
 ...
 Fastpath fp = ((postgresql.Connection)myconn).getFastpathAPI();
          where myconn is an open Connection to postgresql.
        Returns:
                Fastpath object allowing access to functions on the 
postgresql backend.
        Throws: SQLException
                by Fastpath when initialising for first time
          
 public LargeObjectManager getLargeObjectAPI() throws SQLException
          This returns the LargeObject <acronym>API</acronym> for the current connection.
          NOTE: This is not part of <acronym>JDBC</acronym>, but allows access to 
functions on the postgresql backend itself.
   
          The best way to use this is as follows:
 import postgresql.largeobject.*;
 ...
 LargeObjectManager lo = 
((postgresql.Connection)myconn).getLargeObjectAPI();
          where myconn is an open Connection to postgresql.
        Returns:
                LargeObject object that implements the <acronym>API</acronym>
        Throws: SQLException
                by LargeObject when initialising for first time
 public void addDataType(String type,
                         String name)
          This allows client code to add a handler for one of 
postgresql's more unique data types. Normally, a data type not known 
by the driver is returned by ResultSet.getObject() as a PGobject 
instance.
This method allows you to write a class that extends PGobject, and 
tell the driver the type name, and class name to use.
The down side to this, is that you must call this method each time a 
connection is made.
          NOTE: This is not part of <acronym>JDBC</acronym>, but an extension.
          The best way to use this is as follows:
 ...
 ((postgresql.Connection)myconn).addDataType("mytype","my.class.name"-
);
 ...
          where myconn is an open Connection to postgresql.
          The handling class must extend postgresql.util.PGobject
        See Also:
                PGobject
Fastpath
Fastpath is an <acronym>API</acronym> that exists within the libpq C interface, and 
allows a client machine to execute a function on the database backend. 
Most client code will not need to use this method, but it's provided 
because the Large Object <acronym>API</acronym> uses it.
To use, you need to import the postgresql.fastpath package, using the 
line:
     import postgresql.fastpath.*;
Then, in your code, you need to get a FastPath object:
     Fastpath fp = ((postgresql.Connection)conn).getFastpathAPI();
This will return an instance associated with the database connection 
that you can use to issue commands. The casing of Connection to 
postgresql.Connection is required, as the getFastpathAPI() is one of 
our own methods, not <acronym>JDBC</acronym>'s.
Once you have a Fastpath instance, you can use the fastpath() methods 
to execute a backend function.
Class postgresql.fastpath.Fastpath
java.lang.Object
   |
   +----postgresql.fastpath.Fastpath
   public class Fastpath
   extends Object
   This class implements the Fastpath api.
   This is a means of executing functions imbeded in the postgresql 
backend from within a java application.
   It is based around the file src/interfaces/libpq/fe-exec.c
   See Also:
          FastpathFastpathArg, LargeObject
Methods
 public Object fastpath(int fnid,
                        boolean resulttype,
                        FastpathArg args[]) throws SQLException
          Send a function call to the PostgreSQL backend
          
        Parameters:
                fnid - Function id
                resulttype - True if the result is an integer, false 
for
                other results
                args - FastpathArguments to pass to fastpath
        Returns:
                null if no data, Integer if an integer result, or 
byte[]
                otherwise
         
        Throws: SQLException
                if a database-access error occurs.
 public Object fastpath(String name,
                        boolean resulttype,
                        FastpathArg args[]) throws SQLException
          Send a function call to the PostgreSQL backend by name. 
Note:
          the mapping for the procedure name to function id needs to 
exist, usually to an earlier call to addfunction(). This is the 
prefered method to call, as function id's can/may change between 
versions of the backend. For an example of how this works, refer to 
postgresql.LargeObject
        Parameters:
                name - Function name
                resulttype - True if the result is an integer, false 
for
                other results
                args - FastpathArguments to pass to fastpath
        Returns:
                null if no data, Integer if an integer result, or 
byte[]
                otherwise
        Throws: SQLException
                if name is unknown or if a database-access error 
occurs.
        See Also:
                LargeObject
          
 public int getInteger(String name,
                       FastpathArg args[]) throws SQLException
          This convenience method assumes that the return value is an 
Integer
        Parameters:
                name - Function name
                args - Function arguments
        Returns:
                integer result
        Throws: SQLException
                if a database-access error occurs or no result
 public byte[] getData(String name,
                       FastpathArg args[]) throws SQLException
          This convenience method assumes that the return value is 
binary data
        Parameters:
                name - Function name
                args - Function arguments
        Returns:
                byte[] array containing result
        Throws: SQLException
                if a database-access error occurs or no result
 public void addFunction(String name,
                         int fnid)
          This adds a function to our lookup table.
          User code should use the addFunctions method, which is based 
upon a query, rather than hard coding the oid. The oid for a function 
is not guaranteed to remain static, even on different servers of the 
same version.
        Parameters:
                name - Function name
                fnid - Function id
 public void addFunctions(ResultSet rs) throws SQLException
                       
          This takes a ResultSet containing two columns. Column 1 
contains the function name, Column 2 the oid.
          It reads the entire ResultSet, loading the values into the 
function table.
          REMEMBER to close() the resultset after calling this!!
          Implementation note about function name lookups:
          
          PostgreSQL stores the function id's and their corresponding 
names in the pg_proc table. To speed things up locally, instead of 
querying each function from that table when required, a Hashtable is 
used. Also, only the function's required are entered into this table, 
keeping connection times as fast as possible.
          The postgresql.LargeObject class performs a query upon it's 
startup, and passes the returned ResultSet to the addFunctions() 
method here.
       
          Once this has been done, the LargeObject api refers to the 
functions by name.
          
          Dont think that manually converting them to the oid's will 
work. Ok, they will for now, but they can change during development 
(there was some discussion about this for V7.0), so this is 
implemented to prevent any unwarranted headaches in the future.
        Parameters:
                rs - ResultSet
        Throws: SQLException
                if a database-access error occurs.
          
        See Also:
                LargeObjectManager
 public int getID(String name) throws SQLException
          
          This returns the function id associated by its name
          
          If addFunction() or addFunctions() have not been called for 
this name, then an SQLException is thrown.
        Parameters:
                name - Function name to lookup
        Returns:
                Function ID for fastpath call
        Throws: SQLException
                is function is unknown.
Class postgresql.fastpath.FastpathArg
java.lang.Object
   |
   +----postgresql.fastpath.FastpathArg
   public class FastpathArg extends Object
        
   Each fastpath call requires an array of arguments, the number and 
type dependent on the function being called.
   This class implements methods needed to provide this capability.
   For an example on how to use this, refer to the 
postgresql.largeobject package
   See Also:
          Fastpath, LargeObjectManager, LargeObject
Constructors
 public FastpathArg(int value)
 
          Constructs an argument that consists of an integer value
        Parameters:
                value - int value to set
 public FastpathArg(byte bytes[])
          
          Constructs an argument that consists of an array of bytes
        Parameters:
                bytes - array to store
 public FastpathArg(byte buf[],
                    int off,
                    int len)
           Constructs an argument that consists of part of a byte 
array
        Parameters:
                buf - source array
                off - offset within array
                len - length of data to include
 public FastpathArg(String s)
          
          Constructs an argument that consists of a String.
      
        Parameters:
                s - String to store
Geometric Data Types
PostgreSQL has a set of datatypes that can store geometric features 
into a table. These range from single points, lines, and polygons.
We support these types in Java with the postgresql.geometric package.
It contains classes that extend the postgresql.util.PGobject class. 
Refer to that class for details on how to implement your own data type 
handlers.
Class postgresql.geometric.PGbox
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGbox
   public class PGbox extends PGobject implements Serializable, 
Cloneable
   This represents the box datatype within postgresql.
Variables
 public PGpoint point[]
          These are the two corner points of the box.
Constructors
 public PGbox(double x1,
              double y1,
              double x2,
              double y2)
        Parameters:
                x1 - first x coordinate
                y1 - first y coordinate
                x2 - second x coordinate
                y2 - second y coordinate
 public PGbox(PGpoint p1,
              PGpoint p2)
        Parameters:
                p1 - first point
                p2 - second point
 public PGbox(String s) throws SQLException
                            
        Parameters:
                s - Box definition in PostgreSQL syntax
        Throws: SQLException
                if definition is invalid
                
 public PGbox()
          Required constructor
              
Methods
 public void setValue(String value) throws SQLException
                
          This method sets the value of this object. It should be 
overidden, but still called by subclasses.
                            
        Parameters:
                value - a string representation of the value of the 
object
        Throws: SQLException
                thrown if value is invalid for this type
        Overrides:
                setValue in class PGobject
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
                
        Returns:
                true if the two boxes are identical
          
        Overrides:
                equals in class PGobject
 public Object clone()
        
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
   
 public String getValue()
        
        Returns:
                the PGbox in the syntax expected by postgresql
        Overrides:
                getValue in class PGobject
Class postgresql.geometric.PGcircle
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGcircle
        
   public class PGcircle extends PGobject implements Serializable, 
Cloneable
               
   This represents postgresql's circle datatype, consisting of a point 
and a radius
Variables
 public PGpoint center
           
          This is the centre point
 
public double radius
           
          This is the radius
   
Constructors   
 public PGcircle(double x,
                 double y,
                 double r)
          
        Parameters:
               x - coordinate of centre
                y - coordinate of centre
                r - radius of circle
 public PGcircle(PGpoint c,
                 double r)
          
        Parameters:
                c - PGpoint describing the circle's centre
                r - radius of circle
 public PGcircle(String s) throws SQLException
        Parameters:
                s - definition of the circle in PostgreSQL's syntax.
        Throws: SQLException
                on conversion failure
 public PGcircle()
          This constructor is used by the driver.
            
Methods   
 public void setValue(String s) throws SQLException
        Parameters:
                s - definition of the circle in PostgreSQL's syntax.
        Throws: SQLException
                on conversion failure
        Overrides:
                setValue in class PGobject
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
            
        Returns:
                true if the two boxes are identical
        Overrides:
                equals in class PGobject
 public Object clone()
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
 public String getValue()
        Returns:
                the PGcircle in the syntax expected by postgresql
        
        Overrides:
                getValue in class PGobject
Class postgresql.geometric.PGline
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGline
   public class PGline extends PGobject implements Serializable, 
Cloneable
   This implements a line consisting of two points. Currently line is 
not yet implemented in the backend, but this class ensures that when 
it's done were ready for it.
Variables
   
 public PGpoint point[]
     
          These are the two points.
Constructors
 public PGline(double x1,
               double y1,
               double x2,
               double y2)
        Parameters:
                x1 - coordinate for first point
                y1 - coordinate for first point
                x2 - coordinate for second point
                y2 - coordinate for second point
 public PGline(PGpoint p1,
               PGpoint p2)
     
        Parameters:
                p1 - first point
                p2 - second point
 public PGline(String s) throws SQLException
               
        Parameters:
                s - definition of the circle in PostgreSQL's syntax.
        Throws: SQLException
                on conversion failure
 public PGline()
          reuired by the driver
               
Methods
 public void setValue(String s) throws SQLException
        Parameters:
                s - Definition of the line segment in PostgreSQL's 
syntax
        Throws: SQLException
                on conversion failure
        Overrides:
                setValue in class PGobject
                
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
               
        Returns:
                true if the two boxes are identical
   
        Overrides:
                equals in class PGobject
 public Object clone()
        
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
 public String getValue()
   
        Returns:
                the PGline in the syntax expected by postgresql
        
        Overrides:
                getValue in class PGobject
Class postgresql.geometric.PGlseg
             
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGlseg
          
   public class PGlseg extends PGobject implements Serializable, 
Cloneable
 
   This implements a lseg (line segment) consisting of two points
Variables
 public PGpoint point[]
           
          These are the two points.
Constructors
   
 public PGlseg(double x1,
               double y1,
               double x2,
               double y2)
     
        Parameters:
                x1 - coordinate for first point
                y1 - coordinate for first point
                x2 - coordinate for second point
                y2 - coordinate for second point
 public PGlseg(PGpoint p1,
               PGpoint p2)
           
        Parameters:
                p1 - first point
                p2 - second point
   
 public PGlseg(String s) throws SQLException
        Parameters:
                s - definition of the circle in PostgreSQL's syntax.
        Throws: SQLException
                on conversion failure
 public PGlseg()
          reuired by the driver
               
Methods    
   
 public void setValue(String s) throws SQLException
   
        Parameters:
                s - Definition of the line segment in PostgreSQL's 
syntax
        Throws: SQLException
                on conversion failure
     
        Overrides:
                setValue in class PGobject
                
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
               
        Returns:
                true if the two boxes are identical
   
        Overrides:
                equals in class PGobject
   
 public Object clone()
          This must be overidden to allow the object to be cloned
        Overrides:
               clone in class PGobject
 public String getValue()
        Returns:
                the PGlseg in the syntax expected by postgresql
        
        Overrides:
                getValue in class PGobject
Class postgresql.geometric.PGpath
                                
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGpath
          
   public class PGpath extends PGobject implements Serializable, 
Cloneable
               
   This implements a path (a multiple segmented line, which may be 
closed)
           
Variables
 public boolean open
               
          True if the path is open, false if closed
 public PGpoint points[]
          The points defining this path
Constructors   
 public PGpath(PGpoint points[],
               boolean open)
          
        Parameters:
                points - the PGpoints that define the path
                open - True if the path is open, false if closed
 public PGpath()
          Required by the driver
 public PGpath(String s) throws SQLException
        Parameters:
                s - definition of the circle in PostgreSQL's syntax.
        Throws: SQLException
                on conversion failure
Methods
 public void setValue(String s) throws SQLException
   
        Parameters:
                s - Definition of the path in PostgreSQL's syntax
           
        Throws: SQLException
                on conversion failure
        Overrides:
                setValue in class PGobject
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
        Returns:
                true if the two boxes are identical
        Overrides:
                equals in class PGobject
 public Object clone()
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
 public String getValue()
          This returns the polygon in the syntax expected by 
postgresql
        Overrides:
                getValue in class PGobject
 public boolean isOpen()
     This returns true if the path is open
 public boolean isClosed()
     This returns true if the path is closed
 public void closePath()
     Marks the path as closed
 public void openPath()
     Marks the path as open
Class postgresql.geometric.PGpoint
                                
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGpoint
          
   public class PGpoint extends PGobject implements Serializable, 
Cloneable
   This implements a version of java.awt.Point, except it uses double 
to represent the coordinates.
   It maps to the point datatype in postgresql.
Variables
 public double x
          The X coordinate of the point
 public double y
          The Y coordinate of the point
Constructors
 public PGpoint(double x,
                double y)
        Parameters:
                x - coordinate
                y - coordinate
 public PGpoint(String value) throws SQLException
     
          This is called mainly from the other geometric types, when a 
point is imbeded within their definition.
             
        Parameters:
                value - Definition of this point in PostgreSQL's 
syntax
   
 public PGpoint()
          
          Required by the driver
Methods
 public void setValue(String s) throws SQLException
        Parameters:
                s - Definition of this point in PostgreSQL's syntax
        Throws: SQLException
                on conversion failure
        Overrides:
                setValue in class PGobject
          
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
        Returns:
                true if the two boxes are identical
        Overrides:
                equals in class PGobject
 public Object clone()
                
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
          
 public String getValue()       
    
        Returns:
                the PGpoint in the syntax expected by postgresql
        Overrides:
                getValue in class PGobject
          
 public void translate(int x,
                       int y)
          Translate the point with the supplied amount.
        Parameters:
                x - integer amount to add on the x axis
                y - integer amount to add on the y axis
 public void translate(double x,
                       double y)
          
          Translate the point with the supplied amount.
 
        Parameters:
                x - double amount to add on the x axis
                y - double amount to add on the y axis
 public void move(int x,
                  int y)
                
          Moves the point to the supplied coordinates.
        Parameters:
                x - integer coordinate
                y - integer coordinate
public void move(double x,
                  double y)
          
          Moves the point to the supplied coordinates.
        Parameters:
                x - double coordinate
                y - double coordinate
 public void setLocation(int x,
                         int y)
          Moves the point to the supplied coordinates. refer to
          java.awt.Point for description of this
        Parameters:
                x - integer coordinate
                y - integer coordinate
        See Also:
                Point
 public void setLocation(Point p)
          Moves the point to the supplied java.awt.Point refer to
          java.awt.Point for description of this
        Parameters:
                p - Point to move to
        See Also:
                Point
Class postgresql.geometric.PGpolygon
                                
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGpolygon
   public class PGpolygon extends PGobject implements Serializable, 
Cloneable
               
   This implements the polygon datatype within PostgreSQL.
Variables
 public PGpoint points[]
          The points defining the polygon
                                
Constructors
 public PGpolygon(PGpoint points[])
          Creates a polygon using an array of PGpoints
        Parameters:
                points - the points defining the polygon
 public PGpolygon(String s) throws SQLException
                 
        Parameters:
                s - definition of the circle in PostgreSQL's syntax.
        Throws: SQLException
                on conversion failure
 public PGpolygon()
          Required by the driver
Methods
 public void setValue(String s) throws SQLException
        Parameters:
                s - Definition of the polygon in PostgreSQL's syntax
        Throws: SQLException
                on conversion failure
        Overrides:
                setValue in class PGobject
 public boolean equals(Object obj)
     
        Parameters:
                obj - Object to compare with
                                
        Returns:
                true if the two boxes are identical
        Overrides:
                equals in class PGobject
 public Object clone()
        
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
                 
 public String getValue()
        Returns:
                the PGpolygon in the syntax expected by postgresql
        Overrides:
                getValue in class PGobject
Large Objects
Large objects are supported in the standard <acronym>JDBC</acronym> specification. 
However, that interface is limited, and the api provided by PostgreSQL 
allows for random access to the objects contents, as if it was a local 
file.
The postgresql.largeobject package profides to Java the libpq C 
interface's large object <acronym>API</acronym>. It consists of two classes, 
LargeObjectManager, which deals with creating, opening and deleting 
large obejects, and LargeObject which deals with an individual object.
Class postgresql.largeobject.LargeObject
java.lang.Object
   |
   +----postgresql.largeobject.LargeObject
public class LargeObject extends Object
This class implements the large object interface to postgresql.
   It provides the basic methods required to run the interface, plus a 
pair of methods that provide InputStream and OutputStream classes for 
this object.
   Normally, client code would use the getAsciiStream, 
getBinaryStream, or getUnicodeStream methods in ResultSet, or 
setAsciiStream, setBinaryStream, or setUnicodeStream methods in 
PreparedStatement to access Large Objects.
   However, sometimes lower level access to Large Objects are 
required, that are not supported by the <acronym>JDBC</acronym> specification.
   Refer to postgresql.largeobject.LargeObjectManager on how to gain 
access to a Large Object, or how to create one.
   See Also:
          LargeObjectManager
Variables
 public static final int SEEK_SET
          Indicates a seek from the begining of a file
 public static final int SEEK_CUR
          Indicates a seek from the current position
 public static final int SEEK_END
          Indicates a seek from the end of a file
Methods
 public int getOID()
        Returns:
                the OID of this LargeObject
 public void close() throws SQLException
          This method closes the object. You must not call methods in 
this object after this is called.
    Throws: SQLException
                if a database-access error occurs.
 public byte[] read(int len) throws SQLException
          Reads some data from the object, and return as a byte[] 
array
        Parameters:
                len - number of bytes to read
        Returns:
                byte[] array containing data read
        Throws: SQLException
                if a database-access error occurs.
 public void read(byte buf[],
                  int off,
                  int len) throws SQLException
          Reads some data from the object into an existing array
        Parameters:
                buf - destination array
                off - offset within array
                len - number of bytes to read
        Throws: SQLException
                if a database-access error occurs.
 public void write(byte buf[]) throws SQLException
          Writes an array to the object
        Parameters:
                buf - array to write
        Throws: SQLException
                if a database-access error occurs.
 public void write(byte buf[],
                   int off,
                   int len) throws SQLException
          Writes some data from an array to the object
        Parameters:
                buf - destination array
                off - offset within array
                len - number of bytes to write
        Throws: SQLException
                if a database-access error occurs.
 public void seek(int pos,
                  int ref) throws SQLException
          Sets the current position within the object.
          This is similar to the fseek() call in the standard C 
library.It allows you to have random access to the large object.
        Parameters:
                pos - position within object
                ref - Either SEEK_SET, SEEK_CUR or SEEK_END
        Throws: SQLException
                if a database-access error occurs.
 public void seek(int pos) throws SQLException
          Sets the current position within the object.
          This is similar to the fseek() call in the standard C 
library.It allows you to have random access to the large object.
        Parameters:
                pos - position within object from begining
        Throws: SQLException
                if a database-access error occurs.
 public int tell() throws SQLException
        Returns:
                the current position within the object
        Throws: SQLException
                if a database-access error occurs.
 public int size() throws SQLException
          This method is inefficient, as the only way to find out the 
size of the object is to seek to the end, record the current position, 
then return to the original position.
          A better method will be found in the future.
        Returns:
                the size of the large object
        Throws: SQLException
                if a database-access error occurs.
 public InputStream getInputStream() throws SQLException
          Returns an InputStream from this object.
          This InputStream can then be used in any method that 
requires an InputStream.
        Throws: SQLException
                if a database-access error occurs.
 public OutputStream getOutputStream() throws SQLException
          Returns an OutputStream to this object
          This OutputStream can then be used in any method that 
requires an OutputStream.
        Throws: SQLException
                if a database-access error occurs.
Class postgresql.largeobject.LargeObjectManager
                                
java.lang.Object
   |
   +----postgresql.largeobject.LargeObjectManager
public class LargeObjectManager extends Object
This class implements the large object interface to postgresql.
        
   It provides methods that allow client code to create, open and 
delete large objects from the database. When opening an object, an 
instance of postgresql.largeobject.LargeObject is returned, and its 
methods then allow access to the object.
This class can only be created by postgresql.Connection
To get access to this class, use the following segment of code:
 import postgresql.largeobject.*;
 Connection  conn;
 LargeObjectManager lobj;
 ... code that opens a connection ...
 lobj = ((postgresql.Connection)myconn).getLargeObjectAPI();
Normally, client code would use the getAsciiStream, getBinaryStream, 
or getUnicodeStream methods in ResultSet, or setAsciiStream, 
setBinaryStream, or setUnicodeStream methods in PreparedStatement to 
access Large Objects.
   However, sometimes lower level access to Large Objects are 
required, that are not supported by the <acronym>JDBC</acronym> specification.
   Refer to postgresql.largeobject.LargeObject on how to manipulate 
the contents of a Large Object.
   See Also:
          LargeObject
Variables
 public static final int WRITE
          This mode indicates we want to write to an object
 public static final int READ
          This mode indicates we want to read an object
 public static final int READWRITE
          This mode is the default. It indicates we want read and 
write access to a large object
Methods
 public LargeObject open(int oid) throws SQLException
          
          This opens an existing large object, based on its OID. This
          method assumes that READ and WRITE access is required (the 
default).
        Parameters:
                oid - of large object
        Returns:
                LargeObject instance providing access to the object
        Throws: SQLException
                on error
 public LargeObject open(int oid,
                         int mode) throws SQLException
          
          This opens an existing large object, based on its OID
  
        Parameters:
                oid - of large object
                mode - mode of open
        Returns:
                LargeObject instance providing access to the object
        Throws: SQLException
                on error
 public int create() throws SQLException
          This creates a large object, returning its OID.
          It defaults to READWRITE for the new object's attributes.
        Returns:
                oid of new object
        Throws: SQLException
                on error
 public int create(int mode) throws SQLException
          This creates a large object, returning its OID
        Parameters:
                mode - a bitmask describing different attributes of 
the
                new object
        Returns:
                oid of new object
        Throws: SQLException
                on error
 public void delete(int oid) throws SQLException
          
          This deletes a large object.
          
        Parameters:
                oid - describing object to delete
        Throws: SQLException
                on error
 public void unlink(int oid) throws SQLException
          This deletes a large object.
          It is identical to the delete method, and is supplied as the 
C <acronym>API</acronym> uses unlink.
        Parameters:
                oid - describing object to delete
        Throws: SQLException
                on error
Object Serialisation
PostgreSQL is not a normal SQL Database. It is far more extensible 
than most other databases, and does support Object Oriented features 
that are unique to it. 
One of the consequences of this, is that you can have one table refer 
to a row in another table. For example:
test=> create table users (username name,fullname text);
CREATE
test=> create table server (servername name,adminuser users);
CREATE
test=> insert into users values ('peter','Peter Mount');
INSERT 2610132 1
test=> insert into server values ('maidast',2610132::users);
INSERT 2610133 1
test=> select * from users;
username|fullname      
--------+--------------
peter   |Peter Mount   
(1 row)
test=> select * from server;
servername|adminuser
----------+---------
maidast   |  2610132
(1 row)
Ok, the above example shows that we can use a table name as a field, 
and the row's oid value is stored in that field.
What does this have to do with Java?
In Java, you can store an object to a Stream as long as it's class 
implements the java.io.Serializable interface. This process, known as 
Object Serialization, can be used to store complex objects into the 
database.
Now, under <acronym>JDBC</acronym>, you would have to use a LargeObject to store them. 
However, you cannot perform queries on those objects.
What the postgresql.util.Serialize class does, is provide a means of 
storing an object as a table, and to retrieve that object from a 
table. In most cases, you would not need to access this class direct, 
but you would use the PreparedStatement.setObject() and 
ResultSet.getObject() methods. Those methods will check the objects 
class name against the table's in the database. If a match is found, 
it assumes that the object is a Serialized object, and retrieves it 
from that table. As it does so, if the object contains other 
serialized objects, then it recurses down the tree.
Sound's complicated? In fact, it's simpler than what I wrote - it's 
just difficult to explain.
The only time you would access this class, is to use the create() 
methods. These are not used by the driver, but issue one or more 
"create table" statements to the database, based on a Java Object or 
Class that you want to serialize.
Oh, one last thing. If your object contains a line like:
     public int oid;
then, when the object is retrieved from the table, it is set to the 
oid within the table. Then, if the object is modified, and re-
serialized, the existing entry is updated.
If the oid variable is not present, then when the object is 
serialized, it is always inserted into the table, and any existing 
entry in the table is preserved.
Setting oid to 0 before serialization, will also cause the object to 
be inserted. This enables an object to be duplicated in the database.
Class postgresql.util.Serialize
java.lang.Object
   |
   +----postgresql.util.Serialize
   public class Serialize extends Object
   This class uses PostgreSQL's object oriented features to store Java 
Objects. It does this by mapping a Java Class name to a table in the 
database. Each entry in this new table then represents a Serialized 
instance of this class. As each entry has an OID (Object IDentifier), 
this OID can be included in another table. This is too complex to show 
here, and will be documented in the main documents in more detail.
Constructors
 public Serialize(Connection c,
                  String type) throws SQLException
          This creates an instance that can be used to serialize 
ordeserialize a Java object from a PostgreSQL table.
Methods
 public Object fetch(int oid) throws SQLException
          This fetches an object from a table, given it's OID
        Parameters:
                oid - The oid of the object
        Returns:
                Object relating to oid
        Throws: SQLException
                on error
 public int store(Object o) throws SQLException
          This stores an object into a table, returning it's OID.
          If the object has an int called OID, and it is > 0, then 
that value is used for the OID, and the table will be updated. If the 
value of OID is 0, then a new row will be created, and the value of 
OID will be set in the object. This enables an object's value in the 
database to be updateable. If the object has no int called OID, then 
the object is stored. However if the object is later retrieved, 
amended and stored again, it's new state will be appended to the 
table, and will not overwrite the old entries.
        Parameters:
                o - Object to store (must implement Serializable)
        Returns:
                oid of stored object
        Throws: SQLException
                on error
 
 public static void create(Connection con,
                           Object o) throws SQLException
          This method is not used by the driver, but it creates a 
table, given a Serializable Java Object. It should be used before 
serializing any objects.
        Parameters:
                c - Connection to database
                o - Object to base table on
        Throws: SQLException
                on error
                   Returns:
                Object relating to oid
        Throws: SQLException
                on error
 public int store(Object o) throws SQLException
          This stores an object into a table, returning it's OID.
          If the object has an int called OID, and it is > 0, then 
that value is used for the OID, and the table will be updated. If the 
value of OID is 0, then a new row will be created, and the value of 
OID will be set in the object. This enables an object's value in the 
database to be updateable. If the object has no int called OID, then 
the object is stored. However if the object is later retrieved, 
amended and stored again, it's new state will be appended to the 
table, and will not overwrite the old entries.
        Parameters:
                o - Object to store (must implement Serializable)
        Returns:
                oid of stored object
        Throws: SQLException
                on error
 
 public static void create(Connection con,
                           Object o) throws SQLException
          This method is not used by the driver, but it creates a 
table, given a Serializable Java Object. It should be used before 
serializing any objects.
        Parameters:
                c - Connection to database
                o - Object to base table on
        Throws: SQLException
                on error
                
 public static void create(Connection con,
                           Class c) throws SQLException
          This method is not used by the driver, but it creates a 
table, given a Serializable Java Object. It should be used before 
serializing any objects.
        Parameters:
                c - Connection to database
                o - Class to base table on
        Throws: SQLException
                on error
 public static String toPostgreSQL(String name) throws SQLException
          
          This converts a Java Class name to a postgresql table, by
          replacing . with _
          Because of this, a Class name may not have _ in the name.
          Another limitation, is that the entire class name (including
          packages) cannot be longer than 31 characters (a limit 
forced by PostgreSQL).
        Parameters:
                name - Class name
        Returns:
                PostgreSQL table name
        Throws: SQLException
                on error
          
 public static String toClassName(String name) throws SQLException
          This converts a postgresql table to a Java Class name, by
          replacing _ with .
        Parameters:
                name - PostgreSQL table name
  
        Returns:
                Class name
        Throws: SQLException
                on error
Utility Classes
The postgresql.util package contains classes used by the internals of 
the main driver, and the other extensions.
Class postgresql.util.PGmoney
                                
java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.util.PGmoney
   public class PGmoney extends PGobject implements Serializable, 
Cloneable
               
   This implements a class that handles the PostgreSQL money type
Variables
 public double val
                                
          The value of the field
Constructors
           
 public PGmoney(double value)
   
        Parameters:
                value - of field
               
 public PGmoney(String value) throws SQLException
   
          This is called mainly from the other geometric types, when a 
point is imbeded within their definition.
        Parameters:
                value - Definition of this point in PostgreSQL's 
syntax
 public PGmoney()
          Required by the driver
Methods
 public void setValue(String s) throws SQLException
        Parameters:
                s - Definition of this point in PostgreSQL's syntax
        Throws: SQLException
                on conversion failure
        Overrides:
                setValue in class PGobject
 public boolean equals(Object obj)
        Parameters:
                obj - Object to compare with
                                
        Returns:
                true if the two boxes are identical
        Overrides:
                equals in class PGobject
 public Object clone()
                
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class PGobject
 public String getValue()
        Returns:
                the PGpoint in the syntax expected by postgresql
        Overrides:
                getValue in class PGobject
Class postgresql.util.PGobject
java.lang.Object
   |
   +----postgresql.util.PGobject
   public class PGobject extends Object implements Serializable, 
Cloneable
               
   This class is used to describe data types that are unknown by <acronym>JDBC</acronym> 
Standard.
    A call to postgresql.Connection permits a class that extends this 
class to be associated with a named type. This is how the 
postgresql.geometric package operates.
    ResultSet.getObject() will return this class for any type that is 
not recognised on having it's own handler. Because of this, any 
postgresql data type is supported.
Constructors
 public PGobject()
          This is called by postgresql.Connection.getObject() to 
create the object.
Methods
 public final void setType(String type)
          This method sets the type of this object.
          It should not be extended by subclasses, hence its final
        Parameters:
                type - a string describing the type of the object
 public void setValue(String value) throws SQLException
          This method sets the value of this object. It must be 
overidden.
        Parameters:
                value - a string representation of the value of the
                object
        Throws: SQLException
                thrown if value is invalid for this type
    
 public final String getType()
          As this cannot change during the life of the object, it's 
final.
        Returns:
                the type name of this object
 public String getValue()
          This must be overidden, to return the value of the object, 
in the form required by postgresql.
        Returns:
                the value of this object
 public boolean equals(Object obj)
          This must be overidden to allow comparisons of objects
        Parameters:
                obj - Object to compare with
        Returns:
                true if the two boxes are identical
        Overrides:
                equals in class Object
 public Object clone()
          This must be overidden to allow the object to be cloned
        Overrides:
                clone in class Object
 public String toString()
          This is defined here, so user code need not overide it.
          
        Returns:
                the value of this object, in the syntax expected by 
postgresql
        Overrides:
                toString in class Object
Class postgresql.util.PGtokenizer
java.lang.Object
   |
   +----postgresql.util.PGtokenizer
   public class PGtokenizer extends Object
   This class is used to tokenize the text output of postgres.
   We could have used StringTokenizer to do this, however, we needed 
to handle nesting of '(' ')' '[' ']' '<' and '>' as these are used by 
the geometric data types.
   It's mainly used by the geometric classes, but is useful in parsing 
any output from custom data types output from postgresql.
                 
   See Also:
          PGbox, PGcircle, PGlseg, PGpath, PGpoint, PGpolygon
          
Constructors
 public PGtokenizer(String string,
                    char delim)
          Create a tokeniser.
        Parameters:
                string - containing tokens
                delim - single character to split the tokens
Methods
        
 public int tokenize(String string,
                     char delim)
          This resets this tokenizer with a new string and/or 
delimiter.
        Parameters:
                string - containing tokens
                delim - single character to split the tokens
 public int getSize()
        Returns:
                the number of tokens available
 public String getToken(int n)
        Parameters:
                n - Token number ( 0 ... getSize()-1 )
        Returns:
                The token value
 public PGtokenizer tokenizeToken(int n,
                                  char delim)
          This returns a new tokenizer based on one of our tokens. The 
geometric datatypes use this to process nested tokens (usually 
PGpoint).
        Parameters:
                n - Token number ( 0 ... getSize()-1 )
                delim - The delimiter to use
        Returns:
                A new instance of PGtokenizer based on the token
 public static String remove(String s,
                             String l,
                             String t)
          This removes the lead/trailing strings from a string
        Parameters:
                s - Source string
                l - Leading string to remove
                t - Trailing string to remove
                
        Returns:
                String without the lead/trailing strings
 public void remove(String l,
                    String t)
          This removes the lead/trailing strings from all tokens
        Parameters:
                l - Leading string to remove
                t - Trailing string to remove
 public static String removePara(String s)
          Removes ( and ) from the beginning and end of a string
        Parameters:
                s - String to remove from
        Returns:
                String without the ( or )
 public void removePara()
          Removes ( and ) from the beginning and end of all tokens
        Returns:
                String without the ( or )
 public static String removeBox(String s)
   
          Removes [ and ] from the beginning and end of a string
        Parameters:
                s - String to remove from
   
        Returns:
                String without the [ or ]
 public void removeBox()
          Removes [ and ] from the beginning and end of all tokens
        Returns:
                String without the [ or ]
 public static String removeAngle(String s)
          Removes < and > from the beginning and end of a string
        Parameters:
                s - String to remove from
        Returns:
                String without the < or >
 public void removeAngle()
          Removes < and > from the beginning and end of all tokens
        Returns:
                String without the < or >
Class postgresql.util.Serialize
This was documented earlier under Object Serialisation.
Class postgresql.util.UnixCrypt
              
java.lang.Object
   |
   +----postgresql.util.UnixCrypt
   public class UnixCrypt extends Object
   This class provides us with the ability to encrypt passwords when 
sent over the network stream
   Contains static methods to encrypt and compare passwords with Unix 
encrypted passwords.
   See John Dumas's Java Crypt page for the original source.
   http://www.zeh.com/local/jfd/crypt.html
Methods
 public static final String crypt(String salt,
                                  String original)
          Encrypt a password given the cleartext password and a 
"salt".
   
        Parameters:
                salt - A two-character string representing the salt 
used
                to iterate the encryption engine in lots of different
                ways. If you are generating a new encryption then this
                value should be randomised.
                original - The password to be encrypted.
        Returns:
                A string consisting of the 2-character salt followed 
by
                the encrypted password.
              
 public static final String crypt(String original)
          Encrypt a password given the cleartext password. This method 
generates a random salt using the 'java.util.Random' class.
        Parameters:
                original - The password to be encrypted.
   
        Returns: 
                A string consisting of the 2-character salt followed 
by
                the encrypted password.
               
 public static final boolean matches(String encryptedPassword,
                                     String enteredPassword)
                 
          Check that enteredPassword encrypts to encryptedPassword.
               
        Parameters:
                encryptedPassword - The encryptedPassword. The first 
two characters are assumed to be the salt. This string would be the 
same as one found in a Unix /etc/passwd file.
                enteredPassword - The password as entered by the user 
(or otherwise aquired).
        Returns:
                true if the password should be considered correct.
Using the driver in a multi Threaded or Servlet environment
A problem with many <acronym>JDBC</acronym> drivers, is that only one thread can use a 
Connection at any one time - otherwise a thread could send a query 
while another one is receiving results, and this would be a bad thing 
for the database engine.
PostgreSQL 6.4, brings thread safety to the entire driver. Standard 
<acronym>JDBC</acronym> was thread safe in 6.3.x, but the Fastpath <acronym>API</acronym> wasn't.
So, if your application uses multiple threads (which most decent ones 
would), then you don't have to worry about complex schemes to ensure 
only one uses the database at any time.
If a thread attempts to use the connection while another is using it, 
it will wait until the other thread has finished it's current 
operation.
If it's a standard SQL statement, then the operation is sending the 
statement, and retrieving any ResultSet (in full).
If it's a Fastpath call (ie: reading a block from a LargeObject), then 
it's the time to send, and retrieve that block.
This is fine for applications & applets, but can cause a performance 
problem with servlets.
With servlets, you can have a heavy load on the connection. If you 
have several threads performing queries, then each one will pause, 
which may not be what you are after.
To solve this, you would be advised to create a pool of Connections.
When ever a thread needs to use the database, it asks a manager class 
for a Connection. It hands a free connection to the thread, and marks 
it as busy. If a free connection is not available, it opens one.
Once the thread has finished with it, it returns it to the manager, 
who can then either close it, or add it to the pool. The manager would 
also check that the connection is still alive, and remove it from the 
pool if it's dead.
So, with servlets, it's up to you to use either a single connection, 
or a pool. The plus side for a pool is that threads will not be hit by 
the bottle neck caused by a single network connection. The down side, 
is that it increases the load on the server, as a backend is created 
for each Connection.
It's up to you, and your applications requirements.
</programlisting>
</para>
</sect1>
<sect1>
<title>Further Reading</title>
<para>
If you have not yet read it, I'd advise you read the <acronym>JDBC</acronym>
 <acronym>API</acronym> 
Documentation (supplied with Sun's <acronym>JDK</acronym>),
 and the <acronym>JDBC</acronym> Specification. 
Both are available on 
<ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>.
</para>
<para>
<ulink url="http://www.retep.org.uk">My own web site</ulink>
 contains updated information not included in this 
document, and also includes precompiled drivers for v6.4, and earlier.
</para>
</sect1>
</chapter>

						