head	1.53;
access;
symbols
	REL7_4_29:1.50
	REL7_4_28:1.50
	REL7_4_27:1.50
	REL7_4_26:1.50
	REL7_4_25:1.50
	REL7_4_24:1.50
	REL7_4_23:1.50
	REL7_4_22:1.50
	REL7_4_21:1.50
	REL7_4_20:1.50
	REL7_3_21:1.39.2.1
	REL7_4_19:1.50
	REL7_3_20:1.39.2.1
	REL7_4_18:1.50
	REL7_3_19:1.39.2.1
	REL7_4_17:1.50
	REL7_3_18:1.39.2.1
	REL7_4_16:1.50
	REL7_4_15:1.50
	REL7_3_17:1.39.2.1
	REL7_4_14:1.50
	REL7_3_16:1.39.2.1
	REL7_3_15:1.39.2.1
	REL7_4_13:1.50
	REL7_3_14:1.39.2.1
	REL7_4_12:1.50
	REL7_3_13:1.39.2.1
	REL7_4_11:1.50
	REL7_3_12:1.39.2.1
	REL7_4_10:1.50
	REL7_3_11:1.39.2.1
	REL7_4_9:1.50
	REL7_2_8:1.35
	REL7_3_10:1.39.2.1
	REL7_4_8:1.50
	REL7_2_7:1.35
	REL7_3_9:1.39.2.1
	REL7_4_7:1.50
	REL7_4_6:1.50
	REL7_3_8:1.39.2.1
	REL7_2_6:1.35
	REL7_2_5:1.35
	REL7_4_5:1.50
	REL7_3_7:1.39.2.1
	REL7_4_4:1.50
	REL7_4_3:1.50
	REL7_4_2:1.50
	REL7_3_6:1.39.2.1
	REL7_4_1:1.50
	REL7_3_5:1.39.2.1
	REL7_4:1.50
	REL7_4_RC2:1.50
	REL7_4_STABLE:1.50.0.2
	REL7_4_RC1:1.50
	REL7_4_BETA5:1.49
	REL7_4_BETA4:1.49
	REL7_4_BETA3:1.48
	REL7_4_BETA2:1.47
	WIN32_DEV:1.47.0.2
	REL7_4_BETA1:1.45
	REL7_3_4:1.39.2.1
	REL7_3_2:1.39.2.1
	REL7_2_4:1.35
	REL7_3_STABLE:1.39.0.2
	REL7_2_3:1.35
	REL7_2_STABLE:1.35.0.2
	REL7_2:1.35
	REL7_2_RC2:1.35
	REL7_2_RC1:1.35
	REL7_2_BETA5:1.34
	REL7_2_BETA4:1.34
	REL7_2_BETA3:1.27
	REL7_2_BETA2:1.27
	REL7_2_BETA1:1.26
	REL7_1_2:1.20
	REL7_1_STABLE:1.20.0.2
	REL7_1_BETA:1.15
	REL7_1_BETA3:1.18
	REL7_1_BETA2:1.18
	REL7_1:1.20
	REL7_0_PATCHES:1.10.0.2
	REL7_0:1.10
	REL6_5_PATCHES:1.6.0.2
	REL6_5:1.6
	REL6_4:1.4.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.53
date	2004.01.19.21.20.06;	author tgl;	state dead;
branches;
next	1.52;

1.52
date	2003.12.13.23.59.06;	author neilc;	state Exp;
branches;
next	1.51;

1.51
date	2003.11.29.19.51.37;	author pgsql;	state Exp;
branches;
next	1.50;

1.50
date	2003.11.01.01.56.29;	author petere;	state Exp;
branches
	1.50.2.1;
next	1.49;

1.49
date	2003.09.20.20.12.05;	author tgl;	state Exp;
branches;
next	1.48;

1.48
date	2003.08.31.17.32.19;	author petere;	state Exp;
branches;
next	1.47;

1.47
date	2003.08.07.05.06.40;	author barry;	state Exp;
branches
	1.47.2.1;
next	1.46;

1.46
date	2003.08.06.23.50.19;	author barry;	state Exp;
branches;
next	1.45;

1.45
date	2003.06.30.16.39.42;	author barry;	state Exp;
branches;
next	1.44;

1.44
date	2003.04.07.01.29.25;	author petere;	state Exp;
branches;
next	1.43;

1.43
date	2003.03.25.16.15.37;	author petere;	state Exp;
branches;
next	1.42;

1.42
date	2003.01.19.00.13.28;	author momjian;	state Exp;
branches;
next	1.41;

1.41
date	2002.11.15.03.11.16;	author momjian;	state Exp;
branches;
next	1.40;

1.40
date	2002.11.11.07.31.28;	author barry;	state Exp;
branches;
next	1.39;

1.39
date	2002.10.01.04.09.13;	author barry;	state Exp;
branches
	1.39.2.1;
next	1.38;

1.38
date	2002.09.21.18.32.53;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2002.09.18.20.09.31;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2002.03.22.19.20.11;	author petere;	state Exp;
branches;
next	1.35;

1.35
date	2002.01.20.22.19.56;	author petere;	state Exp;
branches;
next	1.34;

1.34
date	2001.11.29.05.35.51;	author barry;	state Exp;
branches;
next	1.33;

1.33
date	2001.11.27.13.02.33;	author ishii;	state Exp;
branches;
next	1.32;

1.32
date	2001.11.27.01.20.17;	author barry;	state Exp;
branches;
next	1.31;

1.31
date	2001.11.26.19.07.11;	author momjian;	state Exp;
branches;
next	1.30;

1.30
date	2001.11.26.18.51.19;	author momjian;	state Exp;
branches;
next	1.29;

1.29
date	2001.11.26.05.57.57;	author barry;	state Exp;
branches;
next	1.28;

1.28
date	2001.11.21.05.53.41;	author thomas;	state Exp;
branches;
next	1.27;

1.27
date	2001.10.25.22.00.31;	author barry;	state Exp;
branches;
next	1.26;

1.26
date	2001.10.12.23.32.33;	author momjian;	state Exp;
branches;
next	1.25;

1.25
date	2001.09.13.15.55.22;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2001.09.12.15.55.00;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2001.09.12.15.49.10;	author momjian;	state Exp;
branches;
next	1.22;

1.22
date	2001.09.10.21.58.46;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2001.08.16.16.24.15;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2001.03.11.11.06.59;	author petere;	state Exp;
branches;
next	1.19;

1.19
date	2001.02.24.12.40.27;	author petere;	state Exp;
branches;
next	1.18;

1.18
date	2000.12.22.21.51.58;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2000.12.22.18.57.49;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2000.12.21.22.55.27;	author petere;	state Exp;
branches;
next	1.15;

1.15
date	2000.10.27.22.28.23;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2000.10.16.02.20.58;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2000.09.29.20.21.34;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2000.08.29.20.02.07;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2000.08.23.05.59.02;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	2000.03.31.03.27.40;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	2000.03.30.22.22.40;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	99.10.09.02.30.02;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	99.10.04.15.16.35;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	99.04.15.06.00.16;	author peter;	state Exp;
branches;
next	1.5;

1.5
date	98.12.29.02.24.16;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.10.30.19.37.01;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.10.25.00.27.44;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.07.29.06.49.59;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.03.01.08.15.56;	author thomas;	state Exp;
branches;
next	;

1.39.2.1
date	2002.11.11.07.33.24;	author barry;	state Exp;
branches;
next	;

1.47.2.1
date	2003.09.07.04.36.42;	author momjian;	state Exp;
branches;
next	;

1.50.2.1
date	2010.08.17.04.49.31;	author petere;	state Exp;
branches;
next	;


desc
@@


1.53
log
@Remove JDBC from the build system and documentation, too.
@
text
@<!--
$PostgreSQL: pgsql-server/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:
-->
@


1.52
log
@This patch makes some SGML markup more consistent and makes a small
improvement to the SSL auth docs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/jdbc.sgml,v 1.51 2003/11/29 19:51:37 pgsql Exp $
@


1.51
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.50 2003/11/01 01:56:29 petere Exp $
d101 2
a102 2
    <filename>/usr/local/lib/myapp.jar</filename>.  The PostgreSQL
    <acronym>JDBC</> driver installed as
d122 3
a124 3
    <application>PostgreSQL</application> server must be configured to
    accept TCP/IP connections.  This can be done by setting 
    <literal>tcpip_socket = true</literal> in the 
d242 1
a242 1
    <application>PostgreSQL</application>, this takes one of the
d723 1
a723 1
    <application>PostgreSQL</application> provides two distinct ways to 
d773 5
a777 6
    To use the Large Object functionality you can use either the 
    <classname>LargeObject</classname> class
    provided by the <application>PostgreSQL</application> 
    <acronym>JDBC</acronym> driver, or by using the 
    <function>getBLOB()</function> and <function>setBLOB()</function>
    methods.
d802 2
a803 1
   how to process binary data using the PostgreSQL <acronym>JDBC</> driver.
d951 1
a951 1
  <title><application>PostgreSQL</application> Extensions to the
@


1.50
log
@Spell checking, consistent terminology.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.49 2003/09/20 20:12:05 tgl Exp $
@


1.50.2.1
log
@Backpatch some blatant spelling mistakes
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.50 2003/11/01 01:56:29 petere Exp $
d2439 1
a2439 1
                pos - position within object from beginning
@


1.49
log
@Fix a batch of speling misteaks identified by Peter's spell-checker tool.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.48 2003/08/31 17:32:19 petere Exp $
d575 1
a575 1
    <para><productname>PostgreSQL's</productname> jdbc driver fully
d639 1
a639 1
	  of getObject to
d956 1
a956 1
   system.  You can add your own functions to the backend, which can
d1002 1
a1002 1
        This returns the Fastpath <acronym>API</acronym> for the
d1020 2
a1021 2
         Fastpath object allowing access to functions on the
         <productname>PostgreSQL</productname> backend.
d1028 1
a1028 1
         <classname>SQLException</> by Fastpath when initializing for first time
d1113 1
a1113 1
     to execute a function on the database backend.  Most client code
d1137 1
a1137 1
     <function>fastpath()</function> methods to execute a backend
d1159 1
a1159 1
        Send a function call to the <productname>PostgreSQL</productname> backend.
d1169 1
a1169 1
                <parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
d1189 1
a1189 1
        Send a function call to the <productname>PostgreSQL</productname> backend by name.
d1197 1
a1197 1
         between versions of the backend. For an example of how this
d1209 1
a1209 1
                <parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
d1384 1
a1384 1
     Each fastpath call requires an array of arguments, the number and
d1703 1
a1703 1
not yet implemented in the backend, but this class ensures that when 
@


1.48
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.47 2003/08/07 05:06:40 barry Exp $
d265 1
a265 1
    The parametes have the following meanings:
d400 1
a400 1
       query at once. This can be inconvieniant for large data sets so
d634 1
a634 1
	<title>Gettig <type>refcursor</type> values from a
d744 1
a744 1
    issues since anyone connected to the database cann view 
@


1.47
log
@markup fixes
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.46 2003/08/06 23:50:19 barry Exp $
d8 8
d77 8
d335 12
d712 10
d2638 5
d2691 9
d3084 5
a3088 1
    <title>Data Sources and <acronym>JNDI</acronym></title>
@


1.47.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.48 2003/08/31 17:32:19 petere Exp $
a7 8
  <indexterm zone="jdbc">
   <primary>JDBC</primary>
  </indexterm>

  <indexterm zone="jdbc">
   <primary>Java</primary>
  </indexterm>

a68 8
   <indexterm zone="jdbc-classpath">
    <primary>class path</primary>
   </indexterm>

   <indexterm zone="jdbc-classpath">
    <primary>CLASSPATH</primary>
   </indexterm>

a318 12
   <indexterm zone="jdbc-query">
    <primary>Statement</primary>
   </indexterm>

   <indexterm zone="jdbc-query">
    <primary>PreparedStatement</primary>
   </indexterm>

   <indexterm zone="jdbc-query">
    <primary>ResultSet</primary>
   </indexterm>

a683 10
  <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>

a2599 5
  <indexterm zone="jdbc-thread">
   <primary>threads</primary>
   <secondary sortas="JDBC">with JDBC</secondary>
  </indexterm>

a2647 9
  <indexterm zone="jdbc-datasource">
   <primary>connection pool</primary>
   <secondary sortas="JDBC">in JDBC</secondary>
  </indexterm>

  <indexterm zone="jdbc-datasource">
   <primary>DataSource</primary>
  </indexterm>

d3032 1
a3032 5
   <title>Data Sources and <acronym>JNDI</acronym></title>

   <indexterm zone="jdbc-jndi">
    <primary>JNDI</primary>
   </indexterm>
@


1.46
log
@Applied doc patch for the jdbc docs submitted by Nic Ferrier for functionality
he supplied a few months ago, but didn't get around to docing until now.  And
he also added some doc for calling stored functions in general from jdbc that was missing.

 Modified Files:
 	sgml/jdbc.sgml
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.45 2003/06/30 16:39:42 barry Exp $
d368 1
a368 1
   <sect2 id="query-with-cursor">
d410 2
a411 1

d611 1
a611 1
	  of <methodname>getObject</methodname> to
@


1.45
log
@Minor jdbc doc updates submitted by Kris Jurka

 Modified Files:
 	sgml/jdbc.sgml
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.44 2003/04/07 01:29:25 petere Exp $
d326 3
a328 2
    instance, which contains the entire result.  <xref
    linkend="jdbc-query-example"> illustrates this process.
d368 44
d541 114
@


1.44
log
@General editing
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.43 2003/03/25 16:15:37 petere Exp $
d36 1
a36 1
   write or run programs that use the JDBC interface.
d52 3
a54 2
    For details, refer to the <productname>PostgreSQL</> installation
    instructions.  After installation, the driver should be found in
d58 5
a62 4
    version that supports the JDBC 1 specification, if you build with
    a Java 2 <acronym>JDK</> (e.g., <acronym>JDK</> 1.2 or
    <acronym>JDK</> 1.3) you will build a version that supports the
    JDBC 2 specification.
d72 6
a77 6
    it will likely be named <filename>jdbc&majorversion;-1.1.jar</filename> or 
    <filename>jdbc&majorversion;-1.2.jar</filename> for the JDBC 1 and JDBC 2 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
d86 1
a86 1
    JDBC driver installed as
d118 3
a120 2
    <acronym>JDBC</acronym> driver supports the trust, ident,
    password, md5, and crypt authentication methods.
d129 2
a130 2
   This section describes how to load and initialize the JDBC driver
   in your programs.
d258 4
a261 1
        The host name of the server. Defaults to <literal>localhost</literal>.
a459 10
      <listitem>
       <para>
        <classname>ResultSet</classname> is currently read only.
        You can not update data through the <classname>ResultSet</classname>.
        If you want to update data you need to do it the normal way
        by using the <acronym>SQL</acronym> statement <command>UPDATE</command>.  This is 
        in conformance with the <acronym>JDBC</acronym> specification 
        which does not require drivers to provide updatable result sets.
       </para>
      </listitem>
d605 1
a605 1
   how to process binary data using the PostgreSQL JDBC driver.
d609 1
a609 1
   <title>Processing Binary Data in JDBC</title>
d2489 2
a2490 2
    JDBC 2 introduced standard connection pooling features in an
    add-on API known as the <acronym>JDBC</acronym> 2.0 Optional
d2493 3
a2495 2
    the core JDBC 3 API.  The <productname>PostgreSQL</productname>
    <acronym>JDBC</acronym> drivers support these features if it has been compiled with
d2510 1
a2510 1
     The <acronym>JDBC</acronym> API provides a client
@


1.43
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.42 2003/01/19 00:13:28 momjian Exp $
a7 8
  <note>
   <title>Author</title>
   <para>
    Originally written by Peter T. Mount (<email>peter@@retep.org.uk</email>), 
    the original author of the <acronym>JDBC</acronym> driver.
   </para>
  </note>

d16 1
a16 1
   4</firstterm> <acronym>JDBC</acronym> Driver.  Type 4 indicates
d28 1
a28 2
   Also, take a look at the examples included with the source. The
   basic example is used here.
