]> granicus.if.org Git - postgresql/commitdiff
Remove JDBC from the build system and documentation, too.
authorTom Lane <tgl@sss.pgh.pa.us>
Mon, 19 Jan 2004 21:20:06 +0000 (21:20 +0000)
committerTom Lane <tgl@sss.pgh.pa.us>
Mon, 19 Jan 2004 21:20:06 +0000 (21:20 +0000)
13 files changed:
GNUmakefile.in
README
aclocal.m4
config/java.m4 [deleted file]
configure
configure.in
doc/src/sgml/filelist.sgml
doc/src/sgml/installation.sgml
doc/src/sgml/jdbc.sgml [deleted file]
doc/src/sgml/postgres.sgml
src/Makefile.global.in
src/interfaces/Makefile
src/makefiles/Makefile.cygwin

index bcc157bc2f0630a392b205f6301c116fe8a18f20..5f7e6558dea8e743720f08f4afc84daff45bb3aa 100644 (file)
@@ -1,7 +1,7 @@
 #
 # PostgreSQL top level makefile
 #
-# $PostgreSQL: pgsql/GNUmakefile.in,v 1.36 2003/11/28 20:32:09 pgsql Exp $
+# $PostgreSQL: pgsql/GNUmakefile.in,v 1.37 2004/01/19 21:20:04 tgl Exp $
 #
 
 subdir =
@@ -72,7 +72,7 @@ $(distdir).tar: distdir
 opt_files := \
        src/tools src/corba src/tutorial \
        src/bin/pgtclsh \
-       $(addprefix src/interfaces/, libpgtcl jdbc) \
+       $(addprefix src/interfaces/, libpgtcl) \
        $(addprefix src/pl/, plperl plpython tcl)
 
 docs_files := doc/postgres.tar.gz doc/src doc/TODO.detail
diff --git a/README b/README
index 22607bb6f6f45d444fb7466e5d9b9133644d6645..923e951a8c89f229e176913536f08d5eaf714427 100644 (file)
--- a/README
+++ b/README
@@ -8,11 +8,11 @@ PostgreSQL is an advanced object-relational database management system
 that supports an extended subset of the SQL standard, including
 transactions, foreign keys, subqueries, triggers, user-defined types
 and functions.  This distribution also contains several language
-bindings, including C, Perl, Python, and Tcl, as well as a JDBC
-driver.
+bindings, including C and Tcl.
 
-The ODBC and C++ interfaces have been moved to the PostgreSQL Projects
-Web Site at http://gborg.postgresql.org for separate maintenance.
+The JDBC, ODBC, C++, and Python interfaces have been moved to the PostgreSQL
+Projects Web Site at http://gborg.postgresql.org for separate maintenance.
+A Perl DBI/DBD driver is available from CPAN.
 
 See the file INSTALL for instructions on how to build and install
 PostgreSQL.  That file also lists supported operating systems and
index 1fd7537db7640c3e7215a77b186ff7edbb27866b..496f806f9601d2d6dafd8299f7f5829e281fad5e 100644 (file)
@@ -1,10 +1,9 @@
-dnl $PostgreSQL: pgsql/aclocal.m4,v 1.16 2003/11/29 19:51:16 pgsql Exp $
+dnl $PostgreSQL: pgsql/aclocal.m4,v 1.17 2004/01/19 21:20:04 tgl Exp $
 m4_include([config/ac_func_accept_argtypes.m4])
 m4_include([config/c-compiler.m4])
 m4_include([config/c-library.m4])
 m4_include([config/docbook.m4])
 m4_include([config/general.m4])
-m4_include([config/java.m4])
 m4_include([config/libtool.m4])
 m4_include([config/perl.m4])
 m4_include([config/programs.m4])
diff --git a/config/java.m4 b/config/java.m4
deleted file mode 100644 (file)
index 1bfcf31..0000000
+++ /dev/null
@@ -1,61 +0,0 @@
-#
-# Autoconf macros for configuring the build of Java JDBC Tools
-#
-# $PostgreSQL: pgsql/config/java.m4,v 1.5 2003/11/29 19:51:17 pgsql Exp $
-#
-
-
-# _PGAC_PROG_ANT_WORKS
-# --------------------
-AC_DEFUN([_PGAC_PROG_ANT_WORKS],
-[
-  AC_CACHE_CHECK([whether $ANT works], [pgac_cv_prog_ant_works],
-  [
-    cat > conftest.java << EOF
-public class conftest {
-    int testmethod(int a, int b) {
-        return a + b;
-    }
-}
-EOF
-
-    cat > conftest.xml << EOF
-<project name="conftest" default="conftest">
- <target name="conftest">
-  <javac srcdir="." includes="conftest.java">
-  </javac>
- </target>
-</project>
-EOF
-
-    pgac_cmd='$ANT -buildfile conftest.xml 1>&2'
-    AC_TRY_EVAL(pgac_cmd)
-    pgac_save_status=$?
-    if test $? = 0 && test -f ./conftest.class ; then
-      pgac_cv_prog_ant_works=yes
-    else
-      echo "configure: failed java program was:" >&AS_MESSAGE_LOG_FD
-      cat conftest.java >&AS_MESSAGE_LOG_FD
-      echo "configure: failed build file was:" >&AS_MESSAGE_LOG_FD
-      cat conftest.xml >&AS_MESSAGE_LOG_FD
-      pgac_cv_prog_ant_works=no
-    fi
-
-    rm -f conftest* core core.* *.core
-  ])
-
-  if test "$pgac_cv_prog_ant_works" != yes; then
-    AC_MSG_ERROR([ant does not work])
-  fi
-])
-
-
-# PGAC_PATH_ANT
-# -------------
-# Look for the ANT tool and set the output variable 'ANT' to 'ant'
-# if found, empty otherwise
-AC_DEFUN([PGAC_PATH_ANT],
-[
-  AC_PATH_PROGS(ANT, [jakarta-ant ant ant.sh ant.bat])
-  _PGAC_PROG_ANT_WORKS
-])
index 828ac5c60b6aa4a9985c4570cbaa65736bb1670d..3c23e6647e0d6ccb42ca85b698fb1bac7f349fef 100755 (executable)
--- a/configure
+++ b/configure
@@ -864,7 +864,6 @@ Optional Packages:
   --with-tkconfig=DIR     tkConfig.sh is in DIR
   --with-perl             build Perl modules (PL/Perl)
   --with-python           build Python modules (PL/Python)
-  --with-java             build JDBC interface and Java tools
   --with-krb4             build with Kerberos 4 support
   --with-krb5             build with Kerberos 5 support
   --with-krb-srvnam=NAME  name of the service principal in Kerberos [postgres]
@@ -3166,153 +3165,6 @@ echo "$as_me:$LINENO: result: $with_python" >&5
 echo "${ECHO_T}$with_python" >&6
 
 
