postgresql/doc/src/sgml/jdbc.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.19 2001/02/24 12:40:27 petere Exp $
-->

 <chapter id="jdbc">
  <title><acronym>JDBC</acronym> Interface</title>

  <note>
   <title>Author</title>
   <para>
    Written by Peter T. Mount (<email>peter@retep.org.uk</email>), the
    author of the <acronym>JDBC</acronym> driver.
   </para>
  </note>

  <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 <firstterm>type
   4</firstterm> <acronym>JDBC</acronym> Driver.  Type 4 indicates
   that the driver is written in Pure Java, and communicates in the
   database system's own network protocol. Because of this, the driver
   is platform independent; once compiled, the driver can be used on
   any system.
  </para>

  <para>
   This chapter 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.
   Also, take a look at the examples included with the source. The
   basic example is used here.
  </para>

 <sect1 id="jdbc-setup">
  <title>Setting up the <acronym>JDBC</acronym> Driver</title>

  <sect2 id="jdbc-build">
   <title>Building the Driver</title>

   <para>
    Precompiled versions of the driver are regularly made available on
    the <ulink
    url="http://jdbc.postgresql.org"><productname>PostgreSQL</productname>
    <acronym>JDBC</acronym> web site</ulink>.  Here we describe how to
    build the driver manually.
   </para>

   <para>
    Starting with <productname>PostgreSQL</productname> version 7.1,
    the preferred way to build the <acronym>JDBC</acronym> driver is
    using <productname>Ant</productname>, a special tool for building
    Java-based packages.  You should download
    <productname>Ant</productname> from the <ulink
    url="http://jakarta.apache.org/ant/index.html"><productname>Ant</productname>
    web site</ulink> and install it before proceeding.
   </para>

   <para>
    The build the driver, issue the command
<screen>
<prompt>$</prompt> <userinput>ant</userinput>
</screen>
    in the top level directory of the
    <productname>PostgreSQL</productname> source distribution.
   </para>

   <para>
    To install the driver, enter the command
<screen>
<prompt>$</prompt> <userinput>ant -Dinstall.directory=<replaceable>mydir</replaceable> install</userinput>
</screen>
    Replace <replaceable>mydir</replaceable> with a directory name of
    your choice; the directory will be created if necessary.  The
    <productname>PostgreSQL</productname> <acronym>JDBC</acronym>
    driver consists of a <filename>postgresql.jar</filename> file that
    will be copied to that directory.
   </para>

   <para>
    Alternatively, you can use the old <command>make</command>-based
    interface.  The driver's source is located in the <filename
    class="directory">src/interfaces/jdbc</filename> directory of the
    source tree. To compile, simply change directory to that
    directory, and type:
<screen>
<prompt>$</prompt> <userinput>gmake</userinput>
</screen>
    (Remember to use <acronym>GNU</acronym> make.)  Upon completion,
    you will find the archive <filename>postgresql.jar</filename> in
    the current directory. This is the <acronym>JDBC</acronym> driver,
    which you can copy to an appropriate directory in your system.
   </para>

   <note>
    <para>
     You must not use <command>javac</command> directly, as the
     driver uses some dynamic loading techniques for performance
     reasons, and <command>javac</command> cannot cope.
    </para>
   </note>
  </sect2>

  <sect2 id="jdbc-classpath">
   <title>Setting up the Class Path</title>

   <para>
    To use the driver, the jar archive
    <filename>postgresql.jar</filename> needs to be included in the
    class path, either by putting it in the <envar>CLASSPATH</envar>
    environment variable, or by using flags on the
    <command>java</command> command line.
   </para>

   <informalexample>
    <para>
     For instance, 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
     <acronym>JDBC</acronym> driver installed in the <filename
     class="directory">/usr/local/lib</filename> directory, and the
     Java <acronym>JDK</acronym> installed in
     <filename>/usr/local/jdk1.1.6</filename>.  To run the
     application, I would use:
<programlisting>
export CLASSPATH=/usr/local/lib/finder.jar<co id="co.jdbc-finder">:/usr/local/lib/postgresql.jar:.
java uk.org.retep.finder.Main
</programlisting>
     <calloutlist>
      <callout arearefs="co.jdbc-finder">
       <para>
        <filename>finder.jar</filename> contains my application.
       </para>
      </callout>
     </calloutlist>
    </para>

    <para>
     Loading the driver from within the application is covered in
     <xref linkend="jdbc-use">.
    </para>
   </informalexample>
  </sect2>

  <sect2 id="jdbc-prepare">
   <title>Preparing the Database for <acronym>JDBC</acronym></title>

   <para>
    Because Java can only use TCP/IP connections, the
    <application>Postgres</application> server must be configured to
    accept TCP/IP connections, for instance by supplying the
    <option>-i</option> option flag when starting the
    <command>postmaster</command>.
   </para>

   <para>
    Also, the client authentication setup in the
    <filename>pg_hba.conf</filename> file may need to be configured.
    Refer to the <citetitle>Administrator's Guide</citetitle> for
    details.  The <acronym>JDBC</acronym> Driver supports trust,
    ident, password, and crypt authentication methods.
   </para>
  </sect2>
 </sect1>

 <sect1 id="jdbc-use">
  <title>Using the Driver</title>

  <sect2 id="jdbc-import">
   <title>Importing <acronym>JDBC</acronym></title>

   <para>
    Any source that uses <acronym>JDBC</acronym> needs to import the
    <literal>java.sql</literal> package, using:

<programlisting>
import java.sql.*;
</programlisting>

    <important>
     <para>
      Do not import the <literal>org.postgresql</literal> package. If
      you do, your source will not compile, as
      <command>javac</command> will get confused.
     </para>
    </important>
   </para>
  </sect2>

  <sect2 id="jdbc-load">
   <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 which is the best one to use.
   </para>

   <para>
    In the first method, your code implicitly loads the driver using the
    <function>Class.forName()</function> method.
    For <application>Postgres</application>, you would use:

<programlisting>
Class.forName("org.postgresql.Driver");
</programlisting>

    This will load the driver, and while loading, the driver will automatically
    register itself with <acronym>JDBC</acronym>.

    <note>
     <para>
      The <function>forName()</function> method can throw a
      <classname>ClassNotFoundException</classname> if the driver is
      not available.
     </para>
    </note>
   </para>

   <para>
    This is the most common method to use, but restricts your code to
    use just <productname>Postgres</productname>.  If your code may
    access another database system in the future, and you do not use
    any <productname>Postgres</productname>-specific extensions, then
    the second method is advisable.
   </para>

   <para>
    The second method passes the driver as a parameter to the
    <acronym>JVM</acronym> as it starts, using the <option>-D</option>
    argument. Example:
<programlisting>
java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer
</programlisting>
    In this example, the <acronym>JVM</acronym> will attempt to load
    the driver as part of its initialization. Once done, the
    <classname>ImageViewer</classname> is started.
   </para>

   <para>
    Now, this method is the better one to use because it allows your
    code to be used with other database packages without recompiling
    the code. The only thing that would also change is the connection
    <acronym>URL</acronym>, which is covered next.
   </para>

   <para>
    One last thing: When your code then tries to open a
    <classname>Connection</classname>, and you get a <errorname>No
    driver available</errorname> <classname>SQLException</classname>
    being thrown, this is probably caused by the driver not being in
    the class path, or the value in the parameter not being correct.
   </para>
  </sect2>

  <sect2 id="jdbc-connect">
   <title>Connecting to the Database</title>

   <para>
    With <acronym>JDBC</acronym>, a database is represented by a
    <acronym>URL</acronym> (Uniform Resource Locator).  With
    <application>Postgres</application>, this takes one of the
    following forms:

    <itemizedlist>
     <listitem>
<synopsis>
jdbc:postgresql:<replaceable class="parameter">database</replaceable>
</synopsis>
     </listitem>

     <listitem>
<synopsis>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
</synopsis>
     </listitem>

     <listitem>
<synopsis>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
</synopsis>
     </listitem>
    </itemizedlist>

    where:

    <variablelist>
     <varlistentry>
      <term>
       <replaceable class="parameter">host</replaceable>
      </term>
      <listitem>
       <para>
        The host name of the server. Defaults to <literal>localhost</literal>.
       </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 <classname>Connection</classname> instance from 
    <acronym>JDBC</acronym>. To do this,
    you would use the <function>DriverManager.getConnection()</function> method:

<programlisting>
Connection db = DriverManager.getConnection(url, username, password);
</programlisting>
   </para>
  </sect2>

  <sect2 id="jdbc-disconnect">
   <title>Closing the Connection</title>

   <para>
    To close the database connection, simply call the
    <function>close()</function> method to the <classname>Connection</classname>:
<programlisting>
db.close();
</programlisting>
   </para>
  </sect2>
 </sect1>


  <sect1 id="jdbc-query">
   <title>Issuing a Query and Processing the Result</title>

   <para>
    Any time you want to issue <acronym>SQL</acronym> statements to
    the database, you require a <classname>Statement</classname>
    instance. Once you have a <classname>Statement</classname>, you
    can use the <function>executeQuery()</function> method to issue a
    query. This will return a <classname>ResultSet</classname>
    instance, which contains the entire result.  <xref
    linkend="jdbc-query-example"> illustrates this process.
   </para>

   <example id="jdbc-query-example">
    <title>Processing a Simple Query in <acronym>JDCB</acronym></title>

    <para>
     This example with issue a simple query and print out the first
     column of each row.