d34 5
d70 2
a71 2
    it will likely be named <filename>jdbc7.2-1.1.jar</filename> or 
    <filename>jdbc7.2-1.2.jar</filename> for the JDBC 1 and JDBC 2 versions
d79 11
a89 12
    <para>
     For instance, I have an application that uses the
     <acronym>JDBC</acronym> driver to access a large database
     containing astronomical objects. I have the application and the
     <acronym>JDBC</acronym> driver installed in the <filename
     class="directory">/usr/local/lib</filename> directory, and the
     Java <acronym>JDK</acronym> installed in
     <filename>/usr/local/jdk1.3.1</filename>.  To run the
     application, I would use:
<programlisting>
export CLASSPATH=/usr/local/lib/finder.jar<co id="co.jdbc-finder">:/usr/local/pgsql/share/java/postgresql.jar:.
java Finder
a90 7
     <calloutlist>
      <callout arearefs="co.jdbc-finder">
       <para>
        <filename>finder.jar</filename> contains the Finder application.
       </para>
      </callout>
     </calloutlist>
d100 1
a100 1
   <title>Preparing the Database for <acronym>JDBC</acronym></title>
d116 1
a116 1
    <acronym>JDBC</acronym> Driver supports the trust, ident,
d123 6
a128 1
  <title>Using the Driver</title>
d140 1
d142 1
a142 1
    <important>
d148 1
a148 2
    </important>
   </para>
d171 1
a179 1
   </para>
d246 1
a246 1
    where:
d288 1
a288 1
    you would use the <function>DriverManager.getConnection()</function> method:
d332 2
a333 2
ResultSet rs = st.executeQuery("SELECT * FROM mytable where columnfoo = 500");
while(rs.next()) {
d343 1
a343 1
     This example will issue the same query as before using 
d348 1
a348 1
PreparedStatement st = db.prepareStatement("SELECT * FROM mytable where columnfoo = ?");
d351 1
a351 1
while(rs.next()) {
d362 1
a362 2
    <title>Using the <classname>Statement</classname> or <classname>
    PreparedStatement</classname> Interface</title>
d458 2
a459 2
        If you want to update data you need to do it the old fashioned way
        by issuing a <acronym>SQL</acronym> update statement.  This is 
d461 1
a461 1
        which does not require drivers to provide this functionality.
d473 9
a481 7
    To change data (perform an insert, update, or delete) 
    you use the <function>executeUpdate()</function> method.
    <function>executeUpdate()</function> is similar to the
    <function>executeQuery()</function> used to issue a select,
    however it doesn't return a <classname>ResultSet</classname>,
    instead it returns the number of records affected by the insert,
    update, or delete statement.
d485 1
a485 1
   <title>Simple Delete Example</title>
d487 2
a488 2
     This example will issue a simple delete and print out the number
     of rows deleted.
d491 1
a491 1
PreparedStatement st = db.prepareStatement("DELETE FROM mytable where columnfoo = ?");
d506 4
a509 4
    you use the <function>execute()</function> method.
    <function>execute</function> is similar to the
    <function>executeQuery()</function> used to issue a select,
    however it doesn't return a result.
d513 1
a513 1
   <title>Drop Table Example</title>
d518 1
a518 1
ResultSet rs = st.executeQuery("DROP TABLE mytable");
d531 1
a531 2
    <application>PostgreSQL's</application> binary data type 
    <type>bytea</type>, or by using the <firstterm>Large Object</firstterm>
d533 2
a534 2
    format, and refers to that table by storing a value of type 
    <type>OID</type> in your table.
d543 1
a543 1
    require a huge amount of memory (<acronym>RAM</acronym>) to 
d547 1
a547 1
    that contains a Large Object does not delete the Large Object.
d550 1
a550 1
    issues since anyone connected to the database case view 
d552 1
a552 1
    permissions to view/update the row containing the Large Object.
d556 1
a556 1
    7.2 is the first release of the <acronym>JDBC</acronym> Driver 
d559 1
a559 1
    as compared to previous releases.  In 7.2 the methods 
d563 2
a564 2
    the <type>bytea</type> data type.  In 7.1 these methods operated 
    on the <type>OID</type> data type associated with Large Objects.  
d566 3
a568 3
    by setting the <parameter>compatible</parameter> property on 
    the <classname>Connection</classname> to a value of 
    <literal>7.1</literal>
d580 1
a580 1
    <classname>LargeObject</classname> <acronym>API</acronym>
d582 1
a582 1
    <acronym>JDBC</acronym> Driver, or by using the 
d589 3
a591 5
    For <application>PostgreSQL</application>, you must access Large
    Objects within an <acronym>SQL</acronym> transaction.  You would
    open a transaction by using the
    <function>setAutoCommit()</function> method with an input
    parameter of <literal>false</literal>.
d595 4
a598 2
  <note><para>In a future release of the
      <acronym>JDBC</acronym> Driver, the <function>getBLOB()</function>
d600 2
a601 2
      interact with Large Objects and will instead work on 
      <type>bytea</type> data types.  So it is recommended that you 
d604 2
a605 1
  </para></note>
d607 4
d613 1
a613 1
   <title>Binary Data Examples</title>
d616 2
a617 2
    For example, suppose you have a table containing the file name of
    an image and you also want to store the image in a <type>bytea</type>
d650 1
a650 1
PreparedStatement ps = con.prepareStatement("SELECT img FROM images WHERE imgname=?");
d654 1
a654 1
    while(rs.next()) {
d656 1
a656 1
        // use the stream in some way here
d675 1
a675 1
CREATE TABLE imagesLO (imgname text, imgOID OID);
d682 1
a682 1
// All LargeObject API calls must be within a transaction
d688 1
a688 1
//create a new large object
d691 1
a691 1
//open the large object for write
d698 1
a698 1
// copy the data from the file to the large object
d701 3
a703 4
while ((s = fis.read(buf, 0, 2048)) > 0)
{
	obj.write(buf, 0, s);
	tl += s;
d709 2
a710 2
//Now insert the row into imagesLO
PreparedStatement ps = conn.prepareStatement("INSERT INTO imagesLO VALUES (?, ?)");
d717 2
a718 1
</para>
d723 1
a723 1
// All LargeObject API calls must be within a transaction
d729 1
a729 1
PreparedStatement ps = con.prepareStatement("SELECT imgOID FROM imagesLO WHERE imgname=?");
d733 9
a741 9
    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
d743 2
a744 2
	// Close the object
	obj.close();
d2442 1
a2442 1
  <title>Using the driver in a multithreaded or a servlet environment</title>
d2447 2
a2448 3
   time -- otherwise a thread could send a query while another one is
   receiving results, and this would be a bad thing for the database
   engine.
d2452 1
a2452 1
   The <productname>PostgreSQL</productname> <acronym>JDBC</acronym> Driver
d2455 2
a2456 2
   not have to worry about complex algorithms to ensure that only one
   uses the database at any time.
d2462 1
a2462 1
   current operation.  If it is a regular <acronym>SQL</acronym>
d2465 3
a2467 3
   is a <classname>Fastpath</classname> call (e.g., reading a block
   from a <classname>LargeObject</classname>) then it is the time to
   send and retrieve that block.
d2472 14
a2485 26
   performance problem with servlets.  With servlets you can have a
   heavy load on the connection. If you have several threads
   performing queries then each but one will pause, which may not be what
   you are after.
  </para>

  <para>
   To solve this, you would be advised to create a pool of
   connections.  When ever a thread needs to use the database, it asks
   a manager class for a <classname>Connection</classname>. The
   manager hands a free connection to the thread and marks it as
   busy. If a free connection is not available, it opens one.  Once
   the thread has finished with it, it returns it to the manager who
   can then either close it or add it to the pool. The manager would
   also check that the connection is still alive and remove it from
   the pool if it is dead.
  </para>

  <para>
   So, with servlets, it is up to you to use either a single
   connection, or a pool. The plus side for a pool is that threads
   will not be hit by the bottle neck caused by a single network
   connection. The down side is that it increases the load on the
   server, as a backend process is created for each
   <classname>Connection</classname>.  It is up to you and your
   applications requirements.
d2490 1
a2490 1
  <title>Connection Pools And DataSources</title>
d2492 1
a2492 4
  <sect2 id="jdbc-ds-version">
   <title>JDBC, JDK Version Support</title>

   <para>
d2498 1
a2498 1
    <acronym>JDBC</acronym> drivers support these features with
d2501 1
a2501 1
    (<acronym>JDBC</acronym> 2), or with <acronym>JDK</acronym> 1.4+
a2507 1
  </sect2>
d2510 4
a2513 2
    <title>JDBC Connection Pooling API</title>
    <para>The <acronym>JDBC</acronym> API provides a client
d2521 5
a2525 2
     driver.</para>
    <para>In an application server environment, the
d2532 5
a2536 2
     <productname>PostgreSQL</productname>).</para>
    <para>In an environment without an application server,
d2545 2
a2546 1
     <literal>ConnectionPoolDataSource</literal> interface.</para>
d2550 8
a2557 5
    <title>Application Servers: ConnectionPoolDataSource</title>
    <para><productname>PostgreSQL</productname> includes one
     implementation of <literal>ConnectionPoolDataSource</literal>
     for <acronym>JDBC</acronym> 2, and one for 
     <acronym>JDBC</acronym> 3:</para>
d2560 2
a2561 2
    <table>
    <title>ConnectionPoolDataSource Implementations</title>
d2583 9
a2591 1
    </table>
d2593 2
a2594 7
    <para>Both implementations use the same configuration scheme.
     <acronym>JDBC</acronym> requires that a
     <literal>ConnectionPoolDataSource</literal> be configured via
     JavaBean properties, so there are get and set methods for each of
     these properties:</para>
    <table>
    <title>ConnectionPoolDataSource Configuration Properties</title>
d2607 2
a2608 2
       <entry>serverName</entry>
       <entry><literal>String</literal></entry>
d2610 1
a2610 1
         hostname</entry>
d2614 2
a2615 2
       <entry>databaseName</entry>
       <entry><literal>String</literal></entry>
d2620 6
a2625 5
       <entry>portNumber</entry>
       <entry><literal>int</literal></entry>
       <entry><acronym>TCP/IP</acronym> port which the 
        <productname>PostgreSQL</productname> database server is
	listening on (or 0 to use the default port)</entry>
d2629 2
a2630 2
       <entry>user</entry>
       <entry><literal>String</literal></entry>
d2635 2
a2636 2
       <entry>password</entry>
       <entry><literal>String</literal></entry>
d2641 7
a2647 6
       <entry>defaultAutoCommit</entry>
       <entry><literal>boolean</literal></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>
d2651 1
a2651 1
    </table>
d2653 6
a2658 10
    <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.</para>

   <example id="jdbc-cpds-config">
    <title><literal>ConnectionPoolDataSource</literal> Configuration Example</title>

    <para>
     If the application server provides a single area to enter all
      the properties, they might be listed like this:
d2665 2
a2666 1
      Or, separated by semicolons instead of newlines, like this:
d2670 1
a2670 2
    </para>
   </example>
d2675 2
a2676 1
    <title>Applications: DataSource</title>
d2679 3
a2681 2
     for <acronym>JDBC</acronym> 2, and two for <acronym>JDBC</acronym>
     3.  The pooling implementations do not actually close connections
d2687 1
a2687 1
    <para>The pooling datasource implementation provided here is not
d2693 1
a2693 1
     provide more advanced pooling features, and use the
d2696 3
a2698 2
    <table>
    <title>DataSource Implementations</title>
d2738 2
a2739 1
    <para>All the implementations use the same configuration scheme.
d2741 4
a2744 3
     <literal>DataSource</literal> be configured via
     JavaBean properties, so there are get and set methods for each of
     these properties.</para>
d2746 2
a2747 2
    <table>
    <title>DataSource Configuration Properties</title>
d2760 2
a2761 2
       <entry>serverName</entry>
       <entry><literal>String</literal></entry>
d2763 1
a2763 1
         hostname</entry>
d2767 2
a2768 2
       <entry>databaseName</entry>
       <entry><literal>String</literal></entry>
d2773 3
a2775 3
       <entry>portNumber</entry>
       <entry><literal>int</literal></entry>
       <entry><acronym>TCP/IP</acronym> port which the 
d2781 2
a2782 2
       <entry>user</entry>
       <entry><literal>String</literal></entry>
d2787 2
a2788 2
       <entry>password</entry>
       <entry><literal>String</literal></entry>
d2796 1
a2796 1
      configuration properties:</para>
d2798 2
a2799 2
    <table>
    <title>Additional Pooling DataSource Configuration Properties</title>
d2812 2
a2813 2
       <entry>dataSourceName</entry>
       <entry><literal>String</literal></entry>
d2815 1
a2815 1
	 unique name</entry>
d2819 2
a2820 2
       <entry>initialConnections</entry>
       <entry><literal>int</literal></entry>
d2826 2
a2827 2
       <entry>maxConnections</entry>
       <entry><literal>int</literal></entry>
d2836 2
a2837 2
    <para>Here's an example of typical application code using a
     pooling <literal>DataSource</literal>:</para>
d2839 1
a2839 1
   <example id="jdbc-ds-code">
d2843 1
a2843 1
     Code to initialize a pooling DataSource might look like this:
d2855 2
a2856 2
      are closed, or else the pool will "leak" connections, and
      eventually lock all the clients out.
d2862 1
a2862 1
} catch(SQLException e) {
d2865 2
a2866 2
    if(con != null) {
        try {con.close();}catch(SQLException e) {}
d2875 4
a2878 2
    <title>DataSources and <acronym>JNDI</acronym></title>
    <para>All the <literal>ConnectionPoolDataSource</literal> and
d2880 1
a2880 1
     in <acronym>JNDI</acronym>.  In the case of the non-pooling
d2883 1
a2883 1
     same settings as the instance which was stored.  For the
d2885 1
a2885 1
     as long as it is available (e.g. not a different
d2888 5
a2892 2
     settings created otherwise.</para>
    <para>In the application server environment, typically the
d2897 4
a2900 2
     </para>
    <para>In an application environment, the application may store
d2904 4
a2907 1
     components that may need to use it:</para>
d2909 1
a2909 1
    <title><literal>DataSource</literal> <acronym>JNDI</acronym> Code Example</title>
d2912 1
a2912 1
     Application code to initialize a pooling DataSource and add
d2932 1
a2932 1
} catch(SQLException e) {
d2934 1
a2934 1
} catch(NamingException e) {
d2937 2
a2938 2
    if(con != null) {
        try {con.close();}catch(SQLException e) {}
a2945 5
  <sect2 id="jdbc-app-servers">
    <title>Specific Application Server Configurations</title>
    <para>Configuration examples for specific application servers
     will be included here.</para>
  </sect2>
d2952 1
a2952 1
   If you have not yet read it, I'd advise you read the
d2954 1
a2954 1
   (supplied with Sun's <acronym>JDK</acronym>), and the
d2957 1
a2957 1
   url="http://java.sun.com/products/jdbc/index.html">http://java.sun.com/products/jdbc/index.html</ulink>.
d2962 3
a2964 3
   url="http://jdbc.postgresql.org">http://jdbc.postgresql.org</ulink>
   contains updated information not included in this document, and
   also includes precompiled drivers.
@


1.42
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.41 2002/11/15 03:11:16 momjian Exp $
d127 1
a127 1
    Refer to the &cite-admin; for details.  The
@


1.41
log
@SGML improvements.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.40 2002/11/11 07:31:28 barry Exp $
d127 3
a129 3
    Refer to the <citetitle>Administrator's Guide</citetitle> for
    details.  The <acronym>JDBC</acronym> Driver supports the trust,
    ident, password, md5, and crypt authentication methods.
@


1.40
log
@Update jdbc doc to reflect correct name of the PGConnection class.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.39 2002/10/01 04:09:13 barry Exp $
d54 3
a56 3
    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 PostgreSQL installation
d60 5
a64 4
    running.  If you build with a 1.1 <acronym>JDK</> you will build a version
    that supports the JDBC 1 specification, if you build with a Java 2
    <acronym>JDK</> (e.g., <acronym>JDK</> 1.2 or <acronym>JDK</> 1.3) you will build a version that
    supports the JDBC 2 specification.
@


1.39
log
@Applied doc patch to jdbc doc which documents support for datasources
patch submitted by ammulder@@alumni.princeton.edu

 Modified Files:
 	jdbc.sgml
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.38 2002/09/21 18:32:53 petere Exp $
d687 1
a687 1
LargeObjectManager lobj = ((org.postgresql.Connection)conn).getLargeObjectAPI();
d728 1
a728 1
LargeObjectManager lobj = ((org.postgresql.Connection)conn).getLargeObjectAPI();
d777 1
a777 1
    methods in the <classname>org.postgresql.Connection</classname>
d784 1
a784 1
Fastpath fp = ((org.postgresql.Connection)db).getFastpathAPI();
d789 1
a789 1
    <title>Class <classname>org.postgresql.Connection</classname></title>
d792 1
a792 5
public class Connection extends Object implements Connection

java.lang.Object
   |
   +----org.postgresql.Connection
d797 1
a797 3
     <productname>PostgreSQL</productname>'s extensions. Methods
     defined by <classname>java.sql.Connection</classname> are not
     listed.
d819 1
a819 1
Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();
d854 1
a854 1
LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
d893 1
a893 1
((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name");
d935 1
a935 1
Fastpath fp = ((org.postgresql.Connection)conn).getFastpathAPI();
d940 1
a940 1
     <classname>org.postgresql.Connection</classname> is required, as
d2319 1
a2319 1
     This class can only be created by org.postgresql.Connection.  To
d2326 1
a2326 1
lobj = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
@


1.39.2.1
log
@Merge changes from head. (update classname for PGConnection)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.40 2002/11/11 07:31:28 barry Exp $
d687 1
a687 1
LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI();
d728 1
a728 1
LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI();
d777 1
a777 1
    methods in the <classname>org.postgresql.PGConnection</classname>
d784 1
a784 1
Fastpath fp = ((org.postgresql.PGConnection)db).getFastpathAPI();
d789 1
a789 1
    <title>Class <classname>org.postgresql.PGConnection</classname></title>
d792 5
a796 1
public class PGConnection 
d801 3
a803 1
     <productname>PostgreSQL</productname>'s extensions. 
d825 1
a825 1
Fastpath fp = ((org.postgresql.PGConnection)myconn).getFastpathAPI();
d860 1
a860 1
LargeObjectManager lo = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
d899 1
a899 1
((org.postgresql.PGConnection)myconn).addDataType("mytype","my.class.name");
d941 1
a941 1
Fastpath fp = ((org.postgresql.PGConnection)conn).getFastpathAPI();
d946 1
a946 1
     <classname>org.postgresql.PGConnection</classname> is required, as
d2325 1
a2325 1
     This class can only be created by org.postgresql.PGConnection.  To
d2332 1
a2332 1
lobj = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
@


1.38
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.37 2002/09/18 20:09:31 petere Exp $
d331 1
a331 1
    <title>Processing a Simple Query in <acronym>JDCB</acronym></title>
d2509 439
@


1.37
log
@Update installation instructions and put mostly everything in one place.
Also, some editing in PL/Perl and PL/Python chapters.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/jdbc.sgml,v 1.36 2002/03/22 19:20:11 petere Exp $
d60 1
a60 1
    running.  If you build with a 1.1 JDK you will build a version
d62 1
a62 1
    JDK (e.g., JDK 1.2 or JDK 1.3) you will build a version that
d548 1
a548 1
    <type>bytea</type> can hold upto 1Gig of binary data, it would 
d841 1
a841 1
         SQLException by Fastpath when initializing for first time
d1109 1
a1109 1
        rather than hard coding the oid. The oid for a function is not
d1121 1
a1121 1
        contains the function name, Column 2 the oid.  It reads the
d2157 1
a2157 1
           <term>buf</term>
d2164 1
a2164 1
           <term>off</term>
d2171 1
a2171 1
           <term>len</term>
d2205 1
a2205 1
           <term>buf</term>
d2212 1
a2212 1
           <term>off</term>
d2219 1
a2219 1
           <term>len</term>
d2353 1
a2353 1
       <term>public static final int WRITE</term>
d2360 1
a2360 1
       <term>public static final int READ</term>
d2367 1
a2367 1
       <term>public static final int READWRITE</term>
d2385 2
a2386 2
        method assumes that READ and WRITE access is required (the
        default).
d2407 1
a2407 1
        It defaults to READWRITE for the new object's attributes.
@


1.36
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.35 2002/01/20 22:19:56 petere Exp $
d54 10
a63 3
    Alternatively you can build the driver from source.  Although you 
    should only need to do this if you are making changes to the source
    code.
a64 58

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

   <para>
    To build the driver, add the <option>--with-java</option> option to your
    <filename>configure</filename> command line, e.g.,
<screen>
<prompt>$</prompt> <userinput>./configure --prefix=<replaceable>xxx</replaceable> --with-java ...</userinput>
</screen>
    This will build and install the driver along with the rest of the
    <productname>PostgreSQL</productname> package when you issue the
    <literal>make/gmake</literal> and <literal>make/gmake install</literal>
    commands.  If you only want to build the driver and not the rest
    of <productname>PostgreSQL</productname>, change into the
    directory <filename
    class="directory">src/interfaces/jdbc</filename> and issue the
    respective <literal>make/gmake</literal> command there.  Refer to the
    <productname>PostgreSQL</productname> installation instructions
    for more information about the configuration and build process.
   </para>

   <para>When building the driver from source the jar file that is created
    will be named <filename>postgresql.jar</filename>.  The build will 
    create this file in the <filename>src/interfaces/jdbc/jars</filename>
    directory.  The resulting driver will be built for the version of 
    Java you are running.  If you build with a 1.1 JDK you will build
    a version that supports the jdbc1 specification, if you build with a 
    Java2 JDK (i.e. JDK1.2 or JDK1.3) you will build a version that 
    supports the jdbc2 specification. 
   </para>
 
   <note>
    <para>
     Do not try to build the driver by calling <command>javac</command> 
     directly, as the driver uses some dynamic loading techniques for
     performance reasons, and <command>javac</command> cannot cope.
     Do not try to run <command>ant</command> directly either, because
     some configuration information is communicated through the
     makefiles.  Running <command>ant</command> directly without
     providing these parameters will result in a broken driver.
    </para>
   </note>
d71 1
a71 1
    To use the driver, the jar archive (named
d74 1
a74 1
    <filename>jdbc7.2-1.2.jar</filename> for the jdbc1 and jdbc2 versions
d79 1
a79 7
    <command>java</command> command line.  By default, the jar archive
    is installed in the directory <filename
    class="directory">/usr/local/pgsql/share/java</filename>.  You may
    have it in a different directory if you used the
    <option>--prefix</option> option when you ran
    <filename>configure</filename>, or if you are using a binary distribution
    that places it in some different location.
a81 1
   <informalexample>
a107 1
   </informalexample>
d127 1
a127 1
    details.  The <acronym>JDBC</acronym> Driver supports trust,
@


1.35
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.34 2001/11/29 05:35:51 barry Exp $
d1213 1
a1213 1
         Do not think that manually converting them to the oid's will
d2508 1
a2508 1
  <title>Using the driver in a multi-threaded or a servlet environment</title>
@


1.34
log
@Updated jdbc docs to reflect the doc comments received.  Most comments were
already addressed by previous doc updates.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.33 2001/11/27 13:02:33 ishii Exp $
d595 1
a595 1
    <application>PostgreSQL's</application> binary datatype 
d605 1
a605 1
    <type>bytea</type> datatype is not well suited for storing very 
d622 1
a622 1
    that supports the <type>bytea</type> datatype.  The introduction of 
d628 2
a629 2
    the <type>bytea</type> datatype.  In 7.1 these methods operated 
    on the <type>OID</type> datatype associated with Large Objects.  
d637 1
a637 1
    To use the <type>bytea</type> datatype you should simply use 
d666 1
a666 1
      <type>bytea</type> datatypes.  So it is recommended that you 
d731 1
a731 1
    Alternativly you could be storing a very large file and want to use
@


1.33
log
@Fix imcomplete SGML tag.
Please check compile errors before you commit!
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.32 2001/11/27 01:20:17 barry Exp $
d517 11
@


1.32
log
@formating and spelling fixes to my last doc update
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.29 2001/11/26 05:57:57 barry Exp $
d767 1
a767 1

@


1.31
log
@More tag cleanups.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.30 2001/11/26 18:51:19 momjian Exp $
d382 2
a383 3
    a <classname>Statement</classname> or <classname>PreparedStatement
    </classname>, you
    can use issue a
d408 1
a408 1
     This example will issues the same query as before using 
d432 2
a433 1
     <classname>Statement</classname> interface:
d443 2
a444 1
        <classname>Statement</classname> at a given time.
d468 2
a469 1
        you should close the <classname>Statement</classname>.
d537 2
d551 1
d565 2
d575 1
d582 1
a582 1
    <application>PostgreSQL</application> provides two distinct way to 
d587 2
a588 1
    format, and refers to from your own tables by an <type>OID</type> value.
d610 2
a611 2
    7.2 is the first release that the <acronym>JDBC</acronym> Driver 
    supports the <type>bytea</type> datatype.  The introduction of 
d714 1
a714 1
    Here you can see how the Large Object is retrieved as an
d733 2
d774 2
d791 1
a791 1
	}
@


1.30
log
@Fix SGML tag misspelling.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.29 2001/11/26 05:57:57 barry Exp $
d587 1
a587 1
    <type>bytea</bytea> can hold upto 1Gig of binary data, it would 
d626 1
a626 1
    provided by the <application>PostgreSQL</applicaiton> 
d647 1
a647 1
      use the <classname>LargeObject</classname> <acronyn>API</acronym> 
d2495 1
a2495 1
   The <productname>PostgreSQL</productname> <acronyn>JDBC</acronym> Driver
@


1.29
log
@Updates to JDBC doc:
  Editing pass over entire chapter
  Rewrote section dealing with Large Objects to also talk about bytea support
  Removed secion on Serialize functionality a we intend to remove it in the
   next release
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.28 2001/11/21 05:53:41 thomas Exp $
d576 1
a576 1
    <applicaiton>PostgreSQL's</application> binary datatype 
@


1.28
log
@Deprecate 'current' for date/time input.
Fix up references to "PostgreSQL" rather than "Postgres". Was roughly
 evenly split between the two before. ref/ files not yet done.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.27 2001/10/25 22:00:31 barry Exp $
d380 5
a384 3
    the database, you require a <classname>Statement</classname>
    instance. Once you have a <classname>Statement</classname>, you
    can use the <function>executeQuery()</function> method to issue a
d394 2
a395 2
     This example with issue a simple query and print out the first
     column of each row.
d398 19
a416 1
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
d428 2
a429 1
    <title>Using the <classname>Statement</classname> Interface</title>
d443 1
a443 1
        <classname>Statement</classname>.
d463 7
d526 33
a558 3
    To perform an update (or any other <acronym>SQL</acronym>
    statement that does not return a result), you simply use the
    <function>executeUpdate()</function> method:
d560 2
d563 3
a565 1
st.executeUpdate("CREATE TABLE basic (a int, b int)");
d570 52
a621 2
 <sect1 id="jdbc-lo">
  <title>Using Large Objects</title>
d624 6
a629 5
   In <application>PostgreSQL</application>, <firstterm>Large
   Objects</firstterm> (also known as <acronym>BLOB</acronym>s) are
   used to hold data in the database that cannot be stored in a normal
   SQL table. They are stored in a separate table in a special format,
   and are referred to from your own tables by an OID value.
d634 1
a634 1
    For <productname>PostgreSQL</productname>, you must access Large
d638 1
a638 7
    parameter of <literal>false</literal>:
<programlisting>
Connection mycon;
...
mycon.setAutoCommit(false);
... // now use Large Objects
</programlisting>
d642 8
a649 9
   <para>
    There are two methods of using Large Objects. The first is the
    standard <acronym>JDBC</acronym> way, and is documented here. The
    other, uses <productname>PostgreSQL</productname> extensions to
    the <acronym>API</acronym>, which presents the <application>libpq</application> large object
    <acronym>API</acronym> to Java, providing even better access to
    large objects than the standard. Internally, the driver uses the
    extension to provide large object support.
   </para>
a650 11
   <para>
    In <acronym>JDBC</acronym>, the standard way to access Large
    Objects is using the <function>getBinaryStream()</function> method
    in <classname>ResultSet</classname>, and
    <function>setBinaryStream()</function> method in
    <classname>PreparedStatement</classname>. These methods make the
    large object appear as a Java stream, allowing you to use the
    <literal>java.io</literal> package, and others, to manipulate the
    object.  <xref linkend="jdbc-lo-example"> illustrates the usage of
    this approach.
   </para>
d652 2
a653 2
  <example id="jdbc-lo-example">
   <title>Using the <acronym>JDBC</acronym> Large Object Interface</title>
d657 2
a658 1
    an image and you have a large object containing that image:
d660 1
a660 1
CREATE TABLE images (imgname text, imgoid oid);
d669 1
a669 1
PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)"); <co id="co.jdbc-qmark">
d676 6
a681 13
    <calloutlist>
     <callout arearefs="co.jdbc-qmark">
      <para>
       The question marks must appear literally.  The actual data is
       substituted by the next lines.
      </para>
     </callout>
    </calloutlist>
    Here, <function>setBinaryStream</function> transfers a set number
    of bytes from a stream into a Large Object, and stores the OID
    into the field holding a reference to it.  Notice that the
    creation of the Large Object itself in the database happens
    transparently.
d690 1
a690 1
PreparedStatement ps = con.prepareStatement("SELECT imgoid FROM images WHERE imgname=?");
d695 1
a695 1
        InputStream is = rs.getBinaryStream(1);
a696 1
        is.close();
d706 80
a785 6
    <classname>InputStream</classname>.  You will also notice that we
    close the stream before processing the next row in the
    result. This is part of the <acronym>JDBC</acronym> specification,
    which states that any <classname>InputStream</classname> returned
    is closed when <function>ResultSet.next()</function> or
    <function>ResultSet.close()</function> is called.
d787 1
d2098 2
a2099 4
     Normally, client code would use the getAsciiStream,
     getBinaryStream, or getUnicodeStream methods in <classname>ResultSet</classname>, or
     setAsciiStream, setBinaryStream, or setUnicodeStream methods in
     <classname>PreparedStatement</classname> to access Large Objects.
d2103 2
a2104 2
     However, sometimes lower level access to Large Objects are
     required, that are not supported by the <acronym>JDBC</acronym>
d2372 3
a2374 5
     Normally, client code would use the getAsciiStream,
     getBinaryStream, or getUnicodeStream methods in ResultSet, or
     setAsciiStream, setBinaryStream, or setUnicodeStream methods in
     PreparedStatement to access Large Objects.  However, sometimes
     lower level access to Large Objects are required, that are not
d2480 1
a2481 615
  <sect2>
   <title>Object Serialization</title>

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

   <para>
    One of the consequences of this, is that you can have one table
    refer to a row in another table.  For example:
<screen>
test=> CREATE TABLE users (username NAME,fullname TEXT);
CREATE
test=> CREATE TABLE server (servername NAME,adminuser users);
CREATE
test=> INSERT INTO users VALUES ('peter','Peter Mount');
INSERT 2610132 1
test=> INSERT INTO server VALUES ('maidast',2610132::users);
INSERT 2610133 1
test=> SELECT * FROM users;
username|fullname      
--------+--------------
peter   |Peter Mount   
(1 row)

test=> SELECT * FROM server;
servername|adminuser
----------+---------
maidast   |  2610132
(1 row)
</screen>
    Okay, the above example shows that we can use a table name as a
    field, and the row's oid value is stored in that field.
   </para>

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

   <para>
    In Java, you can store an object to a Stream as long as it's class
    implements the java.io.Serializable interface. This process, known
    as Object Serialization, can be used to store complex objects into
    the database.
   </para>

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

   <para>
    What the org.postgresql.util.Serialize class does, is provide a
    means of storing an object as a table, and to retrieve that object
    from a table. In most cases, you would not need to access this
    class direct, but you would use the PreparedStatement.setObject()
    and ResultSet.getObject() methods. Those methods will check the
    objects class name against the table's in the database. If a match
    is found, it assumes that the object is a Serialized object, and
    retrieves it from that table. As it does so, if the object
    contains other serialized objects, then it recurses down the tree.
   </para>

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

   <para>
    The only time you would access this class, is to use the create()
    methods. These are not used by the driver, but issue one or more
    <command>CREATE TABLE</command> statements to the database, based on a Java Object
    or Class that you want to serialize.
   </para>

   <para>
    Oh, one last thing. If your object contains a line like:
<programlisting>
public int oid;
</programlisting>
    then, when the object is retrieved from the table, it is set to
    the oid within the table. Then, if the object is modified, and re-
    serialized, the existing entry is updated.
   </para>

   <para>
    If the oid variable is not present, then when the object is
    serialized, it is always inserted into the table, and any existing
    entry in the table is preserved.
   </para>

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

<programlisting>
Class org.postgresql.util.Serialize

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

   public class Serialize extends Object

   This class uses <productname>PostgreSQL</productname>'s object oriented features to store Java 
Objects. It does this by mapping a Java Class name to a table in the 
database. Each entry in this new table then represents a Serialized 
instance of this class. As each entry has an OID (Object IDentifier), 
this OID can be included in another table. This is too complex to show 
here, and will be documented in the main documents in more detail.

Constructors

 public Serialize(org.postgresql.Connection c,
                  String type) throws SQLException

          This creates an instance that can be used to serialize 
or deserialize a Java object from a <productname>PostgreSQL</productname> table.

Methods

 public Object fetch(int oid) throws SQLException

          This fetches an object from a table, given it's OID

        Parameters:
                oid - The oid of the object

        Returns:
                Object relating to oid

        Throws: SQLException
                on error

 public int store(Object o) throws SQLException

          This stores an object into a table, returning it's OID.

          If the object has an int called OID, and it is > 0, then 
that value is used for the OID, and the table will be updated. If the 
value of OID is 0, then a new row will be created, and the value of 
OID will be set in the object. This enables an object's value in the 
database to be updateable. If the object has no int called OID, then 
the object is stored. However if the object is later retrieved, 
amended and stored again, it's new state will be appended to the 
table, and will not overwrite the old entries.

        Parameters:
                o - Object to store (must implement Serializable)

        Returns:
                oid of stored object

        Throws: SQLException
                on error
 
 public static void create(org.postgresql.Connection con,
                           Object o) throws SQLException

          This method is not used by the driver, but it creates a 
table, given a Serializable Java Object. It should be used before 
serializing any objects.

        Parameters:
                c - Connection to database
                o - Object to base table on

        Throws: SQLException
                on error

 public static void create(org.postgresql.Connection con,
                           Class c) throws SQLException

          This method is not used by the driver, but it creates a 
table, given a Serializable Java Object. It should be used before 
serializing any objects.

        Parameters:
                c - Connection to database
                o - Class to base table on

        Throws: SQLException
                on error

 public static String toPostgreSQL(String name) throws SQLException
          
          This converts a Java Class name to a <productname>PostgreSQL</productname> table, by
          replacing . with _

          Because of this, a Class name may not have _ in the name.

          Another limitation, is that the entire class name (including
          packages) cannot be longer than 31 characters (a limit 
forced by <productname>PostgreSQL</productname>).

        Parameters:
                name - Class name

        Returns:
                <productname>PostgreSQL</productname> table name

        Throws: SQLException
                on error
          
 public static String toClassName(String name) throws SQLException

          This converts a <productname>PostgreSQL</productname> table to a Java Class name, by
          replacing _ with .

        Parameters:
                name - <productname>PostgreSQL</productname> table name
  
        Returns:
                Class name

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

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

Class org.postgresql.util.PGmoney
                                
java.lang.Object
   |
   +----org.postgresql.util.PGobject
           |
           +----org.postgresql.util.PGmoney

   public class PGmoney extends PGobject implements Serializable, 
Cloneable
               
   This implements a class that handles the <productname>PostgreSQL</productname> money type

Variables

 public double val
                                
          The value of the field

Constructors
           
 public PGmoney(double value)
   
        Parameters:
                value - of field
               
 public PGmoney(String value) throws SQLException
   
          Create a money.

        Parameters:
                value - Definition of this money in <productname>PostgreSQL</productname>'s 
syntax

 public PGmoney()

          Required by the driver

Methods

 public void setValue(String s) throws SQLException

        Parameters:
                s - Definition of this money 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 moneys 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 PGmoney in the syntax expected by <productname>PostgreSQL</productname>

        Overrides:
                getValue in class PGobject

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

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

   public class PGobject extends Object implements Serializable, 
Cloneable
               
   This class is used to describe data types that are unknown by
     <acronym>JDBC</acronym> 
Standard.
    A call to org.postgresql.Connection permits a class that extends this 
class to be associated with a named type. This is how the 
org.postgresql.geometric package operates.
    ResultSet.getObject() will return this class for any type that is 
not recognized on having it's own handler. Because of this, any 
<productname>PostgreSQL</productname> data type is supported.

Constructors

 public PGobject()

          This is called by org.postgresql.Connection.getObject() to 
create the object.

Methods

 public final void setType(String type)

          This method sets the type of this object.

          It should not be extended by subclasses, hence its final

        Parameters:
                type - a string describing the type of the object

 public void setValue(String value) throws SQLException

          This method sets the value of this object. It must be 
overridden.

        Parameters:
                value - a string representation of the value of the
                object

        Throws: SQLException
                thrown if value is invalid for this type
    
 public final String getType()

          As this cannot change during the life of the object, it's 
final.

        Returns:
                the type name of this object

 public String getValue()

          This must be overridden, to return the value of the object, 
in the form required by <productname>PostgreSQL</productname>.

        Returns:
                the value of this object

 public boolean equals(Object obj)

          This must be overridden to allow comparisons of objects

        Parameters:
                obj - Object to compare with

        Returns:
                true if the two objects are identical

        Overrides:
                equals in class Object

 public Object clone()

          This must be overridden to allow the object to be cloned

        Overrides:
                clone in class Object

 public String toString()

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

        Overrides:
                toString in class Object

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

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

   public class PGtokenizer extends Object

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

   We could have used StringTokenizer to do this, however, we needed 
to handle nesting of '(' ')' '[' ']' '<' and '>' as these are used by 
the geometric data types.

   It's mainly used by the geometric classes, but is useful in parsing 
any output from custom data types output from <productname>PostgreSQL</productname>.
                 
   See Also:
          PGbox, PGcircle, PGlseg, PGpath, PGpoint, PGpolygon
          
Constructors

 public PGtokenizer(String string,
                    char delim)

          Create a tokenizer.

        Parameters:
                string - containing tokens
                delim - single character to split the tokens

Methods
        
 public int tokenize(String string,
                     char delim)

          This resets this tokenizer with a new string and/or 
delimiter.

        Parameters:
                string - containing tokens
                delim - single character to split the tokens

 public int getSize()

        Returns:
                the number of tokens available

 public String getToken(int n)

        Parameters:
                n - Token number ( 0 ... getSize()-1 )

        Returns:
                The token value

 public PGtokenizer tokenizeToken(int n,
                                  char delim)

          This returns a new tokenizer based on one of our tokens. The 
geometric data types use this to process nested tokens (usually 
PGpoint).

        Parameters:
                n - Token number ( 0 ... getSize()-1 )
                delim - The delimiter to use

        Returns:
                A new instance of PGtokenizer based on the token

 public static String remove(String s,
                             String l,
                             String t)

          This removes the lead/trailing strings from a string

        Parameters:
                s - Source string
                l - Leading string to remove
                t - Trailing string to remove
                
        Returns:
                String without the lead/trailing strings

 public void remove(String l,
                    String t)

          This removes the lead/trailing strings from all tokens

        Parameters:
                l - Leading string to remove
                t - Trailing string to remove

 public static String removePara(String s)

          Removes ( and ) from the beginning and end of a string

        Parameters:
                s - String to remove from

        Returns:
                String without the ( or )

 public void removePara()

          Removes ( and ) from the beginning and end of all tokens

 public static String removeBox(String s)
   
          Removes [ and ] from the beginning and end of a string

        Parameters:
                s - String to remove from
   
        Returns:
                String without the [ or ]

 public void removeBox()

          Removes [ and ] from the beginning and end of all tokens

 public static String removeAngle(String s)

          Removes < and > from the beginning and end of a string

        Parameters:
                s - String to remove from

        Returns:
                String without the < or >

 public void removeAngle()

          Removes < and > from the beginning and end of all tokens

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

This was documented earlier under Object Serialization.

Class org.postgresql.util.UnixCrypt
              
java.lang.Object
   |
   +----org.postgresql.util.UnixCrypt

   public class UnixCrypt extends Object

   This class provides us with the ability to encrypt passwords when 
sent over the network stream

   Contains static methods to encrypt and compare passwords with Unix 
encrypted passwords.

   See John Dumas's Java Crypt page for the original source.  

   (Invalid URL) http://www.zeh.com/local/jfd/crypt.html

Methods

 public static final String crypt(String salt,
                                  String original)

          Encrypt a password given the clear-text password and a 
<quote>salt</quote>.
   
        Parameters:
                salt - A two-character string representing the salt 
used
                to iterate the encryption engine in lots of different
                ways. If you are generating a new encryption then this
                value should be randomized.
                original - The password to be encrypted.

        Returns:
                A string consisting of the 2-character salt followed 
by
                the encrypted password.
              
 public static final String crypt(String original)

          Encrypt a password given the clear-text password. This method 
generates a random salt using the 'java.util.Random' class.

        Parameters:
                original - The password to be encrypted.
   
        Returns: 
                A string consisting of the 2-character salt followed 
by
                the encrypted password.
               
 public static final boolean matches(String encryptedPassword,
                                     String enteredPassword)
                 
          Check that enteredPassword encrypts to encryptedPassword.
               
        Parameters:
                encryptedPassword - The encryptedPassword. The first 
two characters are assumed to be the salt. This string would be the 
same as one found in a Unix /etc/passwd file.
                enteredPassword - The password as entered by the user 
(or otherwise acquired).

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

 </sect1>
<!-- **************************************************************** -->
d2495 2
a2496 3
   <productname>PostgreSQL</productname> 6.4 brought thread safety to
   the entire driver.  (Standard <acronym>JDBC</acronym> was thread
   safe in 6.3, but the Fastpath <acronym>API</acronym> was not.)
@


1.27
log
@updates to jdbc documentation for 7.2
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.26 2001/10/12 23:32:33 momjian Exp $
d23 1
a23 1
   <application>Postgres</application> provides a <firstterm>type
d228 1
a228 1
    For <application>Postgres</application>, you would use:
d248 1
a248 1
    use just <productname>Postgres</productname>.  If your code may
d250 1
a250 1
    any <productname>Postgres</productname>-specific extensions, then
d288 1
a288 1
    <application>Postgres</application>, this takes one of the
d332 1
a332 1
        Postgres standard port number (5432).
d468 1
a468 1
        <productname>Postgres</productname> driver will allow you to
d512 1
a512 1
   In <application>Postgres</application>, <firstterm>Large
d521 1
a521 1
    For <productname>Postgres</productname>, you must access Large
d634 1
a634 1
   <productname>Postgres</productname> is an extensible database
d637 1
a637 1
   these are facilities unique to <productname>Postgres</productname>,
d759 1
a759 1
        PostgreSQL's more unique data types. Normally, a data type not
d844 1
a844 1
        Send a function call to the PostgreSQL backend.
d874 1
a874 1
        Send a function call to the PostgreSQL backend by name.
d1008 1
a1008 1
         PostgreSQL stores the function id's and their corresponding
d1230 1
a1230 1
                s - Box definition in PostgreSQL syntax
d1327 1
a1327 1
                s - definition of the circle in PostgreSQL's syntax.
d1341 1
a1341 1
                s - definition of the circle in PostgreSQL's syntax.
d1420 1
a1420 1
                s - definition of the line in PostgreSQL's syntax.
d1434 1
a1434 1
                s - Definition of the line segment in PostgreSQL's 
d1513 1
a1513 1
                s - Definition of the line segment in PostgreSQL's syntax.
d1527 1
a1527 1
                s - Definition of the line segment in PostgreSQL's 
d1603 1
a1603 1
                s - definition of the path in PostgreSQL's syntax.
d1613 1
a1613 1
                s - Definition of the path in PostgreSQL's syntax
d1705 1
a1705 1
                value - Definition of this point in PostgreSQL's 
d1717 1
a1717 1
                s - Definition of this point in PostgreSQL's syntax
d1823 1
a1823 1
   This implements the polygon data type within PostgreSQL.
d1843 1
a1843 1
                s - definition of the polygon in PostgreSQL's syntax.
d1857 1
a1857 1
                s - Definition of the polygon in PostgreSQL's syntax
d1900 1
a1900 1
    limited, and the <acronym>API</acronym> provided by PostgreSQL allows for random
d2432 1
a2432 1
   This class uses PostgreSQL's object oriented features to store Java 
d2445 1
a2445 1
or deserialize a Java object from a PostgreSQL table.
d2521 1
a2521 1
forced by PostgreSQL).
d2527 1
a2527 1
                PostgreSQL table name
d2538 1
a2538 1
                name - PostgreSQL table name
d2562 1
a2562 1
   This implements a class that handles the PostgreSQL money type
d2582 1
a2582 1
                value - Definition of this money in PostgreSQL's 
d2594 1
a2594 1
                s - Definition of this money in PostgreSQL's syntax
@


1.26
log
@Uppercase keywords where appropriate.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.25 2001/09/13 15:55:22 petere Exp $
d11 2
a12 2
    Written by Peter T. Mount (<email>peter@@retep.org.uk</email>), the
    author of the <acronym>JDBC</acronym> driver.
d44 1
a44 1
   <title>Building the Driver</title>
d47 1
a47 1
    Precompiled versions of the driver are regularly made available on
d50 7
a56 2
    <acronym>JDBC</acronym> web site</ulink>.  Here we describe how to
    build the driver manually.
d78 1
a78 1
    The build the driver, add the <option>--with-java</option> option to your
d85 1
a85 1
    <literal>gmake</literal> and <literal>gmake install</literal>
d90 1
a90 1
    respective <literal>make</literal> command there.  Refer to the
d95 10
d107 2
a108 2
     Do not try to build by calling <command>javac</command> directly,
     as the driver uses some dynamic loading techniques for
d122 6
a127 2
    To use the driver, the jar archive
    <filename>postgresql.jar</filename> needs to be included in the
d135 2
a136 1
    <filename>configure</filename>.
d147 1
a147 1
     <filename>/usr/local/jdk1.1.6</filename>.  To run the
d151 1
a151 1
java uk.org.retep.finder.Main
d156 1
a156 1
        <filename>finder.jar</filename> contains my application.
d173 6
a178 4
    Because Java can only use TCP/IP connections, the
    <application>Postgres</application> server must be configured to
    accept TCP/IP connections, for instance by supplying the
    <option>-i</option> option flag when starting the
d187 1
a187 1
    ident, password, and md5, crypt authentication methods.
@


1.25
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.24 2001/09/12 15:55:00 momjian Exp $
d2314 1
a2314 1
test=> create table users (username name,fullname text);
d2316 1
a2316 1
test=> create table server (servername name,adminuser users);
d2318 1
a2318 1
test=> insert into users values ('peter','Peter Mount');
d2320 1
a2320 1
test=> insert into server values ('maidast',2610132::users);
d2322 1
a2322 1
test=> select * from users;
d2328 1
a2328 1
test=> select * from server;
@


1.24
log
@Attached patch is correction for 'doc/jdbc.sgml' of PostgreSQL 7.1.3.

Correction content:
  * I revised a mistake of type (copy and paste).
  * I revised multiplicity of description.

Ryouichi Matsuda
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.23 2001/09/12 15:49:10 momjian Exp $
d2375 1
a2375 1
    "create table" statements to the database, based on a Java Object
d2868 1
a2868 1
"salt".
@


1.23
log
@Followings are proposed fixes to jdbc.sgml(line numbers are for 7.1.3
doc).

Hiroyuki Yatabe
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.22 2001/09/10 21:58:46 petere Exp $
d1333 1
a1333 1
                true if the two boxes are identical
d1398 1
a1398 1
                s - definition of the circle in PostgreSQL's syntax.
d1427 1
a1427 1
                true if the two boxes are identical
d1491 1
a1491 1
                s - definition of the circle in PostgreSQL's syntax.
d1520 1
a1520 1
                true if the two boxes are identical
d1581 1
a1581 1
                s - definition of the circle in PostgreSQL's syntax.
d1605 1
a1605 1
                true if the two boxes are identical
d1619 1
a1619 1
          This returns the polygon in the syntax expected by 
d1709 1
a1709 1
                true if the two boxes are identical
d1821 1
a1821 1
                s - definition of the circle in PostgreSQL's syntax.
d1849 1
a1849 1
                true if the two boxes are identical
a2475 28
                   Returns:
                Object relating to oid

        Throws: SQLException
                on error

 public int store(Object o) throws SQLException

          This stores an object into a table, returning it's OID.

          If the object has an int called OID, and it is > 0, then 
that value is used for the OID, and the table will be updated. If the 
value of OID is 0, then a new row will be created, and the value of 
OID will be set in the object. This enables an object's value in the 
database to be updateable. If the object has no int called OID, then 
the object is stored. However if the object is later retrieved, 
amended and stored again, it's new state will be appended to the 
table, and will not overwrite the old entries.

        Parameters:
                o - Object to store (must implement Serializable)

        Returns:
                oid of stored object

        Throws: SQLException
                on error
 
a2476 14
                           Object o) throws SQLException

          This method is not used by the driver, but it creates a 
table, given a Serializable Java Object. It should be used before 
serializing any objects.

        Parameters:
                c - Connection to database
                o - Object to base table on

        Throws: SQLException
                on error
                
 public static void create(Connection con,
d2557 1
a2557 2
          This is called mainly from the other geometric types, when a 
point is imbeded within their definition.
d2560 1
a2560 1
                value - Definition of this point in PostgreSQL's 
d2572 1
a2572 1
                s - Definition of this point in PostgreSQL's syntax
d2586 1
a2586 1
                true if the two boxes are identical
d2601 1
a2601 1
                the PGpoint in the syntax expected by <productname>PostgreSQL</productname>
d2680 1
a2680 1
                true if the two boxes are identical
a2810 3
        Returns:
                String without the ( or )

a2824 3
        Returns:
                String without the [ or ]

a2837 3

        Returns:
                String without the < or >
@


1.22
log
@Markup and spell-check run over Programmer's Guide (rather incomplete still).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.21 2001/08/16 16:24:15 momjian Exp $
d579 1
a579 1
PreparedStatement ps = con.prepareStatement("SELECT oid FROM images WHERE name=?");
d584 1
a584 1
        InputStream is = rs.getBinaryInputStream(1);
d1280 1
a1280 1
public double radius
d1996 1
a1996 1
public void read(byte buf[],
d2419 1
a2419 1
 public Serialize(Connection c,
d2462 1
a2462 1
 public static void create(Connection con,
d2504 1
a2504 1
 public static void create(Connection con,
d2910 1
a2910 1
   See John Dumas's Java Crypt page for the original source.
d2912 1
a2912 1
   http://www.zeh.com/local/jfd/crypt.html
@


1.21
log
@Add new MD5 pg_hba.conf keyword.  Prevent fallback to crypt.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.20 2001/03/11 11:06:59 petere Exp $
d517 1
a517 1
    the <acronym>API</acronym>, which presents the libpq large object
d677 1
a677 1
        where myconn is an open Connection to <productname>PostgreSQL</productname>.
d712 1
a712 1
        where myconn is an open Connection to
d719 1
a719 1
         LargeObject object that implements the <acronym>API</acronym>
d726 1
a726 1
         SQLException by LargeObject when initializing for first time
d738 3
a740 3
        known by the driver is returned by ResultSet.getObject() as a
        PGobject instance.  This method allows you to write a class
        that extends PGobject, and tell the driver the type name, and
d752 1
a752 1
        where myconn is an open Connection to
d775 1
a775 1
     exists within the libpq C interface, and allows a client machine
d828 2
a829 2
                fnid - Function id
                resulttype - True if the result is an integer, false 
d832 1
a832 1
                args - FastpathArguments to pass to fastpath
d858 1
a858 1
         exist, usually to an earlier call to addfunction(). This is
d868 2
a869 2
                name - Function name
                resulttype - True if the result is an integer, false 
d872 1
a872 1
                args - FastpathArguments to pass to fastpath
d902 2
a903 2
                name - Function name
                args - Function arguments
d915 1
a915 1
         SQLException if a database-access error occurs or no result
d933 2
a934 2
                name - Function name
                args - Function arguments
d946 1
a946 1
         SQLException if a database-access error occurs or no result
d987 1
a987 1
         names in the pg_proc table. To speed things up locally,
d1005 1
a1005 1
         work. Okay, they will for now, but they can change during
d1026 2
a1027 2
        addFunction() or addFunctions() have not been called for this
        name, then an SQLException is thrown.
d1115 1
a1115 1
           <term>buf</term>
d1122 1
a1122 1
           <term>off</term>
d1129 1
a1129 1
           <term>len</term>
d1883 1
a1883 1
    The org.postgresql.largeobject package provides to Java the libpq
@


1.20
log
@Add uninstall target to Java build.
Respect default port setting in JDBC driver.
Pick up version number from Makefile.global.
Change installation directory to share/java/.
Document.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.19 2001/02/24 12:40:27 petere Exp $
d165 1
a165 1
    ident, password, and crypt authentication methods.
@


1.19
log
@Markup, spell check, refine JDBC documentation.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.18 2000/12/22 21:51:58 petere Exp $
d56 2
a57 2
    the preferred way to build the <acronym>JDBC</acronym> driver is
    using <productname>Ant</productname>, a special tool for building
d59 11
a69 24
    <productname>Ant</productname> from the <ulink
    url="http://jakarta.apache.org/ant/index.html"><productname>Ant</productname>
    web site</ulink> and install it before proceeding.
   </para>

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

   <para>
    To install the driver, enter the command
<screen>
<prompt>$</prompt> <userinput>ant -Dinstall.directory=<replaceable>mydir</replaceable> install</userinput>
</screen>
    Replace <replaceable>mydir</replaceable> with a directory name of
    your choice; the directory will be created if necessary.  The
    <productname>PostgreSQL</productname> <acronym>JDBC</acronym>
    driver consists of a <filename>postgresql.jar</filename> file that
    will be copied to that directory.
d73 2
a74 5
    Alternatively, you can use the old <command>make</command>-based
    interface.  The driver's source is located in the <filename
    class="directory">src/interfaces/jdbc</filename> directory of the
    source tree. To compile, simply change directory to that
    directory, and type:
d76 1
a76 1
<prompt>$</prompt> <userinput>gmake</userinput>
d78 10
a87 4
    (Remember to use <acronym>GNU</acronym> make.)  Upon completion,
    you will find the archive <filename>postgresql.jar</filename> in
    the current directory. This is the <acronym>JDBC</acronym> driver,
    which you can copy to an appropriate directory in your system.
d92 7
a98 3
     You must not use <command>javac</command> directly, as the
     driver uses some dynamic loading techniques for performance
     reasons, and <command>javac</command> cannot cope.
d111 6
a116 1
    <command>java</command> command line.
d130 1
a130 1
export CLASSPATH=/usr/local/lib/finder.jar<co id="co.jdbc-finder">:/usr/local/lib/postgresql.jar:.
@


1.18
log
@Make use of <email> tag for marking up email addresses.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.17 2000/12/22 18:57:49 petere Exp $
d6 1
a6 1
  <title>JDBC Interface</title>
d8 7
a14 9
  <para>
   <note>
    <title>Author</title>
    <para>
     Written by Peter T. Mount (<email>peter@@retep.org.uk</email>), the
     author of the <acronym>JDBC</acronym> driver.
    </para>
   </note>
  </para>
d23 15
a37 6
   <application>Postgres</application> provides 
   a <firstterm>type 4</firstterm> <acronym>JDBC</acronym> Driver.
   Type 4 indicates that the driver
   is written in Pure Java, and communicates in the database's own network
   protocol. Because of this, the driver is platform independent. Once compiled,
   the driver can be used on any platform.
d40 2
a41 2
  <sect1 id="jdbc-build">
   <title>Building the <acronym>JDBC</acronym> Interface</title>
d43 10
a52 2
   <sect2>
    <title>Compiling the Driver</title>
d54 9
a62 9
    <para>
     The driver's source is located in the <filename>src/interfaces/jdbc</filename>
     directory of the
     source tree. To compile simply change directory to that directory, and type:

     <programlisting>
% make
     </programlisting>
    </para>
d64 8
a71 4
    <para>
     Upon completion, you will find the archive <filename>postgresql.jar</filename>
     in the current
     directory. This is the <acronym>JDBC</acronym> driver.
d73 11
a83 12
     <note>
      <para>
       You must use <application>make</application>,
       not <application>javac</application>, 
       as the driver uses some dynamic
       loading techniques for performance reasons, 
       and <application>javac</application> cannot cope.
       The <filename>Makefile</filename> will generate the jar archive.
      </para>
     </note>
    </para>
   </sect2>
d85 14
a98 2
   <sect2>
    <title>Installing the Driver</title>
d100 1
d102 3
a104 2
     To use the driver, the jar archive postgresql.jar needs to be included in
     the <envar>CLASSPATH</envar>.
d106 2
d109 2
a110 2
    <sect3>
     <title>Example</title>
d112 7
a118 5
     <para>
      I have an application that uses the <acronym>JDBC</acronym> driver to access a large database
      containing astronomical objects. I have the application and the jdbc driver
      installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6.
     </para>
d120 12
a131 5
     <para>
      To run the application, I would use:

      <programlisting>
export CLASSPATH = /usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
d133 9
a141 2
      </programlisting>
     </para>
d143 6
a148 6
     <para>
      Loading the driver is covered later on in this chapter.
     </para>
    </sect3>
   </sect2>
  </sect1>
d150 1
a150 1
  <sect1 id="jdbc-prepare">
d154 5
a158 16
    Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
    must be running with the -i flag.
   </para>

   <para>
    Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA
    directory. In a default installation, this file permits access only by Unix
    domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
    to add something like:

    <programlisting>
host         all         127.0.0.1     255.255.255.255   password
    </programlisting>

    Here access to all databases are possible from the local machine 
    with <acronym>JDBC</acronym>.
d162 5
a166 2
    The <acronym>JDBC</acronym> Driver supports trust, ident, 
    password and crypt authentication methods.
d168 2
a169 1
  </sect1>
d171 2
a172 2
  <sect1 id="jdbc-use">
   <title>Using the Driver</title>
d174 1
a174 11
   <para>
    This section is not intended as a complete guide to 
    <acronym>JDBC</acronym> programming, but
    should help to get you started. For more information refer to the standard
    <acronym>JDBC</acronym> <acronym>API</acronym> documentation.
    Also, take a look at the examples included with the source. The basic
    example is used here.
   </para>
  </sect1>

  <sect1 id="jdbc-import">
d178 2
a179 2
    Any source that uses <acronym>JDBC</acronym>
    needs to import the java.sql package, using:
d181 1
a181 1
    <programlisting>
d183 1
a183 1
    </programlisting>
d187 3
a189 2
      Do not import the postgresql package. If you do, your source will not
      compile, as javac will get confused.
d193 1
a193 1
  </sect1>
d195 1
a195 1
  <sect1 id="jdbc-load">
d199 3
a201 2
    Before you can connect to a database, you need to load the driver. There
    are two methods available, and it depends on your code to the best one to use.
d209 1
a209 1
    <programlisting>
d211 1
a211 1
    </programlisting>
a214 1
   </para>
d216 7
a222 4
   <para>
    Note: The <function>forName()</function> method
    can throw a <literal>ClassNotFoundException</literal>, so you will
    need to catch it if the driver is not available.
d226 5
a230 4
    This is the most common method to use, but restricts your code to use just
    <application>Postgres</application>. 
    If your code may access another database in the future, and you
    don't use our extensions, then the second method is advisable.
d234 9
a242 9
    The second method passes the driver as a parameter to the JVM as it starts,
    using the -D argument. Example:

    <programlisting>
% java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer
    </programlisting>

    In this example, the JVM will attempt to load the driver as part of it's
    initialisation. Once done, the ImageViewer is started.
d246 4
a249 3
    Now, this method is the better one to use because it allows your code to
    be used with other databases, without recompiling the code. The only thing
    that would also change is the URL, which is covered next.
d253 5
a257 5
    One last thing. When your code then tries to open a Connection, and you get
    a <literal>No driver available</literal> SQLException being thrown,
    this is probably
    caused by the driver not being in the classpath, or the value in the parameter
    not being correct.
d259 1
a259 1
  </sect1>
d261 1
a261 1
  <sect1 id="jdbc-connect">
d265 4
a268 4
    With <acronym>JDBC</acronym>, a database is represented by a URL 
    (Uniform Resource Locator).
    With <application>Postgres</application>, this takes one of the following
    forms:
d272 3
a274 3
      <para>
       jdbc:postgresql:<replaceable class="parameter">database</replaceable>
      </para>
d278 3
a280 3
      <para>
       jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
      </para>
d284 3
a286 3
      <para>
       jdbc:postgresql://<replaceable class="parameter">host</replaceable><replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
      </para>
d299 1
a299 1
	The hostname of the server. Defaults to "localhost".
d310 2
a311 2
	The port number the server is listening on. Defaults to the Postgres
	standard port number (5432).
d322 1
a322 1
	The database name.
d330 1
a330 1
    To connect, you need to get a Connection instance from 
d332 7
a338 1
    you would use the DriverManager.getConnection() method:
d340 9
a348 3
    <programlisting>
Connection db = DriverManager.getConnection(url,user,pwd);
    </programlisting>
d350 3
a352 1
  </sect1>
d358 7
a364 4
    Any time you want to issue SQL statements to the database, you require a
    Statement instance. Once you have a Statement, you can use the executeQuery()
    method to issue a query. This will return a ResultSet instance, which contains
    the entire result.
d367 19
d387 1
a387 1
    <title>Using the Statement Interface</title>
d390 2
a391 1
     The following must be considered when using the Statement interface:
d396 6
a401 3
	You can use a Statement instance as many times as you want. You could
	create one as soon as you open the connection, and use it for the connections
	lifetime. You have to remember that only one ResultSet can exist per Statement.
d407 3
a409 2
	If you need to perform a query while processing a ResultSet, you can
	simply create and use another Statement.
d412 1
d415 4
a418 4
	If you are using Threads, and several are using the database, you must
	use a separate Statement for each thread. Refer to the sections covering
	Threads and Servlets later in this document if you are thinking of using them,
	as it covers some important points.
d426 1
a426 1
    <title>Using the ResultSet Interface</title>
d429 2
a430 1
     The following must be considered when using the ResultSet interface:
d435 4
a438 2
	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.
d444 5
a448 4
	Under the <acronym>JDBC</acronym> spec, you should access a
	field only once. It's safest to stick to this rule, although
	at the current time, the <application>Postgres</application> driver
	will allow you to access a field as many times as you want.
d454 2
a455 2
	You must close a ResultSet by calling
	<function>close()</function> once you have finished with it.
d461 5
a465 2
	Once you request another query with the Statement used to create a
	ResultSet, the currently open instance is closed.
a469 15

    <para>
     An example is as follows:

     <programlisting>
Statement st = db.createStatement();
ResultSet rs = st.executeQuery("select * from mytable");
while(rs.next()) {
    System.out.print("Column 1 returned ");
    System.out.println(rs.getString(1));
}
rs.close();
st.close();
     </programlisting>
    </para>
d477 3
a479 2
    To perform an update (or any other SQL statement that does not return a
    result), you simply use the <function>executeUpdate()</function> method:
d481 3
a483 3
    <programlisting>
st.executeUpdate("create table basic (a int2, b int2)");
    </programlisting>
d487 2
a488 2
  <sect1 id="jdbc-disconnect">
   <title>Closing the Connection</title>
d490 7
a496 11
   <para>
    To close the database connection, simply call the close() method to the Connection:

    <programlisting>
db.close();
    </programlisting>
   </para>
  </sect1>

  <sect1 id="jdbc-lo">
   <title>Using Large Objects</title>
d498 1
d500 6
a505 17
    In <application>Postgres</application>, 
    large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
    the database that cannot be stored in a normal SQL table. They are stored as a
    Table/Index pair, and are referred to from your own tables by an OID value.
   </para>

   <para>
    <important>
     <para>
      For <productname>Postgres</productname>, you must access large
      objects within an SQL transaction. Although this has always been 
      true in principle, it was not strictly enforced until the
      release of version 6.5. You would open a transaction by using the
      <function>setAutoCommit()</function> method with an input
      parameter of <literal>false</literal>:

      <programlisting>
d509 2
a510 4
... now use Large Objects
      </programlisting>
     </para>
    </important>
d512 1
d515 1
a515 1
    Now, there are two methods of using Large Objects. The first is the
d517 5
a521 5
    other, uses our own extension
    to the api, which presents the libpq large object
    <acronym>API</acronym> to Java, providing even
    better access to large objects than the standard. Internally, the driver uses
    the extension to provide large object support.
d525 9
a533 4
    In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
    method in ResultSet, and setBinaryStream() method in PreparedStatement. These
    methods make the large object appear as a Java stream, allowing you to use the
    java.io package, and others, to manipulate the object.
d536 3
d540 5
a544 7
    For example, suppose
    you have a table containing the file name of an image, and a large object
    containing that image:

    <programlisting>
create table images (imgname name,imgoid oid);
    </programlisting>
d549 1
a549 2

    <programlisting>
d552 3
a554 3
PreparedStatement ps = conn.prepareStatement("insert into images values (?,?)");
ps.setString(1,file.getName());
ps.setBinaryStream(2,fis,file.length());
d558 14
a571 1
    </programlisting>
d575 3
a577 4
    Now in this example, setBinaryStream transfers a set number of bytes from a
    stream into a large object, and stores the OID into the field holding a
    reference to it.
   </para>
d579 3
a581 7
   <para>
    Retrieving an image is even easier (I'm using PreparedStatement here, but
    Statement can equally be used):

    <programlisting>
PreparedStatement ps = con.prepareStatement("select oid from images where name=?");
ps.setString(1,"myimage.gif");
d583 1
a583 1
if(rs!=null) {
d592 1
a592 1
    </programlisting>
d596 7
a602 4
    Now here you can see where the Large Object is retrieved as an InputStream.
    You'll also notice that we close the stream before processing the next row in
    the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any
    InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
d604 3
a606 1
  </sect1>
d608 2
a609 2
  <sect1 id="jdbc-ext">
   <title><application>Postgres</application> Extensions to the
d612 13
a624 6
   <para>
    <application>Postgres</application> is an extensible database system. 
    You can add your own functions
    to the backend, which can then be called from queries, or even add your own
    data types.
   </para>
d627 4
a630 13
    Now, as these are facilities unique to us, we support them from Java, with
    a set of extension <acronym>API</acronym>'s. Some features within 
    the core of the standard driver
    actually use these extensions to implement Large Objects, etc.

<!--
************************************************************
Nothing marked up from here on. It looks like it will be tricky:
what do we want to do with the class inheritance diagrams?
- thomas 1998-10-23
************************************************************
-->

d632 6
a637 1
Accessing the extensions
d639 2
a640 3
To access some of the extensions, you need to use some extra methods 
in the postgresql.Connection class. In this case, you would need to 
case the return value of Driver.getConnection().
d642 2
a643 1
For example:
a644 7
    Connection db = Driver.getConnection(url,user,pass);

    // later on
    Fastpath fp = ((postgresql.Connection)db).getFastpathAPI();

Class postgresql.Connection
                                
d647 2
a648 1
   +----postgresql.Connection
d650 6
a655 1
   public class Connection extends Object implements Connection
d657 2
a658 2
These are the extra methods used to gain access to our extensions. I 
have not listed the methods defined by java.sql.Connection.
d660 10
a669 1
 public Fastpath getFastpathAPI() throws SQLException
d671 9
a679 1
          This returns the Fastpath <acronym>API</acronym> for the current connection.
d681 15
a695 2
          NOTE: This is not part of <acronym>JDBC</acronym>, but allows access to 
functions on the postgresql backend itself.
d697 8
a704 1
          It is primarily used by the LargeObject <acronym>API</acronym>
d706 10
a715 1
          The best way to use this is as follows:
d717 14
a730 3
 import postgresql.fastpath.*;
 ...
 Fastpath fp = ((postgresql.Connection)myconn).getFastpathAPI();
d732 13
a744 48
          where myconn is an open Connection to postgresql.

        Returns:
                Fastpath object allowing access to functions on the 
postgresql backend.

        Throws: SQLException
                by Fastpath when initialising for first time
          
 public LargeObjectManager getLargeObjectAPI() throws SQLException

          This returns the LargeObject <acronym>API</acronym> for the current connection.

          NOTE: This is not part of <acronym>JDBC</acronym>, but allows access to 
functions on the postgresql backend itself.
   
          The best way to use this is as follows:

 import postgresql.largeobject.*;
 ...
 LargeObjectManager lo = 
((postgresql.Connection)myconn).getLargeObjectAPI();

          where myconn is an open Connection to postgresql.

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

        Throws: SQLException
                by LargeObject when initialising for first time

 public void addDataType(String type,
                         String name)

          This allows client code to add a handler for one of 
postgresql's more unique data types. Normally, a data type not known 
by the driver is returned by ResultSet.getObject() as a PGobject 
instance.

This method allows you to write a class that extends PGobject, and 
tell the driver the type name, and class name to use.

The down side to this, is that you must call this method each time a 
connection is made.

          NOTE: This is not part of <acronym>JDBC</acronym>, but an extension.

          The best way to use this is as follows:
d746 3
d750 1
a750 2
 ((postgresql.Connection)myconn).addDataType("mytype","my.class.name"-
);
d752 9
a761 8
          where myconn is an open Connection to postgresql.

          The handling class must extend postgresql.util.PGobject

        See Also:
                PGobject

Fastpath
d763 2
a764 4
Fastpath is an <acronym>API</acronym> that exists within the libpq C interface, and 
allows a client machine to execute a function on the database backend. 
Most client code will not need to use this method, but it's provided 
because the Large Object <acronym>API</acronym> uses it.
d766 2
a767 16
To use, you need to import the postgresql.fastpath package, using the 
line:
     import postgresql.fastpath.*;

Then, in your code, you need to get a FastPath object:
     Fastpath fp = ((postgresql.Connection)conn).getFastpathAPI();

This will return an instance associated with the database connection 
that you can use to issue commands. The casing of Connection to 
postgresql.Connection is required, as the getFastpathAPI() is one of 
our own methods, not <acronym>JDBC</acronym>'s.

Once you have a Fastpath instance, you can use the fastpath() methods 
to execute a backend function.

Class postgresql.fastpath.Fastpath
d771 2
a772 1
   +----postgresql.fastpath.Fastpath
d774 7
a780 1
   public class Fastpath
d782 22
a803 1
   extends Object
d805 6
a810 1
   This class implements the Fastpath api.
d812 2
a813 2
   This is a means of executing functions imbeded in the postgresql 
backend from within a java application.
d815 10
a824 1
   It is based around the file src/interfaces/libpq/fe-exec.c
d826 3
a828 12
   See Also:
          FastpathFastpathArg, LargeObject

Methods

 public Object fastpath(int fnid,
                        boolean resulttype,
                        FastpathArg args[]) throws SQLException

          Send a function call to the PostgreSQL backend
          
        Parameters:
d834 2
d837 8
a844 7
        Returns:
                null if no data, Integer if an integer result, or 
byte[]
                otherwise
         
        Throws: SQLException
                if a database-access error occurs.
d846 9
a854 12
 public Object fastpath(String name,
                        boolean resulttype,
                        FastpathArg args[]) throws SQLException

          Send a function call to the PostgreSQL backend by name. 

Note:
          the mapping for the procedure name to function id needs to 
exist, usually to an earlier call to addfunction(). This is the 
prefered method to call, as function id's can/may change between 
versions of the backend. For an example of how this works, refer to 
postgresql.LargeObject
d856 13
a868 1
        Parameters:
d874 2
d877 13
a889 4
        Returns:
                null if no data, Integer if an integer result, or 
byte[]
                otherwise
d891 8
a898 12
        Throws: SQLException
                if name is unknown or if a database-access error 
occurs.

        See Also:
                LargeObject
          
 public int getInteger(String name,
                       FastpathArg args[]) throws SQLException

          This convenience method assumes that the return value is an 
Integer
d900 3
a902 1
        Parameters:
d905 2
d908 12
a919 2
        Returns:
                integer result
d921 9
a929 2
        Throws: SQLException
                if a database-access error occurs or no result
d931 3
a933 7
 public byte[] getData(String name,
                       FastpathArg args[]) throws SQLException

          This convenience method assumes that the return value is 
binary data

        Parameters:
d936 2
d939 12
a950 2
        Returns:
                byte[] array containing result
d952 13
a964 2
        Throws: SQLException
                if a database-access error occurs or no result
d966 9
a974 2
 public void addFunction(String name,
                         int fnid)
d976 44
a1019 1
          This adds a function to our lookup table.
d1021 13
a1033 47
          User code should use the addFunctions method, which is based 
upon a query, rather than hard coding the oid. The oid for a function 
is not guaranteed to remain static, even on different servers of the 
same version.

        Parameters:
                name - Function name
                fnid - Function id

 public void addFunctions(ResultSet rs) throws SQLException
                       
          This takes a ResultSet containing two columns. Column 1 
contains the function name, Column 2 the oid.

          It reads the entire ResultSet, loading the values into the 
function table.

          REMEMBER to close() the resultset after calling this!!

          Implementation note about function name lookups:
          
          PostgreSQL stores the function id's and their corresponding 
names in the pg_proc table. To speed things up locally, instead of 
querying each function from that table when required, a Hashtable is 
used. Also, only the function's required are entered into this table, 
keeping connection times as fast as possible.

          The postgresql.LargeObject class performs a query upon it's 
start-up, and passes the returned ResultSet to the addFunctions() 
method here.
       
          Once this has been done, the LargeObject api refers to the 
functions by name.
          
          Dont think that manually converting them to the oid's will 
work. Ok, they will for now, but they can change during development 
(there was some discussion about this for V7.0), so this is 
implemented to prevent any unwarranted headaches in the future.

        Parameters:
                rs - ResultSet

        Throws: SQLException
                if a database-access error occurs.
          
        See Also:
                LargeObjectManager
a1034 6
 public int getID(String name) throws SQLException
          
          This returns the function id associated by its name
          
          If addFunction() or addFunctions() have not been called for 
this name, then an SQLException is thrown.
d1036 2
a1037 8
        Parameters:
                name - Function name to lookup

        Returns:
                Function ID for fastpath call

        Throws: SQLException
                is function is unknown.
d1039 2
a1040 1
Class postgresql.fastpath.FastpathArg
d1044 2
a1045 1
   +----postgresql.fastpath.FastpathArg
d1047 5
a1051 4
   public class FastpathArg extends Object
        
   Each fastpath call requires an array of arguments, the number and 
type dependent on the function being called.
d1053 4
a1056 1
   This class implements methods needed to provide this capability.
d1058 6
a1063 2
   For an example on how to use this, refer to the 
postgresql.largeobject package
d1065 2
a1066 2
   See Also:
          Fastpath, LargeObjectManager, LargeObject
d1068 8
a1075 1
Constructors
d1077 7
a1083 13
 public FastpathArg(int value)
 
          Constructs an argument that consists of an integer value

        Parameters:
                value - int value to set

 public FastpathArg(byte bytes[])
          
          Constructs an argument that consists of an array of bytes

        Parameters:
                bytes - array to store
d1085 7
a1091 3
 public FastpathArg(byte buf[],
                    int off,
                    int len)
d1093 7
a1099 2
           Constructs an argument that consists of part of a byte 
array
d1101 9
a1109 4
        Parameters:
                buf - source array
                off - offset within array
                len - length of data to include
d1111 28
a1138 6
 public FastpathArg(String s)
          
          Constructs an argument that consists of a String.
      
        Parameters:
                s - String to store
d1140 12
a1151 1
Geometric Data Types
a1152 2
PostgreSQL has a set of datatypes that can store geometric features 
into a table. These range from single points, lines, and polygons.
d1154 2
a1155 1
We support these types in Java with the postgresql.geometric package.
d1157 8
a1164 3
It contains classes that extend the postgresql.util.PGobject class. 
Refer to that class for details on how to implement your own data type 
handlers.
d1166 2
a1167 1
Class postgresql.geometric.PGbox
d1171 1
a1171 1
   +----postgresql.util.PGobject
d1173 1
a1173 1
           +----postgresql.geometric.PGbox
d1178 1
a1178 1
   This represents the box datatype within postgresql.
d1223 1
a1223 1
overidden, but still called by subclasses.
d1247 1
a1247 1
          This must be overidden to allow the object to be cloned
d1255 1
a1255 1
                the PGbox in the syntax expected by postgresql
d1260 2
a1261 1
Class postgresql.geometric.PGcircle
d1265 1
a1265 1
   +----postgresql.util.PGobject
d1267 1
a1267 1
           +----postgresql.geometric.PGcircle
d1272 1
a1272 1
   This represents postgresql's circle datatype, consisting of a point 
d1279 1
a1279 1
          This is the centre point
d1292 2
a1293 2
               x - coordinate of centre
                y - coordinate of centre
d1300 1
a1300 1
                c - PGpoint describing the circle's centre
d1341 1
a1341 1
          This must be overidden to allow the object to be cloned
d1349 1
a1349 1
                the PGcircle in the syntax expected by postgresql
d1354 2
a1355 1
Class postgresql.geometric.PGline
d1359 1
a1359 1
   +----postgresql.util.PGobject
d1361 1
a1361 1
           +----postgresql.geometric.PGline
d1406 1
a1406 1
          reuired by the driver
d1435 1
a1435 1
          This must be overidden to allow the object to be cloned
d1443 1
a1443 1
                the PGline in the syntax expected by postgresql
d1448 2
a1449 1
Class postgresql.geometric.PGlseg
d1453 1
a1453 1
   +----postgresql.util.PGobject
d1455 1
a1455 1
           +----postgresql.geometric.PGlseg
d1499 1
a1499 1
          reuired by the driver
d1528 1
a1528 1
          This must be overidden to allow the object to be cloned
d1536 1
a1536 1
                the PGlseg in the syntax expected by postgresql
d1541 2
a1542 1
Class postgresql.geometric.PGpath
d1546 1
a1546 1
   +----postgresql.util.PGobject
d1548 1
a1548 1
           +----postgresql.geometric.PGpath
d1613 1
a1613 1
          This must be overidden to allow the object to be cloned
d1621 1
a1621 1
postgresql
d1642 2
a1643 1
Class postgresql.geometric.PGpoint
d1647 1
a1647 1
   +----postgresql.util.PGobject
d1649 1
a1649 1
           +----postgresql.geometric.PGpoint
d1657 1
a1657 1
   It maps to the point datatype in postgresql.
d1681 1
a1681 1
point is imbeded within their definition.
d1717 1
a1717 1
          This must be overidden to allow the object to be cloned
d1725 1
a1725 1
                the PGpoint in the syntax expected by postgresql
d1790 2
a1791 1
Class postgresql.geometric.PGpolygon
d1795 1
a1795 1
   +----postgresql.util.PGobject
d1797 1
a1797 1
           +----postgresql.geometric.PGpolygon
d1802 1
a1802 1
   This implements the polygon datatype within PostgreSQL.
d1857 1
a1857 1
          This must be overidden to allow the object to be cloned
d1865 1
a1865 1
                the PGpolygon in the syntax expected by postgresql
d1869 2
a1871 1
Large Objects
d1873 9
a1881 9
Large objects are supported in the standard <acronym>JDBC</acronym> specification. 
However, that interface is limited, and the api provided by PostgreSQL 
allows for random access to the objects contents, as if it was a local 
file.

The postgresql.largeobject package profides to Java the libpq C 
interface's large object <acronym>API</acronym>. It consists of two classes, 
LargeObjectManager, which deals with creating, opening and deleting 
large obejects, and LargeObject which deals with an individual object.
d1883 7
a1889 1
Class postgresql.largeobject.LargeObject
d1891 2
a1892 3
java.lang.Object
   |
   +----postgresql.largeobject.LargeObject
d1894 1
d1897 4
a1900 1
This class implements the large object interface to postgresql.
d1902 4
a1905 8
   It provides the basic methods required to run the interface, plus a 
pair of methods that provide InputStream and OutputStream classes for 
this object.

   Normally, client code would use the getAsciiStream, 
getBinaryStream, or getUnicodeStream methods in ResultSet, or 
setAsciiStream, setBinaryStream, or setUnicodeStream methods in 
PreparedStatement to access Large Objects.
d1907 5
a1911 2
   However, sometimes lower level access to Large Objects are 
required, that are not supported by the <acronym>JDBC</acronym> specification.
d1913 6
a1918 2
   Refer to postgresql.largeobject.LargeObjectManager on how to gain 
access to a Large Object, or how to create one.
d1920 5
a1924 2
   See Also:
          LargeObjectManager
d1926 4
a1929 1
Variables
d1931 31
a1961 1
 public static final int SEEK_SET
d1963 2
a1964 1
          Indicates a seek from the begining of a file
d1966 9
a1974 1
 public static final int SEEK_CUR
d1976 9
a1984 1
          Indicates a seek from the current position
d1986 8
a1993 1
 public static final int SEEK_END
d1995 9
a2003 1
          Indicates a seek from the end of a file
d2005 28
a2032 1
Methods
d2034 8
a2041 1
 public int getOID()
d2043 3
a2045 26
        Returns:
                the OID of this LargeObject

 public void close() throws SQLException

          This method closes the object. You must not call methods in 
this object after this is called.

    Throws: SQLException
                if a database-access error occurs.

 public byte[] read(int len) throws SQLException

          Reads some data from the object, and return as a byte[] 
array

        Parameters:
                len - number of bytes to read

        Returns:
                byte[] array containing data read

        Throws: SQLException
                if a database-access error occurs.

 public void read(byte buf[],
d2048 4
d2053 28
a2080 34
          Reads some data from the object into an existing array

        Parameters:
                buf - destination array
                off - offset within array
                len - number of bytes to read

        Throws: SQLException
                if a database-access error occurs.

 public void write(byte buf[]) throws SQLException

          Writes an array to the object


        Parameters:
                buf - array to write

        Throws: SQLException
                if a database-access error occurs.

 public void write(byte buf[],
                   int off,
                   int len) throws SQLException

          Writes some data from an array to the object

        Parameters:
                buf - destination array
                off - offset within array
                len - number of bytes to write

        Throws: SQLException
                if a database-access error occurs.
d2082 1
d2151 4
a2155 5
Class postgresql.largeobject.LargeObjectManager
                                
java.lang.Object
   |
   +----postgresql.largeobject.LargeObjectManager
d2157 4
d2163 4
a2166 21
This class implements the large object interface to postgresql.
        
   It provides methods that allow client code to create, open and 
delete large objects from the database. When opening an object, an 
instance of postgresql.largeobject.LargeObject is returned, and its 
methods then allow access to the object.

This class can only be created by postgresql.Connection

To get access to this class, use the following segment of code:

 import postgresql.largeobject.*;
 Connection  conn;
 LargeObjectManager lobj;
 ... code that opens a connection ...
 lobj = ((postgresql.Connection)myconn).getLargeObjectAPI();

Normally, client code would use the getAsciiStream, getBinaryStream, 
or getUnicodeStream methods in ResultSet, or setAsciiStream, 
setBinaryStream, or setUnicodeStream methods in PreparedStatement to 
access Large Objects.
d2168 8
a2175 2
   However, sometimes lower level access to Large Objects are 
required, that are not supported by the <acronym>JDBC</acronym> specification.
d2177 11
a2187 2
   Refer to postgresql.largeobject.LargeObject on how to manipulate 
the contents of a Large Object.
d2189 8
a2196 2
   See Also:
          LargeObject
d2198 4
a2201 1
Variables
d2203 2
a2204 1
 public static final int WRITE
d2206 23
a2228 1
          This mode indicates we want to write to an object
d2230 2
a2231 1
 public static final int READ
d2233 11
a2243 1
          This mode indicates we want to read an object
d2245 10
a2254 1
 public static final int READWRITE
d2256 9
a2264 2
          This mode is the default. It indicates we want read and 
write access to a large object
d2266 9
a2274 1
Methods
d2276 8
a2283 5
 public LargeObject open(int oid) throws SQLException
          
          This opens an existing large object, based on its OID. This
          method assumes that READ and WRITE access is required (the 
default).
d2285 14
a2298 2
        Parameters:
                oid - of large object
a2299 2
        Returns:
                LargeObject instance providing access to the object
d2301 2
a2302 2
        Throws: SQLException
                on error
d2304 6
a2309 72
 public LargeObject open(int oid,
                         int mode) throws SQLException
          
          This opens an existing large object, based on its OID
  
        Parameters:
                oid - of large object
                mode - mode of open

        Returns:
                LargeObject instance providing access to the object

        Throws: SQLException
                on error

 public int create() throws SQLException

          This creates a large object, returning its OID.

          It defaults to READWRITE for the new object's attributes.

        Returns:
                oid of new object

        Throws: SQLException
                on error

 public int create(int mode) throws SQLException

          This creates a large object, returning its OID

        Parameters:
                mode - a bitmask describing different attributes of 
the
                new object

        Returns:
                oid of new object

        Throws: SQLException
                on error

 public void delete(int oid) throws SQLException
          
          This deletes a large object.
          
        Parameters:
                oid - describing object to delete

        Throws: SQLException
                on error

 public void unlink(int oid) throws SQLException

          This deletes a large object.

          It is identical to the delete method, and is supplied as the 
C <acronym>API</acronym> uses unlink.

        Parameters:
                oid - describing object to delete

        Throws: SQLException
                on error

Object Serialisation
PostgreSQL is not a normal SQL Database. It is far more extensible 
than most other databases, and does support Object Oriented features 
that are unique to it. 

One of the consequences of this, is that you can have one table refer 
to a row in another table. For example:
d2311 4
d2334 4
d2339 3
a2341 2
Ok, the above example shows that we can use a table name as a field, 
and the row's oid value is stored in that field.
d2343 6
a2348 1
What does this have to do with Java?
d2350 5
a2354 4
In Java, you can store an object to a Stream as long as it's class 
implements the java.io.Serializable interface. This process, known as 
Object Serialization, can be used to store complex objects into the 
database.
d2356 11
a2366 2
Now, under <acronym>JDBC</acronym>, you would have to use a LargeObject to store them. 
However, you cannot perform queries on those objects.
d2368 4
a2371 9
What the postgresql.util.Serialize class does, is provide a means of 
storing an object as a table, and to retrieve that object from a 
table. In most cases, you would not need to access this class direct, 
but you would use the PreparedStatement.setObject() and 
ResultSet.getObject() methods. Those methods will check the objects 
class name against the table's in the database. If a match is found, 
it assumes that the object is a Serialized object, and retrieves it 
from that table. As it does so, if the object contains other 
serialized objects, then it recurses down the tree.
d2373 6
a2378 2
Sound's complicated? In fact, it's simpler than what I wrote - it's 
just difficult to explain.
d2380 9
a2388 4
The only time you would access this class, is to use the create() 
methods. These are not used by the driver, but issue one or more 
"create table" statements to the database, based on a Java Object or 
Class that you want to serialize.
d2390 5
a2394 1
Oh, one last thing. If your object contains a line like:
d2396 5
a2400 1
     public int oid;
d2402 2
a2403 12
then, when the object is retrieved from the table, it is set to the 
oid within the table. Then, if the object is modified, and re-
serialized, the existing entry is updated.

If the oid variable is not present, then when the object is 
serialized, it is always inserted into the table, and any existing 
entry in the table is preserved.

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

Class postgresql.util.Serialize
d2407 1
a2407 1
   +----postgresql.util.Serialize
d2424 1
a2424 1
ordeserialize a Java object from a PostgreSQL table.
d2535 1
a2535 1
          This converts a Java Class name to a postgresql table, by
d2555 1
a2555 1
          This converts a postgresql table to a Java Class name, by
d2566 1
a2566 1

d2569 1
a2569 1
The postgresql.util package contains classes used by the internals of 
d2572 1
a2572 1
Class postgresql.util.PGmoney
d2576 1
a2576 1
   +----postgresql.util.PGobject
d2578 1
a2578 1
           +----postgresql.util.PGmoney
d2637 1
a2637 1
          This must be overidden to allow the object to be cloned
d2645 1
a2645 1
                the PGpoint in the syntax expected by postgresql
d2650 2
a2651 1
Class postgresql.util.PGobject
d2655 1
a2655 1
   +----postgresql.util.PGobject
d2663 1
a2663 1
    A call to postgresql.Connection permits a class that extends this 
d2665 1
a2665 1
postgresql.geometric package operates.
d2667 2
a2668 2
not recognised on having it's own handler. Because of this, any 
postgresql data type is supported.
d2674 1
a2674 1
          This is called by postgresql.Connection.getObject() to 
d2691 1
a2691 1
overidden.
d2710 2
a2711 2
          This must be overidden, to return the value of the object, 
in the form required by postgresql.
d2718 1
a2718 1
          This must be overidden to allow comparisons of objects
d2731 1
a2731 1
          This must be overidden to allow the object to be cloned
d2738 1
a2738 1
          This is defined here, so user code need not overide it.
d2742 1
a2742 1
postgresql
d2747 2
a2748 1
Class postgresql.util.PGtokenizer
d2752 1
a2752 1
   +----postgresql.util.PGtokenizer
d2756 1
a2756 1
   This class is used to tokenize the text output of postgres.
d2763 1
a2763 1
any output from custom data types output from postgresql.
d2773 1
a2773 1
          Create a tokeniser.
d2808 1
a2808 1
geometric datatypes use this to process nested tokens (usually 
d2892 2
a2893 1
Class postgresql.util.Serialize
d2895 1
a2895 1
This was documented earlier under Object Serialisation.
d2897 1
a2897 1
Class postgresql.util.UnixCrypt
d2901 1
a2901 1
   +----postgresql.util.UnixCrypt
d2920 1
a2920 1
          Encrypt a password given the cleartext password and a 
d2928 1
a2928 1
                value should be randomised.
d2938 1
a2938 1
          Encrypt a password given the cleartext password. This method 
d2959 1
a2959 1
(or otherwise aquired).
d2963 71
d3035 8
a3042 1
Using the driver in a multi Threaded or Servlet environment
d3044 7
a3050 70
A problem with many <acronym>JDBC</acronym> drivers, is that only one thread can use a 
Connection at any one time - otherwise a thread could send a query 
while another one is receiving results, and this would be a bad thing 
for the database engine.

PostgreSQL 6.4, brings thread safety to the entire driver. Standard 
<acronym>JDBC</acronym> was thread safe in 6.3.x, but the Fastpath
     <acronym>API</acronym> wasn't.

So, if your application uses multiple threads (which most decent ones 
would), then you don't have to worry about complex schemes to ensure 
only one uses the database at any time.

If a thread attempts to use the connection while another is using it, 
it will wait until the other thread has finished it's current 
operation.

If it's a standard SQL statement, then the operation is sending the 
statement, and retrieving any ResultSet (in full).

If it's a Fastpath call (ie: reading a block from a LargeObject), then 
it's the time to send, and retrieve that block.

This is fine for applications & applets, but can cause a performance 
problem with servlets.

With servlets, you can have a heavy load on the connection. If you 
have several threads performing queries, then each one will pause, 
which may not be what you are after.

To solve this, you would be advised to create a pool of Connections.

When ever a thread needs to use the database, it asks a manager class 
for a Connection. It hands a free connection to the thread, and marks 
it as busy. If a free connection is not available, it opens one.

Once the thread has finished with it, it returns it to the manager, 
who can then either close it, or add it to the pool. The manager would 
also check that the connection is still alive, and remove it from the 
pool if it's dead.

So, with servlets, it's up to you to use either a single connection, 
or a pool. The plus side for a pool is that threads will not be hit by 
the bottle neck caused by a single network connection. The down side, 
is that it increases the load on the server, as a backend is created 
for each Connection.

It's up to you, and your applications requirements.
</programlisting>
</para>
</sect1>

<sect1 id="jdbc-reading">
<title>Further Reading</title>

<para>
If you have not yet read it, I'd advise you read the <acronym>JDBC</acronym>
 <acronym>API</acronym> 
Documentation (supplied with Sun's <acronym>JDK</acronym>),
 and the <acronym>JDBC</acronym> Specification. 
Both are available on 
<ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>.
</para>

<para>
<ulink url="http://www.retep.org.uk">My own web site</ulink>
 contains updated information not included in this 
document, and also includes precompiled drivers for versions 6.4 and earlier.
</para>
</sect1>
@


1.17
log
@Replace incorrect uses of 'which' with 'that'.  (so-called "wicked which")
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.16 2000/12/21 22:55:27 petere Exp $
d12 1
a12 1
     Written by <ulink url="mailto:peter@@retep.org.uk">Peter T. Mount</ulink>, the
@


1.16
log
@Get rid of the little "v"s in front of version numbers, substituting the
full word "version" where appropriate.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.15 2000/10/27 22:28:23 momjian Exp $
d1302 1
a1302 1
   This implements a path (a multiple segmented line, which may be 
@


1.15
log
@Fix java driver example.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.14 2000/10/16 02:20:58 momjian Exp $
d441 1
a441 1
      release of v6.5. You would open a transaction by using the
d2645 1
a2645 1
document, and also includes precompiled drivers for v6.4, and earlier.
@


1.14
log
@Change jdbc docs from postgresql.Driver to org.postgresql.Driver.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.13 2000/09/29 20:21:34 petere Exp $
d200 1
a200 1
% java -Djdbc.drivers=postgresql.Driver example.ImageViewer
@


1.13
log
@Add `id' attributes to all `chapter' and `sect1' tags, to generate useful
names for the HTML files (e.g., not x4856.htm).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.12 2000/08/29 20:02:07 momjian Exp $
d175 1
a175 1
Class.forName("postgresql.Driver");
@


1.12
log
@Startup is actually start-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.11 2000/08/23 05:59:02 thomas Exp $
d33 1
a33 1
  <sect1>
d100 1
a100 1
  <sect1>
d128 1
a128 1
  <sect1>
d141 1
a141 1
  <sect1>
d161 1
a161 1
  <sect1>
d222 1
a222 1
  <sect1>
d301 1
a301 1
  <sect1>
d400 1
a400 1
  <sect1>
d413 1
a413 1
  <sect1>
d425 1
a425 1
  <sect1>
d531 1
a531 1
  <sect1>
d2630 1
a2630 1
<sect1>
@


1.11
log
@Fix several <ulink> tags which refer to e-mail addresses
 but were missing the "mailto:" prefix.
Fix typo.
Thanks to Neil Conway <nconway@@klamath.dyndns.org> for the heads-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/jdbc.sgml,v 1.10 2000/03/31 03:27:40 thomas Exp $
d819 1
a819 1
startup, and passes the returned ResultSet to the addFunctions() 
@


1.10
log
@Minor markup changes. Refer to (".../catalog") in the emacs hints.
@
text
@d2 1
a2 1
$Header$
d12 1
a12 1
     Written by <ulink url="peter@@retep.org.uk">Peter T. Mount</ulink>, the
@


1.9
log
@Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
 "Normalize" operation. Should be the last of those.
@
text
@d1 4
d2652 1
a2652 1
mode: sgml
d2662 1
a2662 1
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
@


1.8
log
@Remove rogue </book> tag left in from normalizing this chapter in emacs.
@
text
@d236 1
a236 1
       jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>>/<replaceable class="parameter">database</replaceable>
d242 1
a242 1
       jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>><replaceable class="parameter">">po</replaceable>e>/<replaceable class="parameter">database</replaceable>
@


1.7
log
@Add mention of transactions and large objects.
 Still need the code updated for LO examples.
@
text
@d2661 1
a2661 1
--></book>
@


1.6
log
@Replaced <literal></literal> with "" in ProgramListing sections
@
text
@d1 2
a2 2
<Chapter Id="jdbc">
<Title>JDBC Interface</Title>
d4 35
a38 33
<para>
<note>
<title>Author</title>
<para>
Written by <ulink url="peter@@retep.org.uk">Peter T. Mount</ulink>, the
author of the <acronym>JDBC</acronym> driver.
</para>
</note>
</para>

<para>
<acronym>JDBC</acronym> is a core <acronym>API</acronym> of Java 1.1 and later.
It provides a standard set of
interfaces to <acronym>SQL</acronym>-compliant databases.
</para>
<para>
<application>Postgres</application> provides 
a type 4 <acronym>JDBC</acronym> Driver. Type 4 indicates that the driver
is written in Pure Java, and communicates in the database's own network
protocol. Because of this, the driver is platform independent. Once compiled,
the driver can be used on any platform.
</para>

<sect1>
<title>Building the <acronym>JDBC</acronym> Interface</title>

<sect2>
<title>Compiling the Driver</title>

<para>
The driver's source is located in the <filename>src/interfaces/jdbc</filename>
 directory of the
source tree. To compile simply change directory to that directory, and type:
d40 1
a40 1
<programlisting>
d42 2
a43 2
</programlisting>
</para>
d45 34
a78 17
<para>
Upon completion, you will find the archive <filename>postgresql.jar</filename>
 in the current
directory. This is the <acronym>JDBC</acronym> driver.

<note>
<para>
You must use <application>make</application>,
not <application>javac</application>, 
as the driver uses some dynamic
loading techniques for performance reasons, 
and <application>javac</application> cannot cope.
The <filename>Makefile</filename> will generate the jar archive.
</para>
</note>
</para>
</sect2>
d80 2
a81 2
<sect2>
<title>Installing the Driver</title>
d83 2
a84 19
<para>
To use the driver, the jar archive postgresql.jar needs to be included in
the CLASSPATH.
</para>
<para>
Example:
</para>
<para>
I have an application that uses the <acronym>JDBC</acronym> driver to access a large database
containing astronomical objects. I have the application and the jdbc driver
installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6.
</para>

<para>
To run the application, I would use:
</para>
<para>
export CLASSPATH = \
        /usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
d86 2
a87 6
</para>
<para>
Loading the driver is covered later on in this chapter.
</para>
</sect2>
</sect1>
d89 20
a108 2
<sect1>
<title>Preparing the Database for <acronym>JDBC</acronym></title>
d110 1
a110 11
<para>
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
must be running with the -i flag.
</para>
<para>
Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA
directory. In a default installation, this file permits access only by UNIX
domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
to add something like:
</para>
<para>
d112 1
a112 5
</para>
<para>
Here access to all databases are possible from the local machine 
with <acronym>JDBC</acronym>.
</para>
d114 29
a142 5
<para>
The <acronym>JDBC</acronym> Driver supports trust, ident, 
password and crypt authentication methods.
</para>
</sect1>
d144 1
a144 23
<sect1>
<title>Using the Driver</title>

<para>
This section is not intended as a complete guide to 
<acronym>JDBC</acronym> programming, but
should help to get you started. For more information refer to the standard
<acronym>JDBC</acronym> <acronym>API</acronym> documentation.
</para>
<para>
Also, take a look at the examples included with the source. The basic
example is used here.
</para>
</sect1>

<sect1>
<title>Importing <acronym>JDBC</acronym></title>

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

<programlisting>
d146 1
a146 1
</programlisting>
d148 21
a168 8
<important>
<para>
Do not import the postgresql package. If you do, your source will not
compile, as javac will get confused.
</para>
</important>
</para>
</sect1>
d170 1
a170 13
<sect1>
<title>Loading the Driver</title>

<para>
Before you can connect to a database, you need to load the driver. There
are two methods available, and it depends on your code to the best one to use.
</para>

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

<programlisting>
d172 1
a172 18
</programlisting>

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

<para>
Note: The <function>forName()</function> method
 can throw a ClassNotFoundException, so you will
need to catch it if the driver is not available.
</para>

<para>
This is the most common method to use, but restricts your code to use just
<application>Postgres</application>. 
If your code may access another database in the future, and you
don't use our extensions, then the second method is advisable.
</para>
d174 20
a193 6
<para>
The second method passes the driver as a parameter to the JVM as it starts,
using the -D argument.
</para>
<para>
Example:
d195 1
a195 1
<programlisting>
d197 1
a197 2
</programlisting>
</para>
d199 91
a289 3
<para>
In this example, the JVM will attempt to load the driver as part of it's
initialisation. Once done, the ImageViewer is started.
d291 1
a291 92
</para>
<para>
Now, this method is the better one to use because it allows your code to
be used with other databases, without recompiling the code. The only thing
that would also change is the URL, which is covered next.
</para>

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

<sect1>
<title>Connecting to the Database</title>

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

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

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

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

</itemizedlist>

where:

<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
The hostname of the server. Defaults to "localhost".
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
The port number the server is listening on. Defaults to the Postgres
standard port number (5432).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<replaceable class="parameter">database</replaceable>
</term>
<listitem>
<para>
The database name.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>

<para>
To connect, you need to get a Connection instance from 
<acronym>JDBC</acronym>. To do this,
you would use the DriverManager.getConnection() method:
</para>
<para>
d293 85
a377 48
</para>
</sect1>

<sect1>
<title>Issuing a Query and Processing the Result</title>

<para>
Any time you want to issue SQL statements to the database, you require a
Statement instance. Once you have a Statement, you can use the executeQuery()
method to issue a query. This will return a ResultSet instance, which contains
the entire result.
</para>

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

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

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

<listitem>
<para>
If you need to perform a query while processing a ResultSet, you can
simply create and use another Statement.
</para>
</listitem>
<listitem>
<para>
If you are using Threads, and several are using the database, you must
use a separate Statement for each thread. Refer to the sections covering
Threads and Servlets later in this document if you are thinking of using them,
as it covers some important points.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2>
<title>Using the ResultSet Interface</title>
d379 2
a380 36
<para>
The following must be considered when using the ResultSet interface:

<itemizedlist>
<listitem>
<para>
Before reading any values, you must call <function>next()</function>. This returns true if
there is a result, but more importantly, it prepares the row for processing.
</para>
</listitem>

<listitem>
<para>
Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest
to stick to this rule, although at the current time, the <application>Postgres</application> driver
will allow you to access a field as many times as you want.
</para>
</listitem>

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

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

<para>
An example is as follows:
d382 1
a382 1
<programlisting>
d391 11
a401 11
</programlisting>
</para>
</sect2>
</sect1>

<sect1>
<title>Performing Updates</title>

<para>
To perform an update (or any other SQL statement that does not return a
result), you simply use the executeUpdate() method:
d403 1
a403 1
<programlisting>
d405 3
a407 3
</programlisting>
</para>
</sect1>
d409 2
a410 2
<sect1>
<title>Closing the Connection</title>
d412 2
a413 2
<para>
To close the database connection, simply call the close() method to the Connection:
d415 1
a415 1
<programlisting>
d417 55
a471 32
</programlisting>
</para>
</sect1>

<sect1>
<title>Using Large Objects</title>

<para>
In <application>Postgres</application>, 
large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
the database that cannot be stored in a normal SQL table. They are stored as a
Table/Index pair, and are refered to from your own tables, by an OID value.
</para>

<para>
Now, there are you methods of using Large Objects. The first is the
standard <acronym>JDBC</acronym> way, and is documented here. The other, uses our own extension
to the api, which presents the libpq large object <acronym>API</acronym> to Java, providing even
better access to large objects than the standard. Internally, the driver uses
the extension to provide large object support.
</para>
<para>
In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
methods make the large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the object.
</para>

<para>
For example, suppose
you have a table containing the file name of an image, and a large object
containing that image:
d473 1
a473 1
<programlisting>
d475 2
a476 2
</programlisting>
</para>
d478 2
a479 2
<para>
To insert an image, you would use:
d481 1
a481 1
<programlisting>
d490 2
a491 2
</programlisting>
</para>
d493 9
a501 9
<para>
Now in this example, setBinaryStream transfers a set number of bytes from a
stream into a large object, and stores the OID into the field holding a
reference to it.
</para>

<para>
Retrieving an image is even easier (I'm using PreparedStatement here, but
Statement can equally be used):
d503 1
a503 1
<programlisting>
d516 2
a517 2
</programlisting>
</para>
d519 24
a542 22
<para>
Now here you can see where the Large Object is retrieved as an InputStream.
You'll also notice that we close the stream before processing the next row in
the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any
InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
</para>
</sect1>

<sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>

<para>
<application>Postgres</application> is an extensible database system. 
You can add your own functions
to the backend, which can then be called from queries, or even add your own
data types.
</para>
<para>
Now, as these are facilities unique to us, we support them from Java, with
a set of extension <acronym>API</acronym>'s. Some features within 
the core of the standard driver
actually use these extensions to implement Large Objects, etc.
d2270 2
a2271 1
   This class is used to describe data types that are unknown by <acronym>JDBC</acronym> 
d2580 2
a2581 1
<acronym>JDBC</acronym> was thread safe in 6.3.x, but the Fastpath <acronym>API</acronym> wasn't.
d2645 17
@


1.5
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d166 1
a166 1
Class.forName(<literal>postgresql.Driver</literal>);
d383 1
a383 1
ResultSet rs = st.executeQuery(<literal>select * from mytable</literal>);
d385 1
a385 1
    System.out.print(<literal>Column 1 returned </literal>);
d403 1
a403 1
st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
d458 1
a458 1
File file = new File(<literal>myimage.gif</literal>);
d460 1
a460 1
PreparedStatement ps = conn.prepareStatement(<literal>insert into images values (?,?)</literal>);
d480 2
a481 2
PreparedStatement ps = con.prepareStatement(<literal>select oid from images where name=?</literal>);
ps.setString(1,<literal>myimage.gif</literal>);
@


1.4
log
@Minor editing and markup changes as a result of preparing the Postscript
 documentation for v6.4.
Bigger updates to the installation instructions (install and config).
@
text
@d10 1
d12 1
d18 1
d25 1
a29 2
<para>

d41 1
d56 1
d58 2
d67 1
d70 1
d75 1
d79 1
d84 1
d87 3
a89 1
<para>
d97 1
d103 1
d106 1
d110 1
d115 2
a116 2

<para>
d126 1
d130 2
a131 1
<para>
d148 1
d150 2
d159 1
d171 1
d177 1
d184 1
d189 1
d196 1
d202 1
d207 1
d215 2
d231 2
d237 2
d243 3
d254 1
a254 1

d258 3
d265 1
a265 1

d270 3
d277 1
a277 1

d281 3
d286 1
d292 1
d295 2
a296 1
<para>
d306 1
a306 1
<para>
d320 2
d327 2
d335 2
d338 2
a339 1

d352 2
d360 2
d366 2
d373 2
d376 1
d391 3
a393 1

d405 2
a406 1

d417 2
d428 1
d436 1
d442 1
d452 1
d467 1
d473 1
d493 1
d500 2
a501 1

d511 1
d2595 2
d2608 1
d2614 3
a2616 2

</chapter>@


1.3
log
@Add massive new docs from Peter Mount.
Includes markup for the introductory portions suitable for the User's Guide
 but just put the class reference material inside a huge <programlisting>
 block. Figure out what to do later...
@
text
@d53 1
a53 1
<para>
d79 1
a79 1
<title>Preparing the database for <acronym>JDBC</acronym></title>
d92 2
a93 1
Here access to all databases are possible from the local machine with <acronym>JDBC</acronym>.
d96 2
a97 1
The <acronym>JDBC</acronym> Driver supports trust, ident, password and crypt authentication methods.
d198 1
a198 1
jdbc:postgresql:<replaceable class="parameter>database</replaceable>
d202 1
a202 1
jdbc:postgresql://<replaceable class="parameter>host</replaceable>/<replaceable class="parameter>database</replaceable>
d206 1
a206 1
jdbc:postgresql://<replaceable class="parameter>host</replaceable>:<replaceable class="parameter>port</replaceable>/<replaceable class="parameter>database</replaceable>
d214 1
a214 1
<replaceable class="parameter>host</replaceable>
d222 1
a222 1
<replaceable class="parameter>port</replaceable>
d231 1
a231 1
<replaceable class="parameter>database</replaceable>
d248 1
a248 1
<title>Issuing a query and processing the result</title>
d257 5
a261 2
<sect1>
<title>Some notes about using the Statement interface:</title>
a263 1
<para>
d283 5
a287 2
<sect1>
<title>Some notes about using the ResultSet interface:</title>
a289 1
<para>
d292 1
a292 1
Before reading any values, you must call next(). This returns true if
d300 1
d303 2
a304 1
You must close() a ResultSet once you have finished with it.
d308 1
a308 1
ResultSet, the currently open instance is closed().
d311 4
d318 2
a319 8
<itemizedlist>
<para>
<listitem>
<para>
System.out.print(<literal>Column 1 returned </literal>);
<listitem>
<para>
System.out.println(rs.getString(1));
d323 1
a323 1
</itemizedlist>
d327 1
a327 1
<title>Performing updates</title>
a331 2
<para>
 st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
d333 4
a336 1
<para>
d339 1
a339 1
<title>Closing the connection</title>
d344 1
a344 1
<para>
d346 1
a346 1
<para>
d352 2
a353 1
In <application>Postgres</application>, large objects (also known as BLOBS) are used to hold data in
d368 1
d370 2
a371 3
Example:
<para>
You have a table containing the file name of an image, and a large object
d373 5
a377 2
<para>
    create table images (imgname name,imgoid oid);
d380 2
a381 5
<para>
<itemizedlist>
<para>
<listitem>
<para>
a382 2
<listitem>
<para>
d384 1
a384 6
<listitem>
<para>
PreparedStatement ps = conn.prepareStatement(<literal>insert into images
values (?,?)<literal>);
<listitem>
<para>
a385 2
<listitem>
<para>
a386 2
<listitem>
<para>
a387 2
<listitem>
<para>
a388 2
<listitem>
<para>
d390 1
a390 1
</itemizedlist>
d392 1
d396 1
d400 3
a402 9
<para>
<itemizedlist>
<para>
<listitem>
<para>
PreparedStatement ps = con.prepareStatement(<literal>select oid from
images where name=?<literal>);
<listitem>
<para>
a403 2
<listitem>
<para>
a404 2
<listitem>
<para>
a405 2
<listitem>
<para>
d407 3
a409 11
<listitem>
<para>
&#9;InputStream is = rs.getBinaryInputStream(1);
<listitem>
<para>
&#9;// use the stream in some way here
<listitem>
<para>
&#9;is.close();
<listitem>
<para>
a410 2
<listitem>
<para>
a411 2
<listitem>
<para>
a412 2
<listitem>
<para>
d414 1
a414 1
</itemizedlist>
d416 1
a421 1
<para>
d427 2
a428 1
<application>Postgres</application> is an extensible database system. You can add your own functions
d433 2
a434 1
a set of extension <acronym>API</acronym>'s. Some features within the core of the standard driver
a435 1
<para>
d438 7
a444 4
  -- Nothing marked up from here on. It looks like it will be tricky:
  -- what do we want to do with the class inheritance diagrams?
  -- - thomas 1998-10-23
  -->
d2524 1
a2524 1
<ulink url="http://www.javasoft.com>JavaSoft's web site</ulink>.
d2527 1
a2527 1
<ulink url="http://www.retep.org.uk>My own web site</ulink>
@


1.2
log
@Add id field to chapter and book tags to allow output file names
 to be meaningful.
@
text
@d4 7
a10 3
<Para>
There is a JDBC interface available for Postgres. It is documented elsewhere using
the accepted tool for Java-language code.
d12 2547
a2558 1
</Chapter>
@


1.1
log
@SGML source for new documentation.
@
text
@d1 1
a1 1
<Chapter>
@