-#
-# Optionally build the Java/JDBC tools
-#
-echo "$as_me:$LINENO: checking whether to build Java/JDBC tools" >&5
-echo $ECHO_N "checking whether to build Java/JDBC tools... $ECHO_C" >&6
-
-
-
-# Check whether --with-java or --without-java was given.
-if test "${with_java+set}" = set; then
-  withval="$with_java"
-
-  case $withval in
-    yes)
-      echo "$as_me:$LINENO: result: yes" >&5
-echo "${ECHO_T}yes" >&6
-
-  for ac_prog in jakarta-ant ant ant.sh ant.bat
-do
-  # Extract the first word of "$ac_prog", so it can be a program name with args.
-set dummy $ac_prog; ac_word=$2
-echo "$as_me:$LINENO: checking for $ac_word" >&5
-echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6
-if test "${ac_cv_path_ANT+set}" = set; then
-  echo $ECHO_N "(cached) $ECHO_C" >&6
-else
-  case $ANT in
-  [\\/]* | ?:[\\/]*)
-  ac_cv_path_ANT="$ANT" # Let the user override the test with a path.
-  ;;
-  *)
-  as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
-  IFS=$as_save_IFS
-  test -z "$as_dir" && as_dir=.
-  for ac_exec_ext in '' $ac_executable_extensions; do
-  if $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
-    ac_cv_path_ANT="$as_dir/$ac_word$ac_exec_ext"
-    echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
-    break 2
-  fi
-done
-done
-
-  ;;
-esac
-fi
-ANT=$ac_cv_path_ANT
-
-if test -n "$ANT"; then
-  echo "$as_me:$LINENO: result: $ANT" >&5
-echo "${ECHO_T}$ANT" >&6
-else
-  echo "$as_me:$LINENO: result: no" >&5
-echo "${ECHO_T}no" >&6
-fi
-
-  test -n "$ANT" && break
-done
-
-
-  echo "$as_me:$LINENO: checking whether $ANT works" >&5
-echo $ECHO_N "checking whether $ANT works... $ECHO_C" >&6
-if test "${pgac_cv_prog_ant_works+set}" = set; then
-  echo $ECHO_N "(cached) $ECHO_C" >&6
-else
-
-    cat > conftest.java << EOF
-public class conftest {
-    int testmethod(int a, int b) {
-        return a + b;
-    }
-}
-EOF
-
-    cat > conftest.xml << EOF
-<project name="conftest" default="conftest">
- <target name="conftest">
-  <javac srcdir="." includes="conftest.java">
-  </javac>
- </target>
-</project>
-EOF
-
-    pgac_cmd='$ANT -buildfile conftest.xml 1>&2'
-    { (eval echo "$as_me:$LINENO: \"$pgac_cmd\"") >&5
-  (eval $pgac_cmd) 2>&5
-  ac_status=$?
-  echo "$as_me:$LINENO: \$? = $ac_status" >&5
-  (exit $ac_status); }
-    pgac_save_status=$?
-    if test $? = 0 && test -f ./conftest.class ; then
-      pgac_cv_prog_ant_works=yes
-    else
-      echo "configure: failed java program was:" >&5
-      cat conftest.java >&5
-      echo "configure: failed build file was:" >&5
-      cat conftest.xml >&5
-      pgac_cv_prog_ant_works=no
-    fi
-
-    rm -f conftest* core core.* *.core
-
-fi
-echo "$as_me:$LINENO: result: $pgac_cv_prog_ant_works" >&5
-echo "${ECHO_T}$pgac_cv_prog_ant_works" >&6
-
-  if test "$pgac_cv_prog_ant_works" != yes; then
-    { { echo "$as_me:$LINENO: error: ant does not work" >&5
-echo "$as_me: error: ant does not work" >&2;}
-   { (exit 1); exit 1; }; }
-  fi
-
-
-if test -z "$ANT"; then
-  { { echo "$as_me:$LINENO: error: Ant is required to build Java components
-If you have Ant already installed, see config.log for details on the failure." >&5
-echo "$as_me: error: Ant is required to build Java components
-If you have Ant already installed, see config.log for details on the failure." >&2;}
-   { (exit 1); exit 1; }; }
-fi
-if "$ANT" -version | egrep -i 'ant version' | sed q | egrep -v ' 1\.[5-9]| [2-9]\.' >/dev/null ; then
-  { { echo "$as_me:$LINENO: error: Ant version >= 1.5 is required to build Java components" >&5
-echo "$as_me: error: Ant version >= 1.5 is required to build Java components" >&2;}
-   { (exit 1); exit 1; }; }
-fi
-      ;;
-    no)
-      echo "$as_me:$LINENO: result: no" >&5
-echo "${ECHO_T}no" >&6
-      ;;
-    *)
-      { { echo "$as_me:$LINENO: error: no argument expected for --with-java option" >&5
-echo "$as_me: error: no argument expected for --with-java option" >&2;}
-   { (exit 1); exit 1; }; }
-      ;;
-  esac
-
-else
-  with_java=no
-echo "$as_me:$LINENO: result: no" >&5
-echo "${ECHO_T}no" >&6
-fi;
-
-
-
 #
 # Kerberos 4
 #
@@ -18252,8 +18104,6 @@ s,@with_tcl@,$with_tcl,;t t
 s,@with_tk@,$with_tk,;t t
 s,@with_perl@,$with_perl,;t t
 s,@with_python@,$with_python,;t t
-s,@ANT@,$ANT,;t t
-s,@with_java@,$with_java,;t t
 s,@with_krb4@,$with_krb4,;t t
 s,@with_krb5@,$with_krb5,;t t
 s,@krb_srvtab@,$krb_srvtab,;t t
index 1ed6c78d220dfbe218620d1d1d3941c825aaf23d..29dd95cac7d06f6ee78454c71034be73be11a757 100644 (file)
@@ -1,5 +1,5 @@
 dnl Process this file with autoconf to produce a configure script.
-dnl $PostgreSQL: pgsql/configure.in,v 1.310 2004/01/09 04:58:09 momjian Exp $
+dnl $PostgreSQL: pgsql/configure.in,v 1.311 2004/01/19 21:20:05 tgl Exp $
 dnl
 dnl Developers, please strive to achieve this order:
 dnl