<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>
   </example>

   <sect2>
    <title>Using the <classname>Statement</classname> Interface</title>

    <para>
     The following must be considered when using the
     <classname>Statement</classname> interface:

     <itemizedlist>
      <listitem>
       <para>
        You can use a single <classname>Statement</classname> instance
        as many times as you want. You could create one as soon as you
        open the connection and use it for the connection's
        lifetime. But you have to remember that only one
        <classname>ResultSet</classname> can exist per
        <classname>Statement</classname>.
       </para>
      </listitem>

      <listitem>
       <para>
        If you need to perform a query while processing a
        <classname>ResultSet</classname>, you can simply create and
        use another <classname>Statement</classname>.
       </para>
      </listitem>

      <listitem>
       <para>
        If you are using threads, and several are using the database,
        you must use a separate <classname>Statement</classname> for
        each thread. Refer to <xref linkend="jdbc-thread"> if you are
        thinking of using threads, as it covers some important points.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </sect2>

   <sect2>
    <title>Using the <classname>ResultSet</classname> Interface</title>

    <para>
     The following must be considered when using the
     <classname>ResultSet</classname> 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> specification, you should
        access a field only once. It is safest to stick to this rule,
        although at the current time, the
        <productname>Postgres</productname> driver will allow you to
        access a field as many times as you want.
       </para>
      </listitem>

      <listitem>
       <para>
        You must close a <classname>ResultSet</classname> by calling
        <function>close()</function> once you have finished using it.
       </para>
      </listitem>

      <listitem>
       <para>
        Once you make another query with the
        <classname>Statement</classname> used to create a
        <classname>ResultSet</classname>, the currently open
        <classname>ResultSet</classname> instance is closed
        automatically.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </sect2>
  </sect1>

  <sect1 id="jdbc-update">
   <title>Performing Updates</title>

   <para>
    To perform an update (or any other <acronym>SQL</acronym>
    statement that does not return a result), you simply use the
    <function>executeUpdate()</function> method:

<programlisting>
st.executeUpdate("CREATE TABLE basic (a int, b int)");
</programlisting>
   </para>
  </sect1>

 <sect1 id="jdbc-lo">
  <title>Using Large Objects</title>

  <para>
   In <application>Postgres</application>, <firstterm>Large
   Objects</firstterm> (also known as <acronym>BLOB</acronym>s) are
   used to hold data in the database that cannot be stored in a normal
   SQL table. They are stored in a separate table in a special format,
   and are referred to from your own tables by an OID value.
  </para>

  <important>
   <para>
    For <productname>Postgres</productname>, you must access Large
    Objects within an <acronym>SQL</acronym> transaction.  You would
    open a transaction by using the
    <function>setAutoCommit()</function> method with an input
    parameter of <literal>false</literal>:
<programlisting>
Connection mycon;
...
mycon.setAutoCommit(false);
... // now use Large Objects
</programlisting>
   </para>
  </important>

   <para>
    There are two methods of using Large Objects. The first is the
    standard <acronym>JDBC</acronym> way, and is documented here. The
    other, uses <productname>PostgreSQL</productname> extensions to
    the <acronym>API</acronym>, 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 Large
    Objects is using the <function>getBinaryStream()</function> method
    in <classname>ResultSet</classname>, and
    <function>setBinaryStream()</function> method in
    <classname>PreparedStatement</classname>. These methods make the
    large object appear as a Java stream, allowing you to use the
    <literal>java.io</literal> package, and others, to manipulate the
    object.  <xref linkend="jdbc-lo-example"> illustrates the usage of
    this approach.
   </para>

  <example id="jdbc-lo-example">
   <title>Using the <acronym>JDBC</acronym> Large Object Interface</title>

   <para>
    For example, suppose you have a table containing the file name of
    an image and you have a large object containing that image:
<programlisting>
CREATE TABLE images (imgname text, 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 (?, ?)"); <co id="co.jdbc-qmark">
ps.setString(1, file.getName());
ps.setBinaryStream(2, fis, file.length());
ps.executeUpdate();
ps.close();
fis.close();
</programlisting>
    <calloutlist>
     <callout arearefs="co.jdbc-qmark">
      <para>
       The question marks must appear literally.  The actual data is
       substituted by the next lines.
      </para>
     </callout>
    </calloutlist>
    Here, <function>setBinaryStream</function> 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.  Notice that the
    creation of the Large Object itself in the database happens
    transparently.
   </para>

   <para>
    Retrieving an image is even easier.  (We use
    <classname>PreparedStatement</classname> here, but the
    <classname>Statement</classname> class 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>
    Here you can see how the Large Object is retrieved as an
    <classname>InputStream</classname>.  You will 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 <classname>InputStream</classname> returned
    is closed when <function>ResultSet.next()</function> or
    <function>ResultSet.close()</function> is called.
   </para>
  </example>
 </sect1>


 <sect1 id="jdbc-ext">
  <title><application>PostgreSQL</application> Extensions to the
    <acronym>JDBC</acronym> <acronym>API</acronym></title>

  <para>
   <productname>Postgres</productname> 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.  As
   these are facilities unique to <productname>Postgres</productname>,
   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.
  </para>

  <sect2>
   <title>Accessing the Extensions</title>

   <para>
    To access some of the extensions, you need to use some extra
    methods in the <classname>org.postgresql.Connection</classname>
    class. In this case, you would need to case the return value of
    <function>Driver.getConnection()</function>.  For example:
<programlisting>
Connection db = Driver.getConnection(url, username, password);
// ...
// later on
Fastpath fp = ((org.postgresql.Connection)db).getFastpathAPI();
</programlisting>
   </para>

   <sect3>
    <title>Class <classname>org.postgresql.Connection</classname></title>

<synopsis>
public class Connection extends Object implements Connection

java.lang.Object
   |
   +----org.postgresql.Connection
</synopsis>

    <para>
     These are the extra methods used to gain access to
     <productname>PostgreSQL</productname>'s extensions. Methods
     defined by <classname>java.sql.Connection</classname> are not
     listed.
    </para>

    <sect4>
     <title>Methods</title>

     <itemizedlist>
      <listitem>
<synopsis>
public Fastpath getFastpathAPI() throws SQLException
</synopsis>
       <para>
        This returns the Fastpath <acronym>API</acronym> for the
        current connection.  It is primarily used by the Large Object
        <acronym>API</acronym>.
       </para>

       <para>
        The best way to use this is as follows:
<programlisting>
import org.postgresql.fastpath.*;
...
Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();
</programlisting>
        where myconn is an open Connection to <productname>PostgreSQL</productname>.
       </para>

       <formalpara>
        <title>Returns:</title>
        <para>
         Fastpath object allowing access to functions on the
         <productname>PostgreSQL</productname> backend.
        </para>
       </formalpara>

       <formalpara>
        <title>Throws:</title>
        <para>
         SQLException by Fastpath when initializing for first time
        </para>
       </formalpara>
      </listitem>

      <listitem>
       <para>
<synopsis>
public LargeObjectManager getLargeObjectAPI() throws SQLException
</synopsis>
        This returns the Large Object <acronym>API</acronym> for the
        current connection.
       </para>

       <para>
        The best way to use this is as follows:
<programlisting>
import org.postgresql.largeobject.*;
...
LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
</programlisting>
        where myconn is an open Connection to
        <productname>PostgreSQL</productname>.
       </para>

       <formalpara>
        <title>Returns:</title>
        <para>
         LargeObject object that implements the <acronym>API</acronym>
        </para>
       </formalpara>

       <formalpara>
        <title>Throws:</title>
        <para>
         SQLException by LargeObject when initializing for first time
        </para>
       </formalpara>
      </listitem>

      <listitem>
       <para>
<synopsis>
public void addDataType(String type, String name)
</synopsis>
        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.
       </para>

       <para>
        The best way to use this is as follows:
<programlisting>
 ...
((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name");
 ...
</programlisting>
        where myconn is an open Connection to
        <productname>PostgreSQL</productname>.  The handling class must
        extend <classname>org.postgresql.util.PGobject</classname>.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>


   <sect3>
    <title>Class <classname>org.postgresql.Fastpath</classname></title>

<synopsis>
public class Fastpath extends Object

java.lang.Object
   |
   +----org.postgresql.fastpath.Fastpath
</synopsis>

    <para>
     <classname>Fastpath</classname> 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 is provided because the
     Large Object <acronym>API</acronym> uses it.
    </para>

    <para>
     To use, you need to import the
     <classname>org.postgresql.fastpath</classname> package, using the
     line:
<programlisting>
import org.postgresql.fastpath.*;
</programlisting>
     Then, in your code, you need to get a
     <classname>FastPath</classname> object:
<programlisting>
Fastpath fp = ((org.postgresql.Connection)conn).getFastpathAPI();
</programlisting>
     This will return an instance associated with the database
     connection that you can use to issue commands. The casing of
     <classname>Connection</classname> to
     <classname>org.postgresql.Connection</classname> is required, as
     the <function>getFastpathAPI()</function> is an extension method,
     not part of <acronym>JDBC</acronym>.  Once you have a
     <classname>Fastpath</classname> instance, you can use the
     <function>fastpath()</function> methods to execute a backend
     function.
    </para>

    <formalpara>
     <title>See Also:</title>
     <para>
      <classname>FastpathFastpathArg</classname>, <classname>LargeObject</classname>
     </para>
    </formalpara>

    <sect4>
     <title>Methods</title>

     <itemizedlist>
      <listitem>
<synopsis>
public Object fastpath(int fnid,
                       boolean resulttype,
                       FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        Send a function call to the PostgreSQL backend.
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
                fnid - Function id
                resulttype - True if the result is an integer, false 
for
                other results
                args - FastpathArguments to pass to fastpath
        </para>
       </formalpara>

       <formalpara>
        <title>Returns:</title>
        <para>
         null if no data, Integer if an integer result, or byte[]
         otherwise
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public Object fastpath(String name,
                       boolean resulttype,
                       FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        Send a function call to the PostgreSQL backend by name.
       </para>

       <note>
        <para>
         The mapping for the procedure name to function id needs to
         exist, usually to an earlier call to addfunction(). This is
         the preferred method to call, as function id's can/may change
         between versions of the backend. For an example of how this
         works, refer to org.postgresql.LargeObject
        </para>
       </note>

       <formalpara>
        <title>Parameters:</title>
        <para>
                name - Function name
                resulttype - True if the result is an integer, false 
for
                other results
                args - FastpathArguments to pass to fastpath
        </para>
       </formalpara>

       <formalpara>
        <title>Returns:</title>
        <para>
         null if no data, Integer if an integer result, or byte[]
         otherwise
        </para>
       </formalpara>

       <formalpara>
        <title>See Also:</title>
        <para><classname>LargeObject</classname></para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>          
public int getInteger(String name,
                      FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        This convenience method assumes that the return value is an Integer
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
                name - Function name
                args - Function arguments
        </para>
       </formalpara>

       <formalpara>
        <title>Returns:</title>
        <para>integer result</para>
       </formalpara>

       <formalpara>
        <title>Throws:</title>
        <para>
         SQLException if a database-access error occurs or no result
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public byte[] getData(String name,
                      FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        This convenience method assumes that the return value is binary
        data.
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
                name - Function name
                args - Function arguments
        </para>
       </formalpara>

       <formalpara>
        <title>Returns:</title>
        <para>byte[] array containing result</para>
       </formalpara>

       <formalpara>
        <title>Throws:</title>
        <para>
         SQLException if a database-access error occurs or no result
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public void addFunction(String name,
                        int fnid)
</synopsis>
       <para>
        This adds a function to our look-up table.  User code should
        use the <function>addFunctions</function> 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.
       </para>
      </listitem>

      <listitem>
<synopsis>
public void addFunctions(ResultSet rs) throws SQLException
</synopsis>
       <para>
        This takes a <classname>ResultSet</classname> containing two columns. Column 1
        contains the function name, Column 2 the oid.  It reads the
        entire <classname>ResultSet</classname>, loading the values into the function table.
       </para>

       <important>
        <para>
         Remember to <function>close()</function> the
         <classname>ResultSet</classname> after calling this!
        </para>
       </important>

       <note>
        <title>Implementation note about function name look-ups</title>

        <para>
         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 <classname>Hashtable</classname> is used. Also, only the function's
         required are entered into this table, keeping connection
         times as fast as possible.
        </para>

        <para>
         The <classname>org.postgresql.LargeObject</classname> class
         performs a query upon its start-up, and passes the returned
         <classname>ResultSet</classname> to the
         <function>addFunctions()</function> method here.  Once this
         has been done, the Large Object <acronym>API</acronym> refers
         to the functions by name.
        </para>

        <para>
         Do not think that manually converting them to the oid's will
         work. Okay, 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.
        </para>
       </note>

       <formalpara>
        <title>See Also:</title>
        <para>
         <classname>LargeObjectManager</classname>
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public int getID(String name) throws SQLException
</synopsis>
       <para>
        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.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>


   <sect3>
    <title>Class <classname>org.postgresql.fastpath.FastpathArg</classname></title>

<synopsis>
public class FastpathArg extends Object

java.lang.Object
   |
   +----org.postgresql.fastpath.FastpathArg
</synopsis>

    <para>
     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.
    </para>

    <para>
     For an example on how to use this, refer to the
     <classname>org.postgresql.LargeObject</classname> package.
    </para>

    <formalpara>
     <title>See Also:</title>
     <para>
      <classname>Fastpath</classname>, <classname>LargeObjectManager</classname>, <classname>LargeObject</classname>
     </para>
    </formalpara>

    <sect4>
     <title>Constructors</title>

     <itemizedlist>
      <listitem>
<synopsis>
public FastpathArg(int value)
</synopsis>
       <para>
        Constructs an argument that consists of an integer value
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
         value - int value to set
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public FastpathArg(byte bytes[])
</synopsis>
       <para>
        Constructs an argument that consists of an array of bytes
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
         bytes - array to store
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public FastpathArg(byte buf[],
                   int off,
                   int len)
</synopsis>
       <para>
        Constructs an argument that consists of part of a byte array
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
         <variablelist>
          <varlistentry>
           <term>buf</term>
           <listitem>
            <simpara>source array</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>off</term>
           <listitem>
            <simpara>offset within array</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>len</term>
           <listitem>
            <simpara>length of data to include</simpara>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public FastpathArg(String s)
</synopsis>
       <para>
        Constructs an argument that consists of a String.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>
  </sect2>


  <sect2>
   <title>Geometric Data Types</title>

   <para>
    <productname>PostgreSQL</productname> has a set of data types that
    can store geometric features into a table. These include single
    points, lines, and polygons.  We support these types in Java with
    the org.postgresql.geometric package.  It contains classes that
    extend the org.postgresql.util.PGobject class.  Refer to that
    class for details on how to implement your own data type handlers.
   </para>

<programlisting>
Class org.postgresql.geometric.PGbox

java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.postgresql.geometric.PGbox

   public class PGbox extends PGobject implements Serializable, 
Cloneable

   This represents the box data type within <productname>PostgreSQL</productname>.

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 
overridden, 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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject
   
 public String getValue()
        
        Returns:
                the PGbox in the syntax expected by <productname>PostgreSQL</productname>

        Overrides:
                getValue in class PGobject

<!-- **************************************************************** -->
Class org.postgresql.geometric.PGcircle

java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.postgresql.geometric.PGcircle
        
   public class PGcircle extends PGobject implements Serializable, 
Cloneable
               
   This represents <productname>PostgreSQL</productname>'s circle data type, consisting of a point 
and a radius

Variables

 public PGpoint center
           
          This is the center point
 
public double radius
           
          This is the radius
   
Constructors   

 public PGcircle(double x,
                 double y,
                 double r)
          
        Parameters:
               x - coordinate of center
                y - coordinate of center
                r - radius of circle

 public PGcircle(PGpoint c,
                 double r)
          
        Parameters:
                c - PGpoint describing the circle's center
                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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject

 public String getValue()

        Returns:
                the PGcircle in the syntax expected by <productname>PostgreSQL</productname>
        
        Overrides:
                getValue in class PGobject

<!-- **************************************************************** -->
Class org.postgresql.geometric.PGline

java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.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()

          required 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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject

 public String getValue()
   
        Returns:
                the PGline in the syntax expected by <productname>PostgreSQL</productname>
        
        Overrides:
                getValue in class PGobject

<!-- **************************************************************** -->
Class org.postgresql.geometric.PGlseg
             
java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.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()

          required 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 overridden to allow the object to be cloned

        Overrides:
               clone in class PGobject

 public String getValue()

        Returns:
                the PGlseg in the syntax expected by <productname>PostgreSQL</productname>
        
        Overrides:
                getValue in class PGobject

<!-- **************************************************************** -->
Class org.postgresql.geometric.PGpath
                                
java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.postgresql.geometric.PGpath
          
   public class PGpath extends PGobject implements Serializable, 
Cloneable
               
   This implements a path (a multiply 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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject

 public String getValue()

          This returns the polygon in the syntax expected by 
<productname>PostgreSQL</productname>

        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 org.postgresql.geometric.PGpoint
                                
java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.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 data type in <productname>PostgreSQL</productname>.

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 embedded 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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject
          
 public String getValue()       
    
        Returns:
                the PGpoint in the syntax expected by <productname>PostgreSQL</productname>

        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 org.postgresql.geometric.PGpolygon
                                
java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.postgresql.geometric.PGpolygon

   public class PGpolygon extends PGobject implements Serializable, 
Cloneable
               
   This implements the polygon data type 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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject
                 
 public String getValue()

        Returns:
                the PGpolygon in the syntax expected by <productname>PostgreSQL</productname>

        Overrides:
                getValue in class PGobject
</programlisting>
  </sect2>


  <sect2>
   <title>Large Objects</title>

   <para>
    Large objects are supported in the standard
    <acronym>JDBC</acronym> specification.  However, that interface is
    limited, and the <acronym>API</acronym> provided by PostgreSQL allows for random
    access to the objects contents, as if it was a local file.
   </para>

   <para>
    The org.postgresql.largeobject package provides to Java the libpq
    C interface's large object <acronym>API</acronym>. It consists of
    two classes, <classname>LargeObjectManager</classname>, which deals with creating,
    opening and deleting large objects, and <classname>LargeObject</classname> which deals
    with an individual object.
   </para>

   <sect3>
    <title>Class <classname>org.postgresql.largeobject.LargeObject</classname></title>

<synopsis>
public class LargeObject extends Object

java.lang.Object
   |
   +----org.postgresql.largeobject.LargeObject
</synopsis>

    <para>
     This class implements the large object interface to
     <productname>PostgreSQL</productname>.
    </para>

    <para>
     It provides the basic methods required to run the interface, plus
     a pair of methods that provide <classname>InputStream</classname> and <classname>OutputStream</classname>
     classes for this object.
    </para>

    <para>
     Normally, client code would use the getAsciiStream,
     getBinaryStream, or getUnicodeStream methods in <classname>ResultSet</classname>, or
     setAsciiStream, setBinaryStream, or setUnicodeStream methods in
     <classname>PreparedStatement</classname> to access Large Objects.
    </para>

    <para>
     However, sometimes lower level access to Large Objects are
     required, that are not supported by the <acronym>JDBC</acronym>
     specification.
    </para>

    <para>
     Refer to org.postgresql.largeobject.LargeObjectManager on how to
     gain access to a Large Object, or how to create one.
    </para>

    <formalpara>
     <title>See Also:</title>
     <para><classname>LargeObjectManager</classname></para>
    </formalpara>

    <sect4>
     <title>Variables</title>

     <variablelist>
      <varlistentry>
       <term>public static final int SEEK_SET</term>
       <listitem>
        <para>Indicates a seek from the beginning of a file</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>public static final int SEEK_CUR</term>
       <listitem>
        <para>Indicates a seek from the current position</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>public static final int SEEK_END</term>
       <listitem>
        <para>Indicates a seek from the end of a file</para>
       </listitem>
      </varlistentry>
     </variablelist>
    </sect4>

    <sect4>
     <title>Methods</title>

     <itemizedlist>
      <listitem>
<synopsis>
public int getOID()
</synopsis>
       <para>
        Returns the OID of this <classname>LargeObject</classname>
       </para>
      </listitem>

      <listitem>
<synopsis>
public void close() throws SQLException
</synopsis>
       <para>
        This method closes the object. You must not call methods in
        this object after this is called.
       </para>
      </listitem>

      <listitem>
<synopsis>
public byte[] read(int len) throws SQLException
</synopsis>
       <para>
        Reads some data from the object, and return as a byte[] array
       </para>
      </listitem>

      <listitem>
<synopsis>
public void read(byte buf[],
                 int off,
                 int len) throws SQLException
</synopsis>
       <para>
        Reads some data from the object into an existing array
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
         <variablelist>
          <varlistentry>
           <term>buf</term>
           <listitem>
            <simpara>destination array</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>off</term>
           <listitem>
            <simpara>offset within array</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>len</term>
           <listitem>
            <simpara>number of bytes to read</simpara>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>
public void write(byte buf[]) throws SQLException
</synopsis>
       <para>
        Writes an array to the object
       </para>
      </listitem>

      <listitem>
<synopsis>
public void write(byte buf[],
                  int off,
                  int len) throws SQLException
</synopsis>
       <para>
        Writes some data from an array to the object
       </para>

       <formalpara>
        <title>Parameters:</title>
        <para>
         <variablelist>
          <varlistentry>
           <term>buf</term>
           <listitem>
            <simpara>destination array</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>off</term>
           <listitem>
            <simpara>offset within array</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term>len</term>
           <listitem>
            <simpara>number of bytes to write</simpara>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </formalpara>
      </listitem>

<!--
 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.
-->
     </itemizedlist>
    </sect4>
   </sect3>


   <sect3>
    <title>Class <classname>org.postgresql.largeobject.LargeObjectManager</classname></title>

<synopsis>                                
public class LargeObjectManager extends Object

java.lang.Object
   |
   +----org.postgresql.largeobject.LargeObjectManager
</synopsis>

    <para>
     This class implements the large object interface to
     <productname>PostgreSQL</productname>.  It provides methods that
     allow client code to create, open and delete large objects from
     the database. When opening an object, an instance of
     <classname>org.postgresql.largeobject.LargeObject</classname> is
     returned, and its methods then allow access to the object.
    </para>

    <para>
     This class can only be created by org.postgresql.Connection.  To
     get access to this class, use the following segment of code:
<programlisting>
import org.postgresql.largeobject.*;
Connection  conn;
LargeObjectManager lobj;
// ... code that opens a connection ...
lobj = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
</programlisting>
    </para>

    <para>
     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.
    </para>

    <para>
     Refer to org.postgresql.largeobject.LargeObject on how to
     manipulate the contents of a Large Object.
    </para>

    <sect4>
     <title>Variables</title>

     <variablelist>
      <varlistentry>
       <term>public static final int WRITE</term>
       <listitem>
        <simpara>This mode indicates we want to write to an object.</simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>public static final int READ</term>
       <listitem>
        <simpara>This mode indicates we want to read an object.</simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>public static final int READWRITE</term>
       <listitem>
        <simpara>This mode is the default. It indicates we want read and write access to a large object.</simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </sect4>

    <sect4>
     <title>Methods</title>

     <itemizedlist>
      <listitem>
<synopsis>
public LargeObject open(int oid) throws SQLException
</synopsis>
       <para>
        This opens an existing large object, based on its OID. This
        method assumes that READ and WRITE access is required (the
        default).
       </para>
      </listitem>

      <listitem>
<synopsis>
public LargeObject open(int oid,
                        int mode) throws SQLException
</synopsis>
       <para>
        This opens an existing large object, based on its OID, and
        allows setting the access mode.
       </para>
      </listitem>

      <listitem>
<synopsis>
public int create() throws SQLException
</synopsis>
       <para>
        This creates a large object, returning its OID.
        It defaults to READWRITE for the new object's attributes.
       </para>
      </listitem>

      <listitem>
<synopsis>
public int create(int mode) throws SQLException
</synopsis>
       <para>
        This creates a large object, returning its OID, and sets the
        access mode.
       </para>
      </listitem>

      <listitem>
<synopsis>
public void delete(int oid) throws SQLException
</synopsis>
       <para>          
        This deletes a large object.
       </para>
      </listitem>

      <listitem>
<synopsis>
public void unlink(int oid) throws SQLException
</synopsis>
       <para>
        This deletes a large object.  It is identical to the delete
        method, and is supplied as the C <acronym>API</acronym> uses
        <quote>unlink</quote>.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>
  </sect2>


  <sect2>
   <title>Object Serialization</title>

   <para>
    <productname>PostgreSQL</productname> is not a normal
    <acronym>SQL</acronym> database.  It is more extensible than most
    other databases, and does support object oriented features that
    are unique to it.
   </para>

   <para>
    One of the consequences of this, is that you can have one table
    refer to a row in another table.  For example:
<screen>
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)
</screen>
    Okay, 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.
   </para>

   <para>
    What does this have to do with Java?
   </para>

   <para>
    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.
   </para>

   <para>
    Now, under <acronym>JDBC</acronym>, you would have to use a
    Large Object to store them.  However, you cannot perform queries on
    those objects.
   </para>

   <para>
    What the org.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.
   </para>

   <para>
    Sound's complicated? In fact, it's simpler than what I wrote -
    it's just difficult to explain.
   </para>

   <para>
    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.
   </para>

   <para>
    Oh, one last thing. If your object contains a line like:
<programlisting>
public int oid;
</programlisting>
    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.
   </para>

   <para>
    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.
   </para>

   <para>
    Setting oid to 0 before serialization, will also cause the object
    to be inserted. This enables an object to be duplicated in the
    database.
   </para>

<programlisting>
Class org.postgresql.util.Serialize

java.lang.Object
   |
   +----org.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 
or deserialize 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 <productname>PostgreSQL</productname> 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 <productname>PostgreSQL</productname> table to a Java Class name, by
          replacing _ with .

        Parameters:
                name - PostgreSQL table name
  
        Returns:
                Class name

        Throws: SQLException
                on error
<!-- **************************************************************** -->
Utility Classes

The org.postgresql.util package contains classes used by the internals of 
the main driver, and the other extensions.

Class org.postgresql.util.PGmoney
                                
java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.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 overridden to allow the object to be cloned

        Overrides:
                clone in class PGobject

 public String getValue()

        Returns:
                the PGpoint in the syntax expected by <productname>PostgreSQL</productname>

        Overrides:
                getValue in class PGobject

<!-- **************************************************************** -->
Class org.postgresql.util.PGobject

java.lang.Object
   |
   +----org.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 org.postgresql.Connection permits a class that extends this 
class to be associated with a named type. This is how the 
org.postgresql.geometric package operates.
    ResultSet.getObject() will return this class for any type that is 
not recognized on having it's own handler. Because of this, any 
<productname>PostgreSQL</productname> data type is supported.

Constructors

 public PGobject()

          This is called by org.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 
overridden.

        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 overridden, to return the value of the object, 
in the form required by <productname>PostgreSQL</productname>.

        Returns:
                the value of this object

 public boolean equals(Object obj)

          This must be overridden 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 overridden to allow the object to be cloned

        Overrides:
                clone in class Object

 public String toString()

          This is defined here, so user code need not override it.
          
        Returns:
                the value of this object, in the syntax expected by 
<productname>PostgreSQL</productname>

        Overrides:
                toString in class Object

<!-- **************************************************************** -->
Class org.postgresql.util.PGtokenizer

java.lang.Object
   |
   +----org.postgresql.util.PGtokenizer

   public class PGtokenizer extends Object

   This class is used to tokenize the text output of <productname>PostgreSQL</productname>.

   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 <productname>PostgreSQL</productname>.
                 
   See Also:
          PGbox, PGcircle, PGlseg, PGpath, PGpoint, PGpolygon
          
Constructors

 public PGtokenizer(String string,
                    char delim)

          Create a tokenizer.

        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 data types 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 org.postgresql.util.Serialize

This was documented earlier under Object Serialization.

Class org.postgresql.util.UnixCrypt
              
java.lang.Object
   |
   +----org.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 clear-text 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 randomized.
                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 clear-text 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 acquired).

        Returns:
                true if the password should be considered correct.
</programlisting>
  </sect2>

 </sect1>
<!-- **************************************************************** -->

 <sect1 id="jdbc-thread">
  <title>Using the driver in a multi-threaded or a servlet environment</title>

  <para>
   A problem with many <acronym>JDBC</acronym> drivers is that only
   one thread can use a <classname>Connection</classname> 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.
  </para>

  <para>
   <productname>PostgreSQL</productname> 6.4 brought thread safety to
   the entire driver.  (Standard <acronym>JDBC</acronym> was thread
   safe in 6.3, but the Fastpath <acronym>API</acronym> was not.)
   Consequently, if your application uses multiple threads then you do
   not have to worry about complex algorithms to ensure that only one
   uses the database at any time.
  </para>

  <para>
   If a thread attempts to use the connection while another one is
   using it, it will wait until the other thread has finished its
   current operation.  If it is a regular <acronym>SQL</acronym>
   statement, then the operation consists of sending the statement and
   retrieving any <classname>ResultSet</classname> (in full).  If it
   is a <classname>Fastpath</classname> call (e.g., reading a block
   from a <classname>LargeObject</classname>) then it is the time to
   send and retrieve that block.
  </para>

  <para>
   This is fine for applications and 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 but one will pause, which may not be what
   you are after.
  </para>

  <para>
   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 <classname>Connection</classname>. The
   manager 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 is dead.
  </para>

  <para>
   So, with servlets, it is 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 process is created for each
   <classname>Connection</classname>.  It is up to you and your
   applications requirements.
  </para>
 </sect1>


 <sect1 id="jdbc-reading">
  <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 from
   <ulink
   url="http://java.sun.com/products/jdbc/index.html">http://java.sun.com/products/jdbc/index.html</ulink>.
  </para>

  <para>
   <ulink
   url="http://jdbc.postgresql.org">http://jdbc.postgresql.org</ulink>
   contains updated information not included in this document, and
   also includes precompiled drivers.
  </para>
 </sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->