@@ -409,23 +409,6 @@ PGAC_ARG_BOOL(with, python, no, [  --with-python           build Python modules
 AC_MSG_RESULT([$with_python])
 AC_SUBST(with_python)
 
-#
-# Optionally build the Java/JDBC tools
-#
-AC_MSG_CHECKING([whether to build Java/JDBC tools])
-PGAC_ARG_BOOL(with, java, no, [  --with-java             build JDBC interface and Java tools],
-[AC_MSG_RESULT(yes)
-PGAC_PATH_ANT
-if test -z "$ANT"; then
-  AC_MSG_ERROR([Ant is required to build Java components
-If you have Ant already installed, see config.log for details on the failure.])
-fi
-if "$ANT" -version | egrep -i 'ant version' | sed q | egrep -v ' 1\.[[5-9]]| [[2-9]]\.' >/dev/null ; then
-  AC_MSG_ERROR([Ant version >= 1.5 is required to build Java components])
-fi],
-[AC_MSG_RESULT(no)])
-AC_SUBST(with_java)
-
 #
 # Kerberos 4
 #
index bbfd55d9b4c116cfbca0d2ce4e59f40fd2789c95..3fd9ce90451f3725fb7c98a6045e1557315bb244 100644 (file)
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.34 2003/11/29 19:51:37 pgsql Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.35 2004/01/19 21:20:06 tgl Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -49,7 +49,6 @@
 <!entity extend     SYSTEM "extend.sgml">
 <!entity func-ref   SYSTEM "func-ref.sgml">
 <!entity infoschema SYSTEM "information_schema.sgml">
-<!entity jdbc       SYSTEM "jdbc.sgml">
 <!entity libpgeasy  SYSTEM "libpgeasy.sgml">
 <!entity libpq      SYSTEM "libpq.sgml">
 <!entity libpgtcl   SYSTEM "libpgtcl.sgml">
index 1fc151abeb8b2e25d2fd1ef96247e8e67bee4609..368d82e3cbffa2098734364c35c51469101b2738 100644 (file)
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.192 2004/01/11 05:46:58 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.193 2004/01/19 21:20:06 tgl Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -212,41 +212,6 @@ su - postgres
      </para>
     </listitem>
 
-    <listitem>
-     <para>
-      To build the JDBC driver, you need
-      <application>Ant</application> 1.5 or higher and a
-      <acronym>JDK</acronym>.  <application>Ant</application> is a
-      special tool for building Java-based packages.  It can be
-      downloaded from the <ulink
-      url="http://jakarta.apache.org/ant/index.html"><application>Ant</application>
-      web site</ulink>.
-     </para>
-
-     <para>
-      If you have several Java compilers installed, it depends on the
-      Ant configuration which one gets used.  Precompiled
-      <application>Ant</application> distributions are typically set
-      up to read a file <filename>.antrc</filename> in the current
-      user's home directory for configuration.  For example, to use a
-      different <acronym>JDK</acronym> than the default, this may
-      work:
-<programlisting>
-JAVA_HOME=/usr/local/sun-jdk1.3
-JAVACMD=$JAVA_HOME/bin/java
-</programlisting>
-     </para>
-
-     <note>
-      <para>
-       Do not try to build the driver by calling
-       <command>ant</command> or even <command>javac</command>
-       directly.  This will not work.  Run <command>gmake</command>
-       normally as described below.
-      </para>
-     </note>
-    </listitem>
-
     <listitem>
      <para>
       To enable Native Language Support (<acronym>NLS</acronym>), that
@@ -801,16 +766,6 @@ JAVACMD=$JAVA_HOME/bin/java
        </listitem>
       </varlistentry>
 
-      <varlistentry>
-       <term><option>--with-java</option></term>
-       <listitem>
-        <para>
-         Build the <acronym>JDBC</acronym> driver and associated Java
-         packages.
-        </para>
-       </listitem>
-      </varlistentry>
-
       <varlistentry>
        <term><option>--with-krb4</option></term>
        <term><option>--with-krb5</option></term>
diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml
deleted file mode 100644 (file)
index e2f0f39..0000000
+++ /dev/null
@@ -1,3197 +0,0 @@
-<!--
-$PostgreSQL: pgsql/doc/src/sgml/jdbc.sgml,v 1.52 2003/12/13 23:59:06 neilc Exp $
--->
-
- <chapter id="jdbc">
-  <title><acronym>JDBC</acronym> Interface</title>
-
-  <indexterm zone="jdbc">
-   <primary>JDBC</primary>
-  </indexterm>
-
-  <indexterm zone="jdbc">
-   <primary>Java</primary>
-  </indexterm>
-
-  <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>
-   <productname>PostgreSQL</> 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.
-  </para>
-
- <sect1 id="jdbc-setup">
-  <title>Setting up the <acronym>JDBC</acronym> Driver</title>
-
-  <para>
-   This section describes the steps you need to take before you can
-   write or run programs that use the <acronym>JDBC</> interface.
-  </para>
-
-  <sect2 id="jdbc-build">
-   <title>Getting the Driver</title>
-
-   <para>
-    Precompiled versions of the driver can be downloaded from
-    the <ulink
-    url="http://jdbc.postgresql.org"><productname>PostgreSQL</productname>
-    <acronym>JDBC</acronym> web site</ulink>.
-   </para>
-
-   <para>
-    Alternatively you can build the driver from source, but you should
-    only need to do this if you are making changes to the source code.
-    For details, refer to the <productname>PostgreSQL</>
-    <link linkend="installation">installation instructions</link>.
-    After installation, the driver should be found in
-    <filename><replaceable>PREFIX</>/share/java/postgresql.jar</filename>.
-    The resulting driver will be built for the version of Java you are
-    running.  If you build with a 1.1 <acronym>JDK</> you will build a
-    version that supports the <acronym>JDBC</> 1 specification, if you build
-    with a 1.2 or 1.3 <acronym>JDK</> you will build a version that supports
-    the <acronym>JDBC</> 2 specification, and finally if you build with a
-    1.4 <acronym>JDK</acronym> you will build a version that supports the
-    <acronym>JDBC</> 3 specification.
-   </para>
-  </sect2>
-
-  <sect2 id="jdbc-classpath">
-   <title>Setting up the Class Path</title>
-
-   <indexterm zone="jdbc-classpath">
-    <primary>class path</primary>
-   </indexterm>
-
-   <indexterm zone="jdbc-classpath">
-    <primary>CLASSPATH</primary>
-   </indexterm>
-
-   <para>
-    To use the driver, the JAR archive (named
-    <filename>postgresql.jar</filename> if you built from source, otherwise
-    it will likely be named <filename>pg&majorversion;jdbc1.jar</filename>,
-    <filename>pg&majorversion;jdbc2.jar</filename>, or
-    <filename>pg&majorversion;jdbc3.jar</filename> for the <acronym>JDBC</> 1,
-    <acronym>JDBC</> 2, and <acronym>JDBC</> 3 versions respectively)
-    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>
-
-   <para>
-    For instance, assume we have an application that uses the
-    <acronym>JDBC</acronym> driver to access a database, and that
-    application is installed as
-    <filename>/usr/local/lib/myapp.jar</filename>.  The
-    <productname>PostgreSQL</> <acronym>JDBC</> driver installed as
-    <filename>/usr/local/pgsql/share/java/postgresql.jar</>.  To run
-    the application, we would use:
-<programlisting>
-export CLASSPATH=/usr/local/lib/myapp.jar:/usr/local/pgsql/share/java/postgresql.jar:.
-java MyApp
-</programlisting>
-    </para>
-
-    <para>
-     Loading the driver from within the application is covered in
-     <xref linkend="jdbc-use">.
-    </para>
-  </sect2>
-
-  <sect2 id="jdbc-prepare">
-   <title>Preparing the Database Server for <acronym>JDBC</acronym></title>
-
-   <para>
-    Because Java only uses TCP/IP connections, the
-    <productname>PostgreSQL</productname> server must be configured to
-    accept TCP/IP connections.  This can be done by setting
-    <literal>tcpip_socket = true</literal> in the
-    <filename>postgresql.conf</filename> file or by supplying the
-    <option>-i</option> option flag when starting
-    <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 <xref linkend="client-authentication"> for details.  The
-    <acronym>JDBC</acronym> driver supports the <literal>trust</>,
-    <literal>ident</>, <literal>password</>, <literal>md5</>, and
-    <literal>crypt</> authentication methods.
-   </para>
-  </sect2>
- </sect1>
-
- <sect1 id="jdbc-use">
-  <title>Initializing the Driver</title>
-
-  <para>
-   This section describes how to load and initialize the <acronym>JDBC</>
-   driver in your programs.
-  </para>
-
-  <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>
-   </para>
-
-    <note>
-     <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>
-    </note>
-  </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 <productname>PostgreSQL</>, 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>.
-   </para>
-
-    <note>
-     <para>
-      The <function>forName()</function> method can throw a
-      <classname>ClassNotFoundException</classname> if the driver is
-      not available.
-     </para>
-    </note>
-
-   <para>
-    This is the most common method to use, but restricts your code to
-    use just <productname>PostgreSQL</productname>.  If your code may
-    access another database system in the future, and you do not use
-    any <productname>PostgreSQL</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
-    <productname>PostgreSQL</productname>, 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>
-
-    The parameters have the following meanings:
-
-    <variablelist>
-     <varlistentry>
-      <term>
-       <replaceable class="parameter">host</replaceable>
-      </term>
-      <listitem>
-       <para>
-        The host name of the server. Defaults to <literal>localhost</literal>.  To specify an IPv6 address your must enclose the <replaceable class="parameter">host</replaceable> parameter with square brackets, for example:
-<programlisting>
-jdbc:postgresql://[::1]:5740/accounting
-</programlisting>
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>
-       <replaceable class="parameter">port</replaceable>
-      </term>
-      <listitem>
-       <para>
-        The port number the server is listening on. Defaults to the
-        <productname>PostgreSQL</productname> 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 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>
-
-   <indexterm zone="jdbc-query">
-    <primary>Statement</primary>
-   </indexterm>
-
-   <indexterm zone="jdbc-query">
-    <primary>PreparedStatement</primary>
-   </indexterm>
-
-   <indexterm zone="jdbc-query">
-    <primary>ResultSet</primary>
-   </indexterm>
-
-   <para>
-    Any time you want to issue <acronym>SQL</acronym> statements to
-    the database, you require a <classname>Statement</classname> or 
-    <classname>PreparedStatement</classname> instance. Once you have 
-    a <classname>Statement</classname> or 
-    <classname>PreparedStatement</classname>, you can use issue a
-    query. This will return a <classname>ResultSet</classname>
-    instance, which contains the entire result (see <xref linkend="jdbc-query-with-cursor">
-    here for how to alter this behaviour).
-    <xref linkend="jdbc-query-example"> illustrates this process.
-   </para>
-
-   <example id="jdbc-query-example">
-    <title>Processing a Simple Query in <acronym>JDBC</acronym></title>
-
-    <para>
-     This example will issue a simple query and print out the first
-     column of each row using a <classname>Statement</classname>.
-<programlisting>
-Statement st = db.createStatement();
-ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnfoo = 500");
-while (rs.next()) {
-    System.out.print("Column 1 returned ");
-    System.out.println(rs.getString(1));
-}
-rs.close();
-st.close();
-</programlisting>
-    </para>
-
-    <para>
-     This example issues the same query as before but uses
-     a <classname>PreparedStatement</classname>
-     and a bind value in the query.
-<programlisting>
-int foovalue = 500;
-PreparedStatement st = db.prepareStatement("SELECT * FROM mytable WHERE columnfoo = ?");
-st.setInt(1, foovalue);
-ResultSet rs = st.executeQuery();
-while (rs.next()) {
-    System.out.print("Column 1 returned ");
-    System.out.println(rs.getString(1));
-}
-rs.close();
-st.close();
-</programlisting>
-    </para>
-   </example>
-
-   <sect2 id="jdbc-query-with-cursor">
-     <title>Getting results based on a cursor</title>
-
-     <para>By default the driver collects all the results for the
-       query at once. This can be inconvenient for large data sets so
-       the JDBC driver provides a means of basing
-       a <classname>ResultSet</classname> on a database cursor and
-       only fetching a small number of rows.</para>
-
-     <para>A small number of rows are cached on the
-       client side of the connection and when exhausted the next
-       block of rows is retrieved by repositioning the cursor.
-     </para>
-
-     <example>
-       <title>Setting fetch size to turn cursors on and off.</title>
-
-     <para>Changing code to cursor mode is as simple as setting the
-       fetch size of the <classname>Statement</classname> to the
-       appropriate size. Setting the fetch size back to 0 will cause
-       all rows to be cached (the default behaviour).
-
-<programlisting>
-Statement st = db.createStatement();
-// Turn use of the cursor on.
-st.setFetchSize(50);
-ResultSet rs = st.executeQuery("SELECT * FROM mytable");
-while (rs.next()) {
-   System.out.print("a row was returned.");
-}
-rs.close();
-// Turn the cursor off.
-st.setFetchSize(0);
-ResultSet rs = st.executeQuery("SELECT * FROM mytable");
-while (rs.next()) {
-   System.out.print("many rows were returned.");
-}
-rs.close();
-// Close the statement.
-st.close();
-</programlisting>
-     </para>
-   </example>
-   </sect2>
-
-   <sect2>
-    <title>Using the <classname>Statement</classname> or <classname>PreparedStatement</classname> Interface</title>
-
-    <para>
-     The following must be considered when using the
-     <classname>Statement</classname> or 
-     <classname>PreparedStatement</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> or 
-        <classname>PreparedStatement</classname> at a given time.
-       </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>
-
-      <listitem>
-       <para>
-        When you are done using the <classname>Statement</classname>
-        or <classname>PreparedStatement</classname>
-        you should close it.
-       </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>PostgreSQL</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 change data (perform an <command>INSERT</command>,
-    <command>UPDATE</command>, or <command>DELETE</command>) you use
-    the <function>executeUpdate()</function> method.  This method is
-    similar to the method <function>executeQuery()</function> used to
-    issue a <command>SELECT</command> statement, but it doesn't return
-    a <classname>ResultSet</classname>; instead it returns the number
-    of rows affected by the <command>INSERT</command>,
-    <command>UPDATE</command>, or <command>DELETE</command> statement.
-    <xref linkend="jdbc-delete-example"> illustrates the usage.
-   </para>
-
-  <example id="jdbc-delete-example">
-   <title>Deleting Rows in <acronym>JDBC</acronym></title>
-   <para>
-     This example will issue a simple <command>DELETE</command>
-     statement and print out the number of rows deleted.
-<programlisting>
-int foovalue = 500;
-PreparedStatement st = db.prepareStatement("DELETE FROM mytable WHERE columnfoo = ?");
-st.setInt(1, foovalue);
-int rowsDeleted = st.executeUpdate();
-System.out.println(rowsDeleted + " rows deleted");
-st.close();
-</programlisting>
-   </para>
-  </example>
-  </sect1>
-
-
-  <sect1 id="jdbc-callproc">
-    <title>Calling Stored Functions</title>
-
-    <para><productname>PostgreSQL's</productname> JDBC driver fully
-      supports calling <productname>PostgreSQL</productname> stored
-      functions.</para>
-
-    <example id="jdbc-call-function">
-      <title>Calling a built in stored function</title>
-
-      <para>This example shows how to call
-       a <productname>PostgreSQL</productname> built in
-       function, <command>upper</command>, which simply converts the
-       supplied string argument to uppercase.
-
-<programlisting>
-// Turn transactions off.
-con.setAutoCommit(false);
-// Procedure call.
-CallableStatement upperProc = con.prepareCall("{ ? = call upper( ? ) }");
-upperProc.registerOutParameter(1, Types.VARCHAR);
-upperProc.setString(2, "lowercase to uppercase");
-upperProc.execute();
-String upperCased = upperProc.getString(1);
-upperProc.close();
-</programlisting>
-      </para>
-    </example>
-
-    <sect2>
-      <title>Using the <classname>CallableStatement</classname> Interface</title>
-
-      <para>
-       All the considerations that apply
-       for <classname>Statement</classname>
-       and <classname>PreparedStatement</classname> apply
-       for <classname>CallableStatement</classname> but in addition
-       you must also consider one extra restriction:
-      </para>
-
-      <itemizedlist>
-       <listitem>
-         <para>You can only call a stored function from within a
-           transaction.</para>
-       </listitem>
-      </itemizedlist>
-
-    </sect2>
-
-    <sect2>
-      <title>Obtaining <classname>ResultSet</classname> from a stored function</title>
-     
-      <para><productname>PostgreSQL's</productname> stored function
-       can return results by means of a <type>refcursor</type>
-       value. A <type>refcursor</type>.</para>
-
-      <para>As an extension to JDBC,
-       the <productname>PostgreSQL</productname> JDBC driver can
-       return <type>refcursor</type> values
-       as <classname>ResultSet</classname> values.</para>
-
-      <example id="get-refcursor-from-function-call">
-       <title>Getting <type>refcursor</type> values from a
-       function</title>
-
-       <para>When calling a function that returns
-         a <type>refcursor</type> you must cast the return type
-         of <function>getObject</function> to
-         a <classname>ResultSet</classname></para>
-
-<programlisting>
-// Turn transactions off.
-con.setAutoCommit(false);
-// Procedure call.
-CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }");
-proc.registerOutParameter(1, Types.Other);
-proc.setInt(2, -1);
-proc.execute();
-ResultSet results = (ResultSet) proc.getObject(1);
-while (results.next()) {
-  // do something with the results...
-}
-results.close();
-proc.close();
-</programlisting>
-      </example>
-
-      <para>It is also possible to treat the <type>refcursor</type>
-      return value as a distinct type in itself. The JDBC driver
-       provides
-      the <classname>org.postgresql.PGRefCursorResultSet</classname>
-       class for this purpose.</para>
-
-      <example>
-       <title>Treating <type>refcursor</type> as a distinct
-       type</title>
-
-<programlisting>
-con.setAutoCommit(false);
-CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }");
-proc.registerOutParameter(1, Types.Other);
-proc.setInt(2, 0);
-org.postgresql.PGRefCursorResultSet refcurs 
-    = (PGRefCursorResultSet) con.getObject(1);
-String cursorName = refcurs.getRefCursor();
-proc.close();
-</programlisting>
-      </example>
-    </sect2>
-
-  </sect1>
-
-
-  <sect1 id="jdbc-ddl">
-   <title>Creating and Modifying Database Objects</title>
-
-   <para>
-    To create, modify or drop a database object like a table or view
-    you use the <function>execute()</function> method.  This method is
-    similar to the method <function>executeQuery()</function>, but it
-    doesn't return a result.  <xref linkend="jdbc-drop-table-example">
-    illustrates the usage.
-   </para>
-
-  <example id="jdbc-drop-table-example">
-   <title>Dropping a Table in JDBC</title>
-   <para>
-     This example will drop a table.
-<programlisting>
-Statement st = db.createStatement();
-st.execute("DROP TABLE mytable");
-st.close();
-</programlisting>
-   </para>
-  </example>
-  </sect1>
-
- <sect1 id="jdbc-binary-data">
-  <title>Storing Binary Data</title>
-
-  <indexterm zone="jdbc-binary-data">
-   <primary>bytea</primary>
-   <secondary sortas="JDBC">in JDBC</secondary>
-  </indexterm>
-
-  <indexterm zone="jdbc-binary-data">
-   <primary>large object</primary>
-   <secondary sortas="JDBC">in JDBC</secondary>
-  </indexterm>
-
-  <para>
-    <productname>PostgreSQL</productname> provides two distinct ways to 
-    store binary data.  Binary data can be stored in a table using 
-    the data type <type>bytea</type> or by using the Large Object
-    feature which stores the binary data in a separate table in a special 
-    format and refers to that table by storing a value of type 
-    <type>oid</type> in your table.
-  </para>
-
-  <para>
-    In order to determine which method is appropriate you 
-    need to understand the limitations of each method.  The 
-    <type>bytea</type> data type is not well suited for storing very 
-    large amounts of binary data.  While a column of type 
-    <type>bytea</type> can hold up to 1 GB of binary data, it would 
-    require a huge amount of memory to 
-    process such a large value.  The Large Object method for 
-    storing binary data is better suited to storing very large values, 
-    but it has its own limitations.  Specifically deleting a row 
-    that contains a Large Object reference does not delete the Large Object.
-    Deleting the Large Object is a separate operation that needs to
-    be performed.  Large Objects also have some security
-    issues since anyone connected to the database can view 
-    and/or modify any Large Object, even if they don't have 
-    permissions to view/update the row containing the Large Object reference.
-  </para>
-
-  <para>
-    Version 7.2 was the first release of the <acronym>JDBC</acronym> driver 
-    that supports the <type>bytea</type> data type.  The introduction of 
-    this functionality in 7.2 has introduced a change in behavior 
-    as compared to previous releases.  Since 7.2, the methods 
-    <function>getBytes()</function>, <function>setBytes()</function>, 
-    <function>getBinaryStream()</function>, and 
-    <function>setBinaryStream()</function> operate on 
-    the <type>bytea</type> data type.  In 7.1 and earlier, these methods operated 
-    on the <type>oid</type> data type associated with Large Objects.  
-    It is possible to revert the driver back to the old 7.1 behavior 
-    by setting the property <literal>compatible</literal> on 
-    the <classname>Connection</classname> object to the value
-    <literal>7.1</literal>.
-  </para>
-
-  <para>
-    To use the <type>bytea</type> data type you should simply use 
-    the <function>getBytes()</function>, <function>setBytes()</function>,
-    <function>getBinaryStream()</function>, or 
-    <function>setBinaryStream()</function> methods.
-  </para>
-
-  <para>
-    To use the Large Object functionality you can use either the
-    <classname>LargeObject</classname> class provided by the
-    <productname>PostgreSQL</> <acronym>JDBC</acronym> driver, or by
-    using the <function>getBLOB()</function> and
-    <function>setBLOB()</function> methods.
-  </para>
-
-  <important>
-   <para>
-    You must access Large Objects within an <acronym>SQL</acronym>
-    transaction block.  You can start a transaction block by calling
-    <function>setAutoCommit(false)</function>.
-   </para>
-  </important>
-
-  <note>
-   <para>
-      In a future release of the
-      <acronym>JDBC</acronym> driver, the <function>getBLOB()</function>
-      and <function>setBLOB()</function> methods may no longer 
-      interact with Large Objects and will instead work on the data type
-      <type>bytea</type>.  So it is recommended that you 
-      use the <classname>LargeObject</classname> <acronym>API</acronym> 
-      if you intend to use Large Objects.
-   </para>
-  </note>
-
-  <para>
-   <xref linkend="jdbc-binary-data-example"> contains some examples on
-   how to process binary data using the <productname>PostgreSQL</>
-   <acronym>JDBC</> driver.
-  </para>
-
-  <example id="jdbc-binary-data-example">
-   <title>Processing Binary Data in <acronym>JDBC</></title>
-
-   <para>
-    For example, suppose you have a table containing the file names of
-    images and you also want to store the image in a <type>bytea</type>
-    column:
-<programlisting>
-CREATE TABLE images (imgname text, img bytea);
-</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>
-
-    Here, <function>setBinaryStream()</function> transfers a set number
-    of bytes from a stream into the column of type <type>bytea</type>.
-    This also could have been done using the <function>setBytes()</function>
-    method if the contents of the image was already in a 
-    <classname>byte[]</classname>. 
-   </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 img FROM images WHERE imgname = ?");
-ps.setString(1, "myimage.gif");
-ResultSet rs = ps.executeQuery();
-if (rs != null) {
-    while (rs.next()) {
-        byte[] imgBytes = rs.getBytes(1);
-        // use the data in some way here
-    }
-    rs.close();
-}
-ps.close();
-</programlisting>
-   </para>
-
-   <para>
-    Here the binary data was retrieved as an
-    <classname>byte[]</classname>.  You could have used a 
-    <classname>InputStream</classname> object instead.  
-   </para>
-
-   <para>
-    Alternatively you could be storing a very large file and want to use
-    the <classname>LargeObject</classname> <acronym>API</acronym> to 
-    store the file:
-<programlisting>
-CREATE TABLE imageslo (imgname text, imgoid oid);
-</programlisting>
-   </para>
-
-   <para>
-    To insert an image, you would use:
-<programlisting>
-// All LargeObject API calls must be within a transaction block
-conn.setAutoCommit(false);
-
-// Get the Large Object Manager to perform operations with
-LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI();
-
-// Create a new large object
-int oid = lobj.create(LargeObjectManager.READ | LargeObjectManager.WRITE);
-
-// Open the large object for writing
-LargeObject obj = lobj.open(oid, LargeObjectManager.WRITE);
-
-// Now open the file
-File file = new File("myimage.gif");
-FileInputStream fis = new FileInputStream(file);
-
-// Copy the data from the file to the large object
-byte buf[] = new byte[2048];
-int s, tl = 0;
-while ((s = fis.read(buf, 0, 2048)) > 0) {
-    obj.write(buf, 0, s);
-    tl += s;
-}
-
-// Close the large object
-obj.close();
-
-// Now insert the row into imageslo
-PreparedStatement ps = conn.prepareStatement("INSERT INTO imageslo VALUES (?, ?)");
-ps.setString(1, file.getName());
-ps.setInt(2, oid);
-ps.executeUpdate();
-ps.close();
-fis.close();
-</programlisting>
-   </para>
-
-   <para>
-    Retrieving the image from the Large Object:
-
-<programlisting>
-// All LargeObject API calls must be within a transaction block
-conn.setAutoCommit(false);
-
-// Get the Large Object Manager to perform operations with
-LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI();
-
-PreparedStatement ps = con.prepareStatement("SELECT imgoid FROM imageslo WHERE imgname = ?");
-ps.setString(1, "myimage.gif");
-ResultSet rs = ps.executeQuery();
-if (rs != null) {
-    while (rs.next()) {
-        // Open the large object for reading
-        int oid = rs.getInt(1);
-        LargeObject obj = lobj.open(oid, LargeObjectManager.READ);
-
-        // Read the data
-        byte buf[] = new byte[obj.size()];
-        obj.read(buf, 0, obj.size());
-        // Do something with the data read here
-
-        // Close the object
-        obj.close();
-    }
-    rs.close();
-}
-ps.close();
-</programlisting>
-   </para>
-
-  </example>
- </sect1>
-
-
- <sect1 id="jdbc-ext">
-  <title><productname>PostgreSQL</productname> Extensions to the
-    <acronym>JDBC</acronym> <acronym>API</acronym></title>
-
-  <para>
-   <productname>PostgreSQL</productname> is an extensible database
-   system.  You can add your own functions to the server, which can
-   then be called from queries, or even add your own data types.  As
-   these are facilities unique to <productname>PostgreSQL</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.PGConnection</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.PGConnection)db).getFastpathAPI();
-</programlisting>
-   </para>
-
-   <sect3>
-    <title>Class <classname>org.postgresql.PGConnection</classname></title>
-
-<synopsis>
-public class PGConnection 
-</synopsis>
-
-    <para>
-     These are the extra methods used to gain access to
-     <productname>PostgreSQL</productname>'s extensions. 
-    </para>
-
-    <sect4>
-     <title>Methods</title>
-
-     <itemizedlist>
-      <listitem>
-<synopsis>
-public Fastpath getFastpathAPI() throws SQLException
-</synopsis>
-       <para>
-        This returns the fast-path <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.PGConnection)myconn).getFastpathAPI();
-</programlisting>
-        where <varname>myconn</> is an open <classname>Connection</> to <productname>PostgreSQL</productname>.
-       </para>
-
-       <formalpara>
-        <title>Returns:</title>
-        <para>
-         <classname>Fastpath</> object allowing access to functions on the
-         <productname>PostgreSQL</productname> server.
-        </para>
-       </formalpara>
-
-       <formalpara>
-        <title>Throws:</title>
-        <para>
-         <classname>SQLException</> by <classname>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.PGConnection)myconn).getLargeObjectAPI();
-</programlisting>
-        where <varname>myconn</> is an open <classname>Connection</> to
-        <productname>PostgreSQL</productname>.
-       </para>
-
-       <formalpara>
-        <title>Returns:</title>
-        <para>
-         <classname>LargeObject</classname> object that implements the <acronym>API</acronym>
-        </para>
-       </formalpara>
-
-       <formalpara>
-        <title>Throws:</title>
-        <para>
-         <classname>SQLException</classname> by <classname>LargeObject</classname> 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
-        <productname>PostgreSQL</productname>'s more unique data types. Normally, a data type not
-        known by the driver is returned by <literal>ResultSet.getObject()</literal> as a
-        <classname>PGobject</> instance.  This method allows you to write a class
-        that extends <classname>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.PGConnection)myconn).addDataType("mytype","my.class.name");
- ...
-</programlisting>
-        where <varname>myconn</varname> is an open <classname>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 <application>libpq</application> C interface, and allows a client machine
-     to execute a function on the database server.  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.PGConnection)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.PGConnection</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 server
-     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 <productname>PostgreSQL</productname> server.
-       </para>
-
-       <formalpara>
-        <title>Parameters:</title>
-        <para>
-                <parameter>fnid</> - Function id
-                <parameter>resulttype</> - True if the result is an integer, false 
-for
-                other results
-                <parameter>args</> - <classname>FastpathArguments</classname> to pass to fast-path call
-        </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 <productname>PostgreSQL</productname> server by name.
-       </para>
-
-       <note>
-        <para>
-         The mapping for the procedure name to function id needs to
-         exist, usually to an earlier call to <function>addfunction()</function>. This is
-         the preferred method to call, as function id's can/may change
-         between versions of the server. For an example of how this
-         works, refer to org.postgresql.LargeObject
-        </para>
-       </note>
-
-       <formalpara>
-        <title>Parameters:</title>
-        <para>
-                <parameter>name</> - Function name
-                <parameter>resulttype</> - True if the result is an integer, false 
-for
-                other results
-                <parameter>args</> - <classname>FastpathArguments</classname> to pass to fast-path call
-        </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>
-                <parameter>name</parameter> - Function name
-                <parameter>args</parameter> - Function arguments
-        </para>
-       </formalpara>
-
-       <formalpara>
-        <title>Returns:</title>
-        <para>integer result</para>
-       </formalpara>
-
-       <formalpara>
-        <title>Throws:</title>
-        <para>
-         <classname>SQLException</classname> 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>
-                <parameter>name</parameter> - Function name
-                <parameter>args</parameter> - Function arguments
-        </para>
-       </formalpara>
-
-       <formalpara>
-        <title>Returns:</title>
-        <para>byte[] array containing result</para>
-       </formalpara>
-
-       <formalpara>
-        <title>Throws:</title>
-        <para>
-         <classname>SQLException</classname> 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>
-         <productname>PostgreSQL</productname> stores the function id's and their corresponding
-         names in the <classname>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 OIDs 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.
-        </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
-        <function>addFunction()</function> or <function>addFunctions()</function> have not been called for this
-        name, then an <classname>SQLException</classname> 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 fast-path 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><parameter>buf</></term>
-           <listitem>
-            <simpara>source array</simpara>
-           </listitem>
-          </varlistentry>
-
-          <varlistentry>
-           <term><parameter>off</parameter></term>
-           <listitem>
-            <simpara>offset within array</simpara>
-           </listitem>
-          </varlistentry>
-
-          <varlistentry>
-           <term><parameter>len</parameter></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 <productname>PostgreSQL</productname> 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
- 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 <productname>PostgreSQL</productname>'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 <productname>PostgreSQL</productname>'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 circles 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 server, 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 line in <productname>PostgreSQL</productname>'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 <productname>PostgreSQL</productname>'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 lines 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 line segment in <productname>PostgreSQL</productname>'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 <productname>PostgreSQL</productname>'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 line segments 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 path in <productname>PostgreSQL</productname>'s syntax.
-
-        Throws: SQLException
-                on conversion failure
-
-Methods
-
- public void setValue(String s) throws SQLException
-   
-        Parameters:
-                s - Definition of the path in <productname>PostgreSQL</productname>'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 pathes 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 path 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 <productname>PostgreSQL</productname>'s 
-syntax
-   
- public PGpoint()
-          
-          Required by the driver
-
-Methods
-
- public void setValue(String s) throws SQLException
-
-        Parameters:
-                s - Definition of this point in <productname>PostgreSQL</productname>'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 points 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 <productname>PostgreSQL</productname>.
-
-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 polygon in <productname>PostgreSQL</productname>'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 <productname>PostgreSQL</productname>'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 polygons 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 <productname>PostgreSQL</productname> 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 <application>libpq</application>
-    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 methods in 
-     <classname>BLOB</classname> to access large objects.
-    </para>
-
-    <para>
-     However, sometimes lower level access to Large Objects is
-     required, that is 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 int 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><parameter>buf</></term>
-           <listitem>
-            <simpara>destination array</simpara>
-           </listitem>
-          </varlistentry>
-
-          <varlistentry>
-           <term><parameter>off</></term>
-           <listitem>
-            <simpara>offset within array</simpara>
-           </listitem>
-          </varlistentry>
-
-          <varlistentry>
-           <term><parameter>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><parameter>buf</></term>
-           <listitem>
-            <simpara>destination array</simpara>
-           </listitem>
-          </varlistentry>
-
-          <varlistentry>
-           <term><parameter>off</></term>
-           <listitem>
-            <simpara>offset within array</simpara>
-           </listitem>
-          </varlistentry>
-
-          <varlistentry>
-           <term><parameter>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.PGConnection.  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.PGConnection)myconn).getLargeObjectAPI();
-</programlisting>
-    </para>
-
-    <para>
-     Normally, client code would use the <classname>BLOB</classname>
-     methods to access large objects.  However, sometimes
-     lower level access to Large Objects is required, that is 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><literal>public static final int WRITE</></term>
-       <listitem>
-        <simpara>This mode indicates we want to write to an object.</simpara>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><literal>public static final int READ</></term>
-       <listitem>
-        <simpara>This mode indicates we want to read an object.</simpara>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><literal>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 <symbol>READ</> and
-        <symbol>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 <symbol>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>
-
- </sect1>
-
-
- <sect1 id="jdbc-thread">
-  <title>Using the Driver in a Multithreaded or a Servlet Environment</title>
-
-  <indexterm zone="jdbc-thread">
-   <primary>threads</primary>
-   <secondary sortas="JDBC">with JDBC</secondary>
-  </indexterm>
-
-  <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 could cause severe confusion.
-  </para>
-
-  <para>
-   The <productname>PostgreSQL</productname> <acronym>JDBC</acronym> driver
-   is thread safe.
-   Consequently, if your application uses multiple threads then you do
-   not have to worry about complex algorithms to ensure that only one thread
-   uses the database at a 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 the operation 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 fast-path call (e.g., reading a block
-   from a large object) then it consists of
-   sending and retrieving the respective data.
-  </para>
-
-  <para>
-   This is fine for applications and applets but can cause a
-   performance problem with servlets.  If you have several threads
-   performing queries then each but one will pause.
-   To solve this, you are 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> object. 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 using the connection, it returns it to the manager
-   which 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.  The down side of a connection pool is
-   that it increases the load on the server because a new session is
-   created for each <classname>Connection</classname> object.  It is
-   up to you and your applications' requirements.
-  </para>
- </sect1>
-
- <sect1 id="jdbc-datasource">
-  <title>Connection Pools and Data Sources</title>
-
-  <indexterm zone="jdbc-datasource">
-   <primary>connection pool</primary>
-   <secondary sortas="JDBC">in JDBC</secondary>
-  </indexterm>
-
-  <indexterm zone="jdbc-datasource">
-   <primary>DataSource</primary>
-  </indexterm>
-
-  <para>
-    <acronym>JDBC</> 2 introduced standard connection pooling features in an
-    add-on <acronym>API</> known as the <acronym>JDBC</acronym> 2.0 Optional
-    Package (also known as the <acronym>JDBC</acronym> 2.0
-    Standard Extension).  These features have since been included in
-    the core <acronym>JDBC</> 3 <acronym>API</>.  The
-    <productname>PostgreSQL</productname> <acronym>JDBC</acronym> drivers
-    support these features if it has been compiled with
-    <acronym>JDK</acronym> 1.3.x in combination with the
-    <acronym>JDBC</acronym> 2.0 Optional Package
-    (<acronym>JDBC</acronym> 2), or with <acronym>JDK</acronym> 1.4 or higher
-    (<acronym>JDBC</acronym> 3).  Most application servers include
-    the <acronym>JDBC</acronym> 2.0 Optional Package, but it is
-    also available separately from the Sun
-    <ulink
-    url="http://java.sun.com/products/jdbc/download.html#spec"><acronym>JDBC</acronym> download site</ulink>.
-   </para>
-
-  <sect2 id="jdbc-ds-intro">
-   <title>Overview</title>
-
-    <para>
-     The <acronym>JDBC</acronym> <acronym>API</> provides a client
-     and a server interface for connection pooling.  The client
-     interface is <literal>javax.sql.DataSource</literal>,
-     which is what application code will typically use to
-     acquire a pooled database connection.  The server interface
-     is <literal>javax.sql.ConnectionPoolDataSource</literal>,
-     which is how most application servers will interface with
-     the <productname>PostgreSQL</productname> <acronym>JDBC</acronym>
-     driver.
-    </para>
-
-    <para>
-     In an application server environment, the
-     application server configuration will typically refer to
-     the <productname>PostgreSQL</productname>
-     <literal>ConnectionPoolDataSource</literal> implementation,
-     while the application component code will typically acquire a
-     <literal>DataSource</literal> implementation provided by
-     the application server (not by
-     <productname>PostgreSQL</productname>).
-    </para>
-
-    <para>
-     For an environment without an application server,
-     <productname>PostgreSQL</productname> provides two implementations
-     of <literal>DataSource</literal> which an application can use
-     directly.  One implementation performs connection pooling,
-     while the other simply provides access to database connections
-     through the <literal>DataSource</literal> interface without
-     any pooling.  Again, these implementations should not be used
-     in an application server environment unless the application
-     server does not support the
-     <literal>ConnectionPoolDataSource</literal> interface.
-    </para>
-  </sect2>
-   
-  <sect2 id="jdbc-ds-cpds">
-   <title>Application Servers: <classname>ConnectionPoolDataSource</classname></title>
-
-   <para>
-    <productname>PostgreSQL</productname> includes one implementation
-    of <classname>ConnectionPoolDataSource</classname> for
-    <acronym>JDBC</acronym> 2 and one for <acronym>JDBC</acronym> 3,
-    as shown in <xref linkend="jdbc-ds-cpds-imp-table">.
-   </para>
-
-  
-   <table id="jdbc-ds-cpds-imp-table">
-    <title><classname>ConnectionPoolDataSource</classname> Implementations</title>
-  
-    <tgroup cols=2>
-     <thead>
-      <row>
-       <entry><acronym>JDBC</acronym></entry>
-       <entry>Implementation Class</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>2</entry>
-       <entry><literal>org.postgresql.jdbc2.optional.ConnectionPool</literal></entry>
-      </row>
-      <row>
-       <entry>3</entry>
-       <entry><literal>org.postgresql.jdbc3.Jdbc3ConnectionPool</literal></entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
-   <para>
-    Both implementations use the same configuration scheme.
-    <acronym>JDBC</acronym> requires that a
-    <classname>ConnectionPoolDataSource</classname> be configured via
-    JavaBean properties, shown in <xref linkend="jdbc-ds-cpds-props">,
-    so there are get and set methods for each of these properties.
-   </para>
-
-   <table id="jdbc-ds-cpds-props">
-    <title><classname>ConnectionPoolDataSource</> Configuration Properties</title>
-  
-    <tgroup cols=3>
-     <thead>
-      <row>
-       <entry>Property</entry>
-       <entry>Type</entry>
-       <entry>Description</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry><literal>serverName</literal></entry>
-       <entry><type>String</type></entry>
-       <entry><productname>PostgreSQL</productname> database server
-         host name</entry>
-      </row>
-      <row>
-       <entry><literal>databaseName</literal></entry>
-       <entry><type>String</type></entry>
-       <entry><productname>PostgreSQL</productname> database name</entry>
-      </row>
-      <row>
-       <entry><literal>portNumber</literal></entry>
-       <entry><type>int</type></entry>
-       <entry>
-        TCP port which the <productname>PostgreSQL</productname>
-        database server is listening on (or 0 to use the default port)
-       </entry>
-      </row>
-      <row>
-       <entry><literal>user</literal></entry>
-       <entry><type>String</type></entry>
-       <entry>User used to make database connections</entry>
-      </row>
-      <row>
-       <entry><literal>password</literal></entry>
-       <entry><type>String</type></entry>
-       <entry>Password used to make database connections</entry>
-      </row>
-      <row>
-       <entry><literal>defaultAutoCommit</literal></entry>
-       <entry><type>boolean</type></entry>
-       <entry>
-        Whether connections should have autocommit enabled or disabled
-        when they are supplied to the caller.  The default is
-        <literal>false</literal>, to disable autocommit.
-       </entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
-   <para>
-    Many application servers use a properties-style syntax to
-    configure these properties, so it would not be unusual to enter
-    properties as a block of text.  If the application server provides
-    a single area to enter all the properties, they might be listed
-    like this:
-<programlisting>
-serverName=localhost
-databaseName=test
-user=testuser
-password=testpassword
-</programlisting>
-    Or, if semicolons are used as separators instead of newlines, it
-    could look like this:
-<programlisting>
-serverName=localhost;databaseName=test;user=testuser;password=testpassword
-</programlisting>
-   </para>
-
-  </sect2>
-
-  <sect2 id="jdbc-ds-ds">
-   <title>Applications: <classname>DataSource</></title>
-
-    <para><productname>PostgreSQL</productname> includes two
-     implementations of <literal>DataSource</literal>
-     for <acronym>JDBC</acronym> 2 and two for <acronym>JDBC</acronym>
-     3, as shown in <xref linkend="jdbc-ds-ds-imp">.
-     The pooling implementations do not actually close connections
-     when the client calls the <literal>close</literal> method, but
-     instead return the connections to a pool of available connections
-     for other clients to use.  This avoids any overhead of repeatedly
-     opening and closing connections, and allows a large number of
-     clients to share a small number of database connections.</para>
-    <para>The pooling data-source implementation provided here is not
-     the most feature-rich in the world.  Among other things,
-     connections are never closed until the pool itself is closed;
-     there is no way to shrink the pool.  As well, connections
-     requested for users other than the default configured user are
-     not pooled.  Many application servers
-     provide more advanced pooling features and use the
-     <literal>ConnectionPoolDataSource</literal> implementation
-     instead.</para>
-
-   <table id="jdbc-ds-ds-imp">
-    <title><classname>DataSource</> Implementations</title>
-  
-    <tgroup cols=3>
-     <thead>
-      <row>
-       <entry><acronym>JDBC</acronym></entry>
-       <entry>Pooling</entry>
-       <entry>Implementation Class</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>2</entry>
-       <entry>No</entry>
-       <entry><literal>org.postgresql.jdbc2.optional.SimpleDataSource</literal></entry>
-      </row>
-      <row>
-       <entry>2</entry>
-       <entry>Yes</entry>
-       <entry><literal>org.postgresql.jdbc2.optional.PoolingDataSource</literal></entry>
-      </row>
-      <row>
-       <entry>3</entry>
-       <entry>No</entry>
-       <entry><literal>org.postgresql.jdbc3.Jdbc3SimpleDataSource</literal></entry>
-      </row>
-      <row>
-       <entry>3</entry>
-       <entry>Yes</entry>
-       <entry><literal>org.postgresql.jdbc3.Jdbc3PoolingDataSource</literal></entry>
-      </row>
-     </tbody>
-    </tgroup>
-    </table>
-
-    <para>
-     All the implementations use the same configuration scheme.
-     <acronym>JDBC</acronym> requires that a
-     <literal>DataSource</literal> be configured via JavaBean
-     properties, shown in <xref linkend="jdbc-ds-ds-props">, so there
-     are get and set methods for each of these properties.
-    </para>
-
-    <table id="jdbc-ds-ds-props">
-    <title><classname>DataSource</> Configuration Properties</title>
-  
-    <tgroup cols=3>
-     <thead>
-      <row>
-       <entry>Property</entry>
-       <entry>Type</entry>
-       <entry>Description</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry><literal>serverName</literal></entry>
-       <entry><type>String</type></entry>
-       <entry><productname>PostgreSQL</productname> database server
-         host name</entry>
-      </row>
-      <row>
-       <entry><literal>databaseName</literal></entry>
-       <entry><type>String</type></entry>
-       <entry><productname>PostgreSQL</productname> database name</entry>
-      </row>
-      <row>
-       <entry><literal>portNumber</literal></entry>
-       <entry><type>int</type></entry>
-       <entry>TCP port which the 
-        <productname>PostgreSQL</productname> database server is
-       listening on (or 0 to use the default port)</entry>
-      </row>
-      <row>
-       <entry><literal>user</literal></entry>
-       <entry><type>String</type></entry>
-       <entry>User used to make database connections</entry>
-      </row>
-      <row>
-       <entry><literal>password</literal></entry>
-       <entry><type>String</type></entry>
-       <entry>Password used to make database connections</entry>
-      </row>
-     </tbody>
-    </tgroup>
-    </table>
-
-    <para>The pooling implementations require some additional
-      configuration properties, which are shown in <xref linkend="jdbc-ds-ds-xprops">.</para>
-
-   <table id="jdbc-ds-ds-xprops">
-    <title>Additional Pooling <classname>DataSource</> Configuration Properties</title>
-  
-    <tgroup cols=3>
-     <thead>
-      <row>
-       <entry>Property</entry>
-       <entry>Type</entry>
-       <entry>Description</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry><literal>dataSourceName</literal></entry>
-       <entry><type>String</type></entry>
-       <entry>Every pooling <literal>DataSource</literal> must have a
-        unique name.</entry>
-      </row>
-      <row>
-       <entry><literal>initialConnections</literal></entry>
-       <entry><type>int</type></entry>
-       <entry>The number of database connections to be created
-       when the pool is initialized.</entry>
-      </row>
-      <row>
-       <entry><literal>maxConnections</literal></entry>
-       <entry><type>int</type></entry>
-       <entry>The maximum number of open database connections to
-       allow.  When more connections are requested, the caller
-       will hang until a connection is returned to the pool.</entry>
-      </row>
-     </tbody>
-    </tgroup>
-    </table>
-
-    <para><xref linkend="jdbc-ds-example"> shows an example of typical application code using a
-     pooling <literal>DataSource</literal>.</para>
-   <example id="jdbc-ds-example">
-    <title><literal>DataSource</literal> Code Example</title>
-
-    <para>
-     Code to initialize a pooling <classname>DataSource</classname> might look like this:
-<programlisting>
-Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
-source.setDataSourceName("A Data Source");
-source.setServerName("localhost");
-source.setDatabaseName("test");
-source.setUser("testuser");
-source.setPassword("testpassword");
-source.setMaxConnections(10);
-</programlisting>
-      Then code to use a connection from the pool might look
-      like this.  Note that it is critical that the connections
-      are eventually closed.  Else the pool will <quote>leak</> connections and
-      will eventually lock all the clients out.
-<programlisting>
-Connection con = null;
-try {
-    con = source.getConnection();
-    // use connection
-} catch (SQLException e) {
-    // log error
-} finally {
-    if (con != null) {
-        try { con.close(); } catch (SQLException e) {}
-    }
-}
-</programlisting>
-    </para>
-   </example>
-  </sect2>
-
-  <sect2 id="jdbc-jndi">
-   <title>Data Sources and <acronym>JNDI</acronym></title>
-
-   <indexterm zone="jdbc-jndi">
-    <primary>JNDI</primary>
-   </indexterm>
-
-    <para>
-     All the <literal>ConnectionPoolDataSource</literal> and
-     <literal>DataSource</literal> implementations can be stored
-     in <acronym>JNDI</acronym>.  In the case of the nonpooling
-     implementations, a new instance will be created every time the
-     object is retrieved from <acronym>JNDI</acronym>, with the
-     same settings as the instance that was stored.  For the
-     pooling implementations, the same instance will be retrieved
-     as long as it is available (e.g., not a different
-     <acronym>JVM</acronym> retrieving the pool from
-     <acronym>JNDI</acronym>), or a new instance with the same
-     settings created otherwise.
-    </para>
-
-    <para>
-     In the application server environment, typically the
-     application server's <literal>DataSource</literal> instance
-     will be stored in <acronym>JNDI</acronym>, instead of the
-     <productname>PostgreSQL</productname>
-     <literal>ConnectionPoolDataSource</literal> implementation.
-    </para>
-
-    <para>
-     In an application environment, the application may store
-     the <literal>DataSource</literal> in <acronym>JNDI</acronym>
-     so that it doesn't have to make a reference to the
-     <literal>DataSource</literal> available to all application
-     components that may need to use it.  An example of this is
-     shown in <xref linkend="jdbc-ds-jndi">.
-    </para>
-
-   <example id="jdbc-ds-jndi">
-    <title><classname>DataSource</classname> <acronym>JNDI</acronym> Code Example</title>
-
-    <para>
-     Application code to initialize a pooling <classname>DataSource</classname> and add
-     it to <acronym>JNDI</acronym> might look like this:
-<programlisting>
-Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
-source.setDataSourceName("A Data Source");
-source.setServerName("localhost");
-source.setDatabaseName("test");
-source.setUser("testuser");
-source.setPassword("testpassword");
-source.setMaxConnections(10);
-new InitialContext().rebind("DataSource", source);
-</programlisting>
-      Then code to use a connection from the pool might look
-      like this:
-<programlisting>
-Connection con = null;
-try {
-    DataSource source = (DataSource)new InitialContext().lookup("DataSource");
-    con = source.getConnection();
-    // use connection
-} catch (SQLException e) {
-    // log error
-} catch (NamingException e) {
-    // DataSource wasn't found in JNDI
-} finally {
-    if (con != null) {
-        try { con.close(); } catch (SQLException e) {}
-    }
-}
-</programlisting>
-    </para>
-   </example>
-  </sect2>
-
- </sect1>
-
- <sect1 id="jdbc-reading">
-  <title>Further Reading</title>
-
-  <para>
-   If you have not yet read it, you are advised 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"></ulink>.
-  </para>
-
-  <para>
-   <ulink
-   url="http://jdbc.postgresql.org"></ulink>
-   contains updated information not included in this chapter and
-   also offers 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:
--->
index 2fbbf401308a595afba51e601215268ea8068e30..7e2e76de701f52a31a5269ca5ece6c13f82493e4 100644 (file)
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.62 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.63 2004/01/19 21:20:06 tgl Exp $
 -->
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@@ -179,7 +179,6 @@ $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.62 2003/11/29 19:51:37 pgsql E
   &lobj;
   &libpgtcl;
   &ecpg;
-  &jdbc;
   &infoschema;
 
  </part>
index 68c3bf80788dd1e581c3bddaa1a1aaab0a1bd592..f3a1d391820a3b520ec37c39c9771c57b1f0eb60 100644 (file)
@@ -1,5 +1,5 @@
 # -*-makefile-*-
-# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.172 2003/12/19 23:29:15 momjian Exp $
+# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.173 2004/01/19 21:20:06 tgl Exp $
 
 #------------------------------------------------------------------------------
 # All PostgreSQL makefiles include this file and use the variables it sets,
@@ -111,7 +111,6 @@ override docdir := $(docdir)/postgresql
 endif
 endif
 
-javadir := $(DESTDIR)$(datadir)/java
 localedir := @localedir@
 
 
@@ -121,7 +120,6 @@ localedir := @localedir@
 #
 # Records the choice of the various --enable-xxx and --with-xxx options.
 
-with_java      = @with_java@
 with_perl      = @with_perl@
 with_python    = @with_python@
 with_tcl       = @with_tcl@
@@ -209,7 +207,6 @@ perl_embed_ldflags  = @perl_embed_ldflags@
 
 # Miscellaneous
 
-ANT    = @ANT@
 AWK    = @AWK@
 LN_S   = @LN_S@
 MSGFMT  = @MSGFMT@
index 052d66dd1439698f5a3df6c3cb97693b2f896483..1fa91d5375d87badcda47ef8c69ff349bff5dd2a 100644 (file)
@@ -4,7 +4,7 @@
 #
 # Copyright (c) 1994, Regents of the University of California
 #
-# $PostgreSQL: pgsql/src/interfaces/Makefile,v 1.51 2003/11/29 19:52:08 pgsql Exp $
+# $PostgreSQL: pgsql/src/interfaces/Makefile,v 1.52 2004/01/19 21:20:06 tgl Exp $
 #
 #-------------------------------------------------------------------------
 
@@ -14,16 +14,12 @@ include $(top_builddir)/src/Makefile.global
 
 DIRS := libpq ecpg 
 
-ALLDIRS := $(DIRS) libpgtcl jdbc
+ALLDIRS := $(DIRS) libpgtcl
 
 ifeq ($(with_tcl), yes)
 DIRS += libpgtcl
 endif
 
-ifeq ($(with_java), yes)
-DIRS += jdbc
-endif
-
 
 all install installdirs uninstall dep depend distprep:
        @for dir in $(DIRS); do $(MAKE) -C $$dir $@ || exit; done
index 04493132767fe1772be786d7e58a72a2f1b10462..b3ee00c09e797e0ed8b69c32bb753a15857ca03a 100644 (file)
@@ -1,4 +1,4 @@
-# $PostgreSQL: pgsql/src/makefiles/Makefile.cygwin,v 1.3 2003/11/29 19:52:12 pgsql Exp $
+# $PostgreSQL: pgsql/src/makefiles/Makefile.cygwin,v 1.4 2004/01/19 21:20:06 tgl Exp $
 DLLTOOL= dlltool
 DLLWRAP= dllwrap
 BE_DLLLIBS= -L$(top_builddir)/src/backend -lpostgres
@@ -32,6 +32,4 @@ ifneq (,$(findstring src/pl/plpython,$(subdir)))
 override CPPFLAGS+= -DUSE_DL_IMPORT
 endif
 
-override javadir := '$(shell cygpath -w $(javadir))'
-
 sqlmansect = 7