2000-03-31 05:27:42 +02:00
|
|
|
<!--
|
2001-09-12 17:55:00 +02:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.24 2001/09/12 15:55:00 momjian Exp $
|
2000-03-31 05:27:42 +02:00
|
|
|
-->
|
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
<chapter id="jdbc">
|
2001-02-24 13:40:27 +01:00
|
|
|
<title><acronym>JDBC</acronym> Interface</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<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>
|
2001-02-24 13:40:27 +01:00
|
|
|
<application>Postgres</application> provides a <firstterm>type
|
|
|
|
4</firstterm> <acronym>JDBC</acronym> Driver. Type 4 indicates
|
|
|
|
that the driver is written in Pure Java, and communicates in the
|
|
|
|
database system's own network protocol. Because of this, the driver
|
|
|
|
is platform independent; once compiled, the driver can be used on
|
|
|
|
any system.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
This chapter is not intended as a complete guide to
|
|
|
|
<acronym>JDBC</acronym> programming, but should help to get you
|
|
|
|
started. For more information refer to the standard
|
|
|
|
<acronym>JDBC</acronym> <acronym>API</acronym> documentation.
|
|
|
|
Also, take a look at the examples included with the source. The
|
|
|
|
basic example is used here.
|
|
|
|
</para>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect1 id="jdbc-setup">
|
|
|
|
<title>Setting up the <acronym>JDBC</acronym> Driver</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2 id="jdbc-build">
|
|
|
|
<title>Building the Driver</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Precompiled versions of the driver are regularly made available on
|
|
|
|
the <ulink
|
|
|
|
url="http://jdbc.postgresql.org"><productname>PostgreSQL</productname>
|
|
|
|
<acronym>JDBC</acronym> web site</ulink>. Here we describe how to
|
|
|
|
build the driver manually.
|
|
|
|
</para>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Starting with <productname>PostgreSQL</productname> version 7.1,
|
2001-03-11 12:07:01 +01:00
|
|
|
the <acronym>JDBC</acronym> driver is built using
|
|
|
|
<application>Ant</application>, a special tool for building
|
2001-02-24 13:40:27 +01:00
|
|
|
Java-based packages. You should download
|
2001-03-11 12:07:01 +01:00
|
|
|
<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>
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
2001-03-11 12:07:01 +01:00
|
|
|
The build the driver, add the <option>--with-java</option> option to your
|
|
|
|
<filename>configure</filename> command line, e.g.,
|
2001-02-24 13:40:27 +01:00
|
|
|
<screen>
|
2001-03-11 12:07:01 +01:00
|
|
|
<prompt>$</prompt> <userinput>./configure --prefix=<replaceable>xxx</replaceable> --with-java ...</userinput>
|
2001-02-24 13:40:27 +01:00
|
|
|
</screen>
|
2001-03-11 12:07:01 +01:00
|
|
|
This will build and install the driver along with the rest of the
|
|
|
|
<productname>PostgreSQL</productname> package when you issue the
|
|
|
|
<literal>gmake</literal> and <literal>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</literal> command there. Refer to the
|
|
|
|
<productname>PostgreSQL</productname> installation instructions
|
|
|
|
for more information about the configuration and build process.
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
1999-10-04 17:16:35 +02:00
|
|
|
<para>
|
2001-03-11 12:07:01 +01:00
|
|
|
Do not try to build 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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</note>
|
|
|
|
</sect2>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2 id="jdbc-classpath">
|
|
|
|
<title>Setting up the Class Path</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
To use the driver, the jar archive
|
|
|
|
<filename>postgresql.jar</filename> needs to be included in the
|
|
|
|
class path, either by putting it in the <envar>CLASSPATH</envar>
|
|
|
|
environment variable, or by using flags on the
|
2001-03-11 12:07:01 +01:00
|
|
|
<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>.
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<informalexample>
|
|
|
|
<para>
|
|
|
|
For instance, I have an application that uses the
|
|
|
|
<acronym>JDBC</acronym> driver to access a large database
|
|
|
|
containing astronomical objects. I have the application and the
|
|
|
|
<acronym>JDBC</acronym> driver installed in the <filename
|
|
|
|
class="directory">/usr/local/lib</filename> directory, and the
|
|
|
|
Java <acronym>JDK</acronym> installed in
|
|
|
|
<filename>/usr/local/jdk1.1.6</filename>. To run the
|
|
|
|
application, I would use:
|
|
|
|
<programlisting>
|
2001-03-11 12:07:01 +01:00
|
|
|
export CLASSPATH=/usr/local/lib/finder.jar<co id="co.jdbc-finder">:/usr/local/pgsql/share/java/postgresql.jar:.
|
1998-10-25 02:27:44 +02:00
|
|
|
java uk.org.retep.finder.Main
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
|
|
|
<calloutlist>
|
|
|
|
<callout arearefs="co.jdbc-finder">
|
|
|
|
<para>
|
|
|
|
<filename>finder.jar</filename> contains my application.
|
|
|
|
</para>
|
|
|
|
</callout>
|
|
|
|
</calloutlist>
|
|
|
|
</para>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Loading the driver from within the application is covered in
|
|
|
|
<xref linkend="jdbc-use">.
|
|
|
|
</para>
|
|
|
|
</informalexample>
|
|
|
|
</sect2>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2 id="jdbc-prepare">
|
1999-10-04 17:16:35 +02:00
|
|
|
<title>Preparing the Database for <acronym>JDBC</acronym></title>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Because Java can only use TCP/IP connections, the
|
|
|
|
<application>Postgres</application> server must be configured to
|
|
|
|
accept TCP/IP connections, for instance by supplying the
|
|
|
|
<option>-i</option> option flag when starting the
|
|
|
|
<command>postmaster</command>.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Also, the client authentication setup in the
|
|
|
|
<filename>pg_hba.conf</filename> file may need to be configured.
|
|
|
|
Refer to the <citetitle>Administrator's Guide</citetitle> for
|
|
|
|
details. The <acronym>JDBC</acronym> Driver supports trust,
|
2001-08-16 18:24:16 +02:00
|
|
|
ident, password, and md5, crypt authentication methods.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</sect2>
|
|
|
|
</sect1>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect1 id="jdbc-use">
|
|
|
|
<title>Using the Driver</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2 id="jdbc-import">
|
1999-10-04 17:16:35 +02:00
|
|
|
<title>Importing <acronym>JDBC</acronym></title>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Any source that uses <acronym>JDBC</acronym> needs to import the
|
|
|
|
<literal>java.sql</literal> package, using:
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
1998-10-25 02:27:44 +02:00
|
|
|
import java.sql.*;
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<important>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Do not import the <literal>org.postgresql</literal> package. If
|
|
|
|
you do, your source will not compile, as
|
|
|
|
<command>javac</command> will get confused.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</important>
|
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</sect2>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2 id="jdbc-load">
|
1999-10-04 17:16:35 +02:00
|
|
|
<title>Loading the Driver</title>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In the first method, your code implicitly loads the driver using the
|
|
|
|
<function>Class.forName()</function> method.
|
|
|
|
For <application>Postgres</application>, you would use:
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
2000-10-16 04:20:58 +02:00
|
|
|
Class.forName("org.postgresql.Driver");
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
This will load the driver, and while loading, the driver will automatically
|
|
|
|
register itself with <acronym>JDBC</acronym>.
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
The <function>forName()</function> method can throw a
|
|
|
|
<classname>ClassNotFoundException</classname> if the driver is
|
|
|
|
not available.
|
|
|
|
</para>
|
|
|
|
</note>
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
This is the most common method to use, but restricts your code to
|
|
|
|
use just <productname>Postgres</productname>. If your code may
|
|
|
|
access another database system in the future, and you do not use
|
|
|
|
any <productname>Postgres</productname>-specific extensions, then
|
|
|
|
the second method is advisable.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</sect2>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2 id="jdbc-connect">
|
1999-10-04 17:16:35 +02:00
|
|
|
<title>Connecting to the Database</title>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
With <acronym>JDBC</acronym>, a database is represented by a
|
|
|
|
<acronym>URL</acronym> (Uniform Resource Locator). With
|
|
|
|
<application>Postgres</application>, this takes one of the
|
|
|
|
following forms:
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
jdbc:postgresql:<replaceable class="parameter">database</replaceable>
|
|
|
|
</synopsis>
|
1999-10-04 17:16:35 +02:00
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
|
|
|
|
</synopsis>
|
1999-10-04 17:16:35 +02:00
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
|
|
|
|
</synopsis>
|
1999-10-04 17:16:35 +02:00
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
where:
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
|
|
<replaceable class="parameter">host</replaceable>
|
|
|
|
</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
The host name of the server. Defaults to <literal>localhost</literal>.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
|
|
<replaceable class="parameter">port</replaceable>
|
|
|
|
</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
The port number the server is listening on. Defaults to the
|
|
|
|
Postgres standard port number (5432).
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
|
|
<replaceable class="parameter">database</replaceable>
|
|
|
|
</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
The database name.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
To connect, you need to get a <classname>Connection</classname> instance from
|
1999-10-04 17:16:35 +02:00
|
|
|
<acronym>JDBC</acronym>. To do this,
|
2001-02-24 13:40:27 +01:00
|
|
|
you would use the <function>DriverManager.getConnection()</function> method:
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
|
|
|
Connection db = DriverManager.getConnection(url, username, password);
|
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</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>
|
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="jdbc-query">
|
1999-10-04 17:16:35 +02:00
|
|
|
<title>Issuing a Query and Processing the Result</title>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Any time you want to issue <acronym>SQL</acronym> statements to
|
|
|
|
the database, you require a <classname>Statement</classname>
|
|
|
|
instance. Once you have a <classname>Statement</classname>, you
|
|
|
|
can use the <function>executeQuery()</function> method to issue a
|
|
|
|
query. This will return a <classname>ResultSet</classname>
|
|
|
|
instance, which contains the entire result. <xref
|
|
|
|
linkend="jdbc-query-example"> illustrates this process.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<example id="jdbc-query-example">
|
|
|
|
<title>Processing a Simple Query in <acronym>JDCB</acronym></title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This example with issue a simple query and print out the first
|
|
|
|
column of each row.
|
|
|
|
<programlisting>
|
|
|
|
Statement st = db.createStatement();
|
|
|
|
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
|
|
|
|
while(rs.next()) {
|
|
|
|
System.out.print("Column 1 returned ");
|
|
|
|
System.out.println(rs.getString(1));
|
|
|
|
}
|
|
|
|
rs.close();
|
|
|
|
st.close();
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</example>
|
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
<sect2>
|
2001-02-24 13:40:27 +01:00
|
|
|
<title>Using the <classname>Statement</classname> Interface</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
The following must be considered when using the
|
|
|
|
<classname>Statement</classname> interface:
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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>.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
If you need to perform a query while processing a
|
|
|
|
<classname>ResultSet</classname>, you can simply create and
|
|
|
|
use another <classname>Statement</classname>.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2001-02-24 13:40:27 +01:00
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
2001-02-24 13:40:27 +01:00
|
|
|
<title>Using the <classname>ResultSet</classname> Interface</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
The following must be considered when using the
|
|
|
|
<classname>ResultSet</classname> interface:
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Under the <acronym>JDBC</acronym> specification, you should
|
|
|
|
access a field only once. It is safest to stick to this rule,
|
|
|
|
although at the current time, the
|
|
|
|
<productname>Postgres</productname> driver will allow you to
|
|
|
|
access a field as many times as you want.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
You must close a <classname>ResultSet</classname> by calling
|
|
|
|
<function>close()</function> once you have finished using it.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="jdbc-update">
|
1999-10-04 17:16:35 +02:00
|
|
|
<title>Performing Updates</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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:
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
|
|
|
st.executeUpdate("CREATE TABLE basic (a int, b int)");
|
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect1 id="jdbc-lo">
|
|
|
|
<title>Using Large Objects</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
In <application>Postgres</application>, <firstterm>Large
|
|
|
|
Objects</firstterm> (also known as <acronym>BLOB</acronym>s) are
|
|
|
|
used to hold data in the database that cannot be stored in a normal
|
|
|
|
SQL table. They are stored in a separate table in a special format,
|
|
|
|
and are referred to from your own tables by an OID value.
|
|
|
|
</para>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<important>
|
1999-10-04 17:16:35 +02:00
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
For <productname>Postgres</productname>, you must access Large
|
|
|
|
Objects within an <acronym>SQL</acronym> transaction. You would
|
|
|
|
open a transaction by using the
|
|
|
|
<function>setAutoCommit()</function> method with an input
|
|
|
|
parameter of <literal>false</literal>:
|
|
|
|
<programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
Connection mycon;
|
|
|
|
...
|
|
|
|
mycon.setAutoCommit(false);
|
2001-02-24 13:40:27 +01:00
|
|
|
... // now use Large Objects
|
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</important>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
There are two methods of using Large Objects. The first is the
|
1999-10-04 17:16:35 +02:00
|
|
|
standard <acronym>JDBC</acronym> way, and is documented here. The
|
2001-02-24 13:40:27 +01:00
|
|
|
other, uses <productname>PostgreSQL</productname> extensions to
|
2001-09-10 23:58:47 +02:00
|
|
|
the <acronym>API</acronym>, which presents the <application>libpq</application> large object
|
2001-02-24 13:40:27 +01:00
|
|
|
<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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
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.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<example id="jdbc-lo-example">
|
|
|
|
<title>Using the <acronym>JDBC</acronym> Large Object Interface</title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
For example, suppose you have a table containing the file name of
|
|
|
|
an image and you have a large object containing that image:
|
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE images (imgname text, imgoid oid);
|
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
1998-10-30 20:37:19 +01:00
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
<para>
|
|
|
|
To insert an image, you would use:
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
1999-04-15 08:00:16 +02:00
|
|
|
File file = new File("myimage.gif");
|
1998-10-25 02:27:44 +02:00
|
|
|
FileInputStream fis = new FileInputStream(file);
|
2001-02-24 13:40:27 +01:00
|
|
|
PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)"); <co id="co.jdbc-qmark">
|
|
|
|
ps.setString(1, file.getName());
|
|
|
|
ps.setBinaryStream(2, fis, file.length());
|
1998-10-25 02:27:44 +02:00
|
|
|
ps.executeUpdate();
|
|
|
|
ps.close();
|
|
|
|
fis.close();
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
|
|
|
<calloutlist>
|
|
|
|
<callout arearefs="co.jdbc-qmark">
|
|
|
|
<para>
|
|
|
|
The question marks must appear literally. The actual data is
|
|
|
|
substituted by the next lines.
|
|
|
|
</para>
|
|
|
|
</callout>
|
|
|
|
</calloutlist>
|
|
|
|
Here, <function>setBinaryStream</function> transfers a set number
|
|
|
|
of bytes from a stream into a Large Object, and stores the OID
|
|
|
|
into the field holding a reference to it. Notice that the
|
|
|
|
creation of the Large Object itself in the database happens
|
|
|
|
transparently.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
1998-10-30 20:37:19 +01:00
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Retrieving an image is even easier. (We use
|
|
|
|
<classname>PreparedStatement</classname> here, but the
|
|
|
|
<classname>Statement</classname> class can equally be used.)
|
1998-10-30 20:37:19 +01:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
2001-09-12 17:49:10 +02:00
|
|
|
PreparedStatement ps = con.prepareStatement("SELECT imgoid FROM images WHERE imgname=?");
|
2001-02-24 13:40:27 +01:00
|
|
|
ps.setString(1, "myimage.gif");
|
1998-10-25 02:27:44 +02:00
|
|
|
ResultSet rs = ps.executeQuery();
|
2001-02-24 13:40:27 +01:00
|
|
|
if (rs != null) {
|
1998-10-25 02:27:44 +02:00
|
|
|
while(rs.next()) {
|
2001-09-12 17:49:10 +02:00
|
|
|
InputStream is = rs.getBinaryStream(1);
|
1998-10-30 20:37:19 +01:00
|
|
|
// use the stream in some way here
|
|
|
|
is.close();
|
1998-10-25 02:27:44 +02:00
|
|
|
}
|
|
|
|
rs.close();
|
|
|
|
}
|
|
|
|
ps.close();
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-02-24 13:40:27 +01:00
|
|
|
Here you can see how the Large Object is retrieved as an
|
|
|
|
<classname>InputStream</classname>. You will also notice that we
|
|
|
|
close the stream before processing the next row in the
|
|
|
|
result. This is part of the <acronym>JDBC</acronym> specification,
|
|
|
|
which states that any <classname>InputStream</classname> returned
|
|
|
|
is closed when <function>ResultSet.next()</function> or
|
|
|
|
<function>ResultSet.close()</function> is called.
|
1999-10-04 17:16:35 +02:00
|
|
|
</para>
|
2001-02-24 13:40:27 +01:00
|
|
|
</example>
|
|
|
|
</sect1>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect1 id="jdbc-ext">
|
|
|
|
<title><application>PostgreSQL</application> Extensions to the
|
|
|
|
<acronym>JDBC</acronym> <acronym>API</acronym></title>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
<productname>Postgres</productname> is an extensible database
|
|
|
|
system. You can add your own functions to the backend, which can
|
|
|
|
then be called from queries, or even add your own data types. As
|
|
|
|
these are facilities unique to <productname>Postgres</productname>,
|
|
|
|
we support them from Java, with a set of extension
|
|
|
|
<acronym>API</acronym>'s. Some features within the core of the
|
|
|
|
standard driver actually use these extensions to implement Large
|
|
|
|
Objects, etc.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2>
|
|
|
|
<title>Accessing the Extensions</title>
|
1998-10-30 20:37:19 +01:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
To access some of the extensions, you need to use some extra
|
|
|
|
methods in the <classname>org.postgresql.Connection</classname>
|
|
|
|
class. In this case, you would need to case the return value of
|
|
|
|
<function>Driver.getConnection()</function>. For example:
|
1998-10-25 02:27:44 +02:00
|
|
|
<programlisting>
|
2001-02-24 13:40:27 +01:00
|
|
|
Connection db = Driver.getConnection(url, username, password);
|
|
|
|
// ...
|
|
|
|
// later on
|
|
|
|
Fastpath fp = ((org.postgresql.Connection)db).getFastpathAPI();
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect3>
|
|
|
|
<title>Class <classname>org.postgresql.Connection</classname></title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
public class Connection extends Object implements Connection
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.Connection
|
|
|
|
</synopsis>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
These are the extra methods used to gain access to
|
|
|
|
<productname>PostgreSQL</productname>'s extensions. Methods
|
|
|
|
defined by <classname>java.sql.Connection</classname> are not
|
|
|
|
listed.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect4>
|
|
|
|
<title>Methods</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public Fastpath getFastpathAPI() throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
This returns the Fastpath <acronym>API</acronym> for the
|
|
|
|
current connection. It is primarily used by the Large Object
|
|
|
|
<acronym>API</acronym>.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
The best way to use this is as follows:
|
|
|
|
<programlisting>
|
|
|
|
import org.postgresql.fastpath.*;
|
|
|
|
...
|
|
|
|
Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();
|
|
|
|
</programlisting>
|
2001-09-10 23:58:47 +02:00
|
|
|
where <varname>myconn</> is an open <classname>Connection</> to <productname>PostgreSQL</productname>.
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Returns:</title>
|
|
|
|
<para>
|
|
|
|
Fastpath object allowing access to functions on the
|
|
|
|
<productname>PostgreSQL</productname> backend.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Throws:</title>
|
|
|
|
<para>
|
|
|
|
SQLException by Fastpath when initializing for first time
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<synopsis>
|
|
|
|
public LargeObjectManager getLargeObjectAPI() throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
This returns the Large Object <acronym>API</acronym> for the
|
|
|
|
current connection.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
The best way to use this is as follows:
|
|
|
|
<programlisting>
|
|
|
|
import org.postgresql.largeobject.*;
|
|
|
|
...
|
|
|
|
LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
|
|
|
|
</programlisting>
|
2001-09-10 23:58:47 +02:00
|
|
|
where <varname>myconn</> is an open <classname>Connection</> to
|
2001-02-24 13:40:27 +01:00
|
|
|
<productname>PostgreSQL</productname>.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Returns:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<classname>LargeObject</classname> object that implements the <acronym>API</acronym>
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Throws:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<classname>SQLException</classname> by <classname>LargeObject</classname> when initializing for first time
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<synopsis>
|
|
|
|
public void addDataType(String type, String name)
|
|
|
|
</synopsis>
|
|
|
|
This allows client code to add a handler for one of
|
|
|
|
PostgreSQL's more unique data types. Normally, a data type not
|
2001-09-10 23:58:47 +02:00
|
|
|
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
|
2001-02-24 13:40:27 +01:00
|
|
|
class name to use. The down side to this, is that you must
|
|
|
|
call this method each time a connection is made.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
The best way to use this is as follows:
|
|
|
|
<programlisting>
|
1998-10-25 02:27:44 +02:00
|
|
|
...
|
2001-02-24 13:40:27 +01:00
|
|
|
((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name");
|
1998-10-25 02:27:44 +02:00
|
|
|
...
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
2001-09-10 23:58:47 +02:00
|
|
|
where <varname>myconn</varname> is an open <classname>Connection</> to
|
2001-02-24 13:40:27 +01:00
|
|
|
<productname>PostgreSQL</productname>. The handling class must
|
|
|
|
extend <classname>org.postgresql.util.PGobject</classname>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect4>
|
|
|
|
</sect3>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect3>
|
|
|
|
<title>Class <classname>org.postgresql.Fastpath</classname></title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
public class Fastpath extends Object
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.fastpath.Fastpath
|
|
|
|
</synopsis>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
<classname>Fastpath</classname> is an <acronym>API</acronym> that
|
2001-09-10 23:58:47 +02:00
|
|
|
exists within the <application>libpq</application> C interface, and allows a client machine
|
2001-02-24 13:40:27 +01:00
|
|
|
to execute a function on the database backend. Most client code
|
|
|
|
will not need to use this method, but it is provided because the
|
|
|
|
Large Object <acronym>API</acronym> uses it.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
To use, you need to import the
|
|
|
|
<classname>org.postgresql.fastpath</classname> package, using the
|
|
|
|
line:
|
|
|
|
<programlisting>
|
|
|
|
import org.postgresql.fastpath.*;
|
|
|
|
</programlisting>
|
|
|
|
Then, in your code, you need to get a
|
|
|
|
<classname>FastPath</classname> object:
|
|
|
|
<programlisting>
|
|
|
|
Fastpath fp = ((org.postgresql.Connection)conn).getFastpathAPI();
|
|
|
|
</programlisting>
|
|
|
|
This will return an instance associated with the database
|
|
|
|
connection that you can use to issue commands. The casing of
|
|
|
|
<classname>Connection</classname> to
|
|
|
|
<classname>org.postgresql.Connection</classname> is required, as
|
|
|
|
the <function>getFastpathAPI()</function> is an extension method,
|
|
|
|
not part of <acronym>JDBC</acronym>. Once you have a
|
|
|
|
<classname>Fastpath</classname> instance, you can use the
|
|
|
|
<function>fastpath()</function> methods to execute a backend
|
|
|
|
function.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>See Also:</title>
|
|
|
|
<para>
|
|
|
|
<classname>FastpathFastpathArg</classname>, <classname>LargeObject</classname>
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect4>
|
|
|
|
<title>Methods</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public Object fastpath(int fnid,
|
|
|
|
boolean resulttype,
|
|
|
|
FastpathArg args[]) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Send a function call to the PostgreSQL backend.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<parameter>fnid</> - Function id
|
|
|
|
<parameter>resulttype</> - True if the result is an integer, false
|
1998-10-25 02:27:44 +02:00
|
|
|
for
|
|
|
|
other results
|
2001-09-10 23:58:47 +02:00
|
|
|
<parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Returns:</title>
|
|
|
|
<para>
|
|
|
|
null if no data, Integer if an integer result, or byte[]
|
|
|
|
otherwise
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public Object fastpath(String name,
|
|
|
|
boolean resulttype,
|
|
|
|
FastpathArg args[]) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Send a function call to the PostgreSQL backend by name.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
The mapping for the procedure name to function id needs to
|
2001-09-10 23:58:47 +02:00
|
|
|
exist, usually to an earlier call to <function>addfunction()</function>. This is
|
2001-02-24 13:40:27 +01:00
|
|
|
the preferred method to call, as function id's can/may change
|
|
|
|
between versions of the backend. For an example of how this
|
|
|
|
works, refer to org.postgresql.LargeObject
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<parameter>name</> - Function name
|
|
|
|
<parameter>resulttype</> - True if the result is an integer, false
|
1998-10-25 02:27:44 +02:00
|
|
|
for
|
|
|
|
other results
|
2001-09-10 23:58:47 +02:00
|
|
|
<parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
|
2001-02-24 13:40:27 +01:00
|
|
|
</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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<parameter>name</parameter> - Function name
|
|
|
|
<parameter>args</parameter> - Function arguments
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Returns:</title>
|
|
|
|
<para>integer result</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Throws:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<classname>SQLException</classname> if a database-access error occurs or no result
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<parameter>name</parameter> - Function name
|
|
|
|
<parameter>args</parameter> - Function arguments
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Returns:</title>
|
|
|
|
<para>byte[] array containing result</para>
|
|
|
|
</formalpara>
|
|
|
|
|
|
|
|
<formalpara>
|
|
|
|
<title>Throws:</title>
|
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
<classname>SQLException</classname> if a database-access error occurs or no result
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<important>
|
|
|
|
<para>
|
|
|
|
Remember to <function>close()</function> the
|
|
|
|
<classname>ResultSet</classname> after calling this!
|
|
|
|
</para>
|
|
|
|
</important>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<title>Implementation note about function name look-ups</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
PostgreSQL stores the function id's and their corresponding
|
2001-09-10 23:58:47 +02:00
|
|
|
names in the <classname>pg_proc</> table. To speed things up locally,
|
2001-02-24 13:40:27 +01:00
|
|
|
instead of querying each function from that table when
|
|
|
|
required, a <classname>Hashtable</classname> is used. Also, only the function's
|
|
|
|
required are entered into this table, keeping connection
|
|
|
|
times as fast as possible.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <classname>org.postgresql.LargeObject</classname> class
|
|
|
|
performs a query upon its start-up, and passes the returned
|
|
|
|
<classname>ResultSet</classname> to the
|
|
|
|
<function>addFunctions()</function> method here. Once this
|
|
|
|
has been done, the Large Object <acronym>API</acronym> refers
|
|
|
|
to the functions by name.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Do not think that manually converting them to the oid's will
|
2001-09-10 23:58:47 +02:00
|
|
|
work. OK, they will for now, but they can change during
|
2001-02-24 13:40:27 +01:00
|
|
|
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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public int getID(String name) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
This returns the function id associated by its name If
|
2001-09-10 23:58:47 +02:00
|
|
|
<function>addFunction()</function> or <function>addFunctions()</function> have not been called for this
|
|
|
|
name, then an <classname>SQLException</classname> is thrown.
|
2001-02-24 13:40:27 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect4>
|
|
|
|
</sect3>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect3>
|
|
|
|
<title>Class <classname>org.postgresql.fastpath.FastpathArg</classname></title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
public class FastpathArg extends Object
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.fastpath.FastpathArg
|
|
|
|
</synopsis>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Each fastpath call requires an array of arguments, the number and
|
|
|
|
type dependent on the function being called. This class
|
|
|
|
implements methods needed to provide this capability.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
For an example on how to use this, refer to the
|
|
|
|
<classname>org.postgresql.LargeObject</classname> package.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>See Also:</title>
|
|
|
|
<para>
|
|
|
|
<classname>Fastpath</classname>, <classname>LargeObjectManager</classname>, <classname>LargeObject</classname>
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect4>
|
|
|
|
<title>Constructors</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public FastpathArg(int value)
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Constructs an argument that consists of an integer value
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
|
|
|
value - int value to set
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public FastpathArg(byte bytes[])
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Constructs an argument that consists of an array of bytes
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
|
|
|
bytes - array to store
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public FastpathArg(byte buf[],
|
|
|
|
int off,
|
|
|
|
int len)
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Constructs an argument that consists of part of a byte array
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2001-09-10 23:58:47 +02:00
|
|
|
<term><parameter>buf</></term>
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<simpara>source array</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2001-09-10 23:58:47 +02:00
|
|
|
<term><parameter>off</parameter></term>
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<simpara>offset within array</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2001-09-10 23:58:47 +02:00
|
|
|
<term><parameter>len</parameter></term>
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<simpara>length of data to include</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public FastpathArg(String s)
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Constructs an argument that consists of a String.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect4>
|
|
|
|
</sect3>
|
|
|
|
</sect2>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2>
|
|
|
|
<title>Geometric Data Types</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
|
|
|
Class org.postgresql.geometric.PGbox
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGbox
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGbox extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This represents the box data type within <productname>PostgreSQL</productname>.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Variables
|
|
|
|
|
|
|
|
public PGpoint point[]
|
|
|
|
|
|
|
|
These are the two corner points of the box.
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
|
|
|
public PGbox(double x1,
|
|
|
|
double y1,
|
|
|
|
double x2,
|
|
|
|
double y2)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
x1 - first x coordinate
|
|
|
|
y1 - first y coordinate
|
|
|
|
x2 - second x coordinate
|
|
|
|
y2 - second y coordinate
|
|
|
|
|
|
|
|
public PGbox(PGpoint p1,
|
|
|
|
PGpoint p2)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
p1 - first point
|
|
|
|
p2 - second point
|
|
|
|
|
|
|
|
public PGbox(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - Box definition in PostgreSQL syntax
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
if definition is invalid
|
|
|
|
|
|
|
|
public PGbox()
|
|
|
|
|
|
|
|
Required constructor
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String value) throws SQLException
|
|
|
|
|
|
|
|
This method sets the value of this object. It should be
|
2001-02-24 13:40:27 +01:00
|
|
|
overridden, but still called by subclasses.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-02-24 13:40:27 +01:00
|
|
|
the PGbox in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
getValue in class PGobject
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.geometric.PGcircle
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGcircle
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGcircle extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This represents <productname>PostgreSQL</productname>'s circle data type, consisting of a point
|
1998-10-25 02:27:44 +02:00
|
|
|
and a radius
|
|
|
|
|
|
|
|
Variables
|
|
|
|
|
|
|
|
public PGpoint center
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This is the center point
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-09-12 17:49:10 +02:00
|
|
|
double radius
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
This is the radius
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
|
|
|
public PGcircle(double x,
|
|
|
|
double y,
|
|
|
|
double r)
|
|
|
|
|
|
|
|
Parameters:
|
2001-02-24 13:40:27 +01:00
|
|
|
x - coordinate of center
|
|
|
|
y - coordinate of center
|
1998-10-25 02:27:44 +02:00
|
|
|
r - radius of circle
|
|
|
|
|
|
|
|
public PGcircle(PGpoint c,
|
|
|
|
double r)
|
|
|
|
|
|
|
|
Parameters:
|
2001-02-24 13:40:27 +01:00
|
|
|
c - PGpoint describing the circle's center
|
1998-10-25 02:27:44 +02:00
|
|
|
r - radius of circle
|
|
|
|
|
|
|
|
public PGcircle(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - definition of the circle in PostgreSQL's syntax.
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
public PGcircle()
|
|
|
|
|
|
|
|
This constructor is used by the driver.
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - definition of the circle in PostgreSQL's syntax.
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two circles are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-02-24 13:40:27 +01:00
|
|
|
the PGcircle in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
getValue in class PGobject
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.geometric.PGline
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGline
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGline extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
|
|
|
This implements a line consisting of two points. Currently line is
|
|
|
|
not yet implemented in the backend, but this class ensures that when
|
|
|
|
it's done were ready for it.
|
|
|
|
|
|
|
|
Variables
|
|
|
|
|
|
|
|
public PGpoint point[]
|
|
|
|
|
|
|
|
These are the two points.
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
|
|
|
public PGline(double x1,
|
|
|
|
double y1,
|
|
|
|
double x2,
|
|
|
|
double y2)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
x1 - coordinate for first point
|
|
|
|
y1 - coordinate for first point
|
|
|
|
x2 - coordinate for second point
|
|
|
|
y2 - coordinate for second point
|
|
|
|
|
|
|
|
public PGline(PGpoint p1,
|
|
|
|
PGpoint p2)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
p1 - first point
|
|
|
|
p2 - second point
|
|
|
|
|
|
|
|
public PGline(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
2001-09-12 17:55:00 +02:00
|
|
|
s - definition of the line in PostgreSQL's syntax.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
public PGline()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
required by the driver
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - Definition of the line segment in PostgreSQL's
|
|
|
|
syntax
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two lines are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-02-24 13:40:27 +01:00
|
|
|
the PGline in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
getValue in class PGobject
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.geometric.PGlseg
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGlseg
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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:
|
2001-09-12 17:55:00 +02:00
|
|
|
s - Definition of the line segment in PostgreSQL's syntax.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
public PGlseg()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
required by the driver
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - Definition of the line segment in PostgreSQL's
|
|
|
|
syntax
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two line segments are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-02-24 13:40:27 +01:00
|
|
|
the PGlseg in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
getValue in class PGobject
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.geometric.PGpath
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGpath
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGpath extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
2000-12-22 19:57:50 +01:00
|
|
|
This implements a path (a multiply segmented line, which may be
|
1998-10-25 02:27:44 +02:00
|
|
|
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:
|
2001-09-12 17:55:00 +02:00
|
|
|
s - definition of the path in PostgreSQL's syntax.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - Definition of the path in PostgreSQL's syntax
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two pathes are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
2001-09-12 17:55:00 +02:00
|
|
|
This returns the path in the syntax expected by
|
2001-02-24 13:40:27 +01:00
|
|
|
<productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.geometric.PGpoint
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGpoint
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGpoint extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
|
|
|
This implements a version of java.awt.Point, except it uses double
|
|
|
|
to represent the coordinates.
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
It maps to the point data type in <productname>PostgreSQL</productname>.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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
|
2001-02-24 13:40:27 +01:00
|
|
|
point is embedded within their definition.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Parameters:
|
|
|
|
value - Definition of this point in PostgreSQL's
|
|
|
|
syntax
|
|
|
|
|
|
|
|
public PGpoint()
|
|
|
|
|
|
|
|
Required by the driver
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - Definition of this point in PostgreSQL's syntax
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two points are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-02-24 13:40:27 +01:00
|
|
|
the PGpoint in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.geometric.PGpolygon
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.geometric.PGpolygon
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGpolygon extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This implements the polygon data type within PostgreSQL.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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:
|
2001-09-12 17:55:00 +02:00
|
|
|
s - definition of the polygon in PostgreSQL's syntax.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
public PGpolygon()
|
|
|
|
|
|
|
|
Required by the driver
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
s - Definition of the polygon in PostgreSQL's syntax
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two polygons are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-02-24 13:40:27 +01:00
|
|
|
the PGpolygon in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
getValue in class PGobject
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
|
|
|
</sect2>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2>
|
|
|
|
<title>Large Objects</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Large objects are supported in the standard
|
|
|
|
<acronym>JDBC</acronym> specification. However, that interface is
|
|
|
|
limited, and the <acronym>API</acronym> provided by PostgreSQL allows for random
|
|
|
|
access to the objects contents, as if it was a local file.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
2001-09-10 23:58:47 +02:00
|
|
|
The org.postgresql.largeobject package provides to Java the <application>libpq</application>
|
2001-02-24 13:40:27 +01:00
|
|
|
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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect3>
|
|
|
|
<title>Class <classname>org.postgresql.largeobject.LargeObject</classname></title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
1998-10-25 02:27:44 +02:00
|
|
|
public class LargeObject extends Object
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
java.lang.Object
|
|
|
|
|
|
|
|
|
+----org.postgresql.largeobject.LargeObject
|
|
|
|
</synopsis>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
This class implements the large object interface to
|
|
|
|
<productname>PostgreSQL</productname>.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Normally, client code would use the getAsciiStream,
|
|
|
|
getBinaryStream, or getUnicodeStream methods in <classname>ResultSet</classname>, or
|
|
|
|
setAsciiStream, setBinaryStream, or setUnicodeStream methods in
|
|
|
|
<classname>PreparedStatement</classname> to access Large Objects.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
However, sometimes lower level access to Large Objects are
|
|
|
|
required, that are not supported by the <acronym>JDBC</acronym>
|
|
|
|
specification.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Refer to org.postgresql.largeobject.LargeObjectManager on how to
|
|
|
|
gain access to a Large Object, or how to create one.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public int getOID()
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Returns the OID of this <classname>LargeObject</classname>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
2001-09-12 17:49:10 +02:00
|
|
|
public int read(byte buf[],
|
2001-02-24 13:40:27 +01:00
|
|
|
int off,
|
|
|
|
int len) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Reads some data from the object into an existing array
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>buf</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>destination array</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>off</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>offset within array</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>len</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>number of bytes to read</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public void write(byte buf[]) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Writes an array to the object
|
|
|
|
</para>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public void write(byte buf[],
|
1998-10-25 02:27:44 +02:00
|
|
|
int off,
|
|
|
|
int len) throws SQLException
|
2001-02-24 13:40:27 +01:00
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
Writes some data from an array to the object
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<formalpara>
|
|
|
|
<title>Parameters:</title>
|
|
|
|
<para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>buf</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>destination array</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>off</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>offset within array</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>len</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>number of bytes to write</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!--
|
1998-10-25 02:27:44 +02:00
|
|
|
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.
|
2001-02-24 13:40:27 +01:00
|
|
|
-->
|
|
|
|
</itemizedlist>
|
|
|
|
</sect4>
|
|
|
|
</sect3>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect3>
|
|
|
|
<title>Class <classname>org.postgresql.largeobject.LargeObjectManager</classname></title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<synopsis>
|
|
|
|
public class LargeObjectManager extends Object
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
java.lang.Object
|
|
|
|
|
|
|
|
|
+----org.postgresql.largeobject.LargeObjectManager
|
|
|
|
</synopsis>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
This class can only be created by org.postgresql.Connection. To
|
|
|
|
get access to this class, use the following segment of code:
|
|
|
|
<programlisting>
|
|
|
|
import org.postgresql.largeobject.*;
|
|
|
|
Connection conn;
|
|
|
|
LargeObjectManager lobj;
|
|
|
|
// ... code that opens a connection ...
|
|
|
|
lobj = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Normally, client code would use the getAsciiStream,
|
|
|
|
getBinaryStream, or getUnicodeStream methods in ResultSet, or
|
|
|
|
setAsciiStream, setBinaryStream, or setUnicodeStream methods in
|
|
|
|
PreparedStatement to access Large Objects. However, sometimes
|
|
|
|
lower level access to Large Objects are required, that are not
|
|
|
|
supported by the <acronym>JDBC</acronym> specification.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Refer to org.postgresql.largeobject.LargeObject on how to
|
|
|
|
manipulate the contents of a Large Object.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect4>
|
|
|
|
<title>Variables</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>public static final int WRITE</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>This mode indicates we want to write to an object.</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>public static final int READ</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>This mode indicates we want to read an object.</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>public static final int READWRITE</term>
|
|
|
|
<listitem>
|
|
|
|
<simpara>This mode is the default. It indicates we want read and write access to a large object.</simpara>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect4>
|
|
|
|
|
|
|
|
<sect4>
|
|
|
|
<title>Methods</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public LargeObject open(int oid) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
This opens an existing large object, based on its OID. This
|
|
|
|
method assumes that READ and WRITE access is required (the
|
|
|
|
default).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public int create() throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
This creates a large object, returning its OID.
|
|
|
|
It defaults to READWRITE for the new object's attributes.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<listitem>
|
|
|
|
<synopsis>
|
|
|
|
public void delete(int oid) throws SQLException
|
|
|
|
</synopsis>
|
|
|
|
<para>
|
|
|
|
This deletes a large object.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect2>
|
|
|
|
<title>Object Serialization</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
One of the consequences of this, is that you can have one table
|
|
|
|
refer to a row in another table. For example:
|
|
|
|
<screen>
|
1998-10-25 02:27:44 +02:00
|
|
|
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)
|
2001-02-24 13:40:27 +01:00
|
|
|
</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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
What does this have to do with Java?
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
Sound's complicated? In fact, it's simpler than what I wrote -
|
|
|
|
it's just difficult to explain.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
The only time you would access this class, is to use the create()
|
|
|
|
methods. These are not used by the driver, but issue one or more
|
|
|
|
"create table" statements to the database, based on a Java Object
|
|
|
|
or Class that you want to serialize.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<programlisting>
|
|
|
|
Class org.postgresql.util.Serialize
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.Serialize
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class Serialize extends Object
|
|
|
|
|
|
|
|
This class uses PostgreSQL's object oriented features to store Java
|
|
|
|
Objects. It does this by mapping a Java Class name to a table in the
|
|
|
|
database. Each entry in this new table then represents a Serialized
|
|
|
|
instance of this class. As each entry has an OID (Object IDentifier),
|
|
|
|
this OID can be included in another table. This is too complex to show
|
|
|
|
here, and will be documented in the main documents in more detail.
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
2001-09-12 17:49:10 +02:00
|
|
|
public Serialize(org.postgresql.Connection c,
|
1998-10-25 02:27:44 +02:00
|
|
|
String type) throws SQLException
|
|
|
|
|
|
|
|
This creates an instance that can be used to serialize
|
2001-02-24 13:40:27 +01:00
|
|
|
or deserialize a Java object from a PostgreSQL table.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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
|
|
|
|
|
2001-09-12 17:49:10 +02:00
|
|
|
public static void create(org.postgresql.Connection con,
|
1998-10-25 02:27:44 +02:00
|
|
|
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
|
|
|
|
|
2001-09-12 17:49:10 +02:00
|
|
|
public static void create(org.postgresql.Connection con,
|
1998-10-25 02:27:44 +02:00
|
|
|
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
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This converts a Java Class name to a <productname>PostgreSQL</productname> table, by
|
1998-10-25 02:27:44 +02:00
|
|
|
replacing . with _
|
|
|
|
|
|
|
|
Because of this, a Class name may not have _ in the name.
|
|
|
|
|
|
|
|
Another limitation, is that the entire class name (including
|
|
|
|
packages) cannot be longer than 31 characters (a limit
|
|
|
|
forced by PostgreSQL).
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
name - Class name
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
PostgreSQL table name
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on error
|
|
|
|
|
|
|
|
public static String toClassName(String name) throws SQLException
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This converts a <productname>PostgreSQL</productname> table to a Java Class name, by
|
1998-10-25 02:27:44 +02:00
|
|
|
replacing _ with .
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
name - PostgreSQL table name
|
|
|
|
|
|
|
|
Returns:
|
|
|
|
Class name
|
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on error
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
1998-10-25 02:27:44 +02:00
|
|
|
Utility Classes
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
The org.postgresql.util package contains classes used by the internals of
|
1998-10-25 02:27:44 +02:00
|
|
|
the main driver, and the other extensions.
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
Class org.postgresql.util.PGmoney
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGmoney
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGmoney extends PGobject implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
|
|
|
This implements a class that handles the PostgreSQL money type
|
|
|
|
|
|
|
|
Variables
|
|
|
|
|
|
|
|
public double val
|
|
|
|
|
|
|
|
The value of the field
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
|
|
|
public PGmoney(double value)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
value - of field
|
|
|
|
|
|
|
|
public PGmoney(String value) throws SQLException
|
|
|
|
|
2001-09-12 17:55:00 +02:00
|
|
|
Create a money.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Parameters:
|
2001-09-12 17:55:00 +02:00
|
|
|
value - Definition of this money in PostgreSQL's
|
1998-10-25 02:27:44 +02:00
|
|
|
syntax
|
|
|
|
|
|
|
|
public PGmoney()
|
|
|
|
|
|
|
|
Required by the driver
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public void setValue(String s) throws SQLException
|
|
|
|
|
|
|
|
Parameters:
|
2001-09-12 17:55:00 +02:00
|
|
|
s - Definition of this money in PostgreSQL's syntax
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Throws: SQLException
|
|
|
|
on conversion failure
|
|
|
|
|
|
|
|
Overrides:
|
|
|
|
setValue in class PGobject
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two moneys are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class PGobject
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class PGobject
|
|
|
|
|
|
|
|
public String getValue()
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
the PGmoney in the syntax expected by <productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
getValue in class PGobject
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGobject
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGobject extends Object implements Serializable,
|
|
|
|
Cloneable
|
|
|
|
|
1999-10-04 17:16:35 +02:00
|
|
|
This class is used to describe data types that are unknown by
|
|
|
|
<acronym>JDBC</acronym>
|
1998-10-25 02:27:44 +02:00
|
|
|
Standard.
|
2001-02-24 13:40:27 +01:00
|
|
|
A call to org.postgresql.Connection permits a class that extends this
|
1998-10-25 02:27:44 +02:00
|
|
|
class to be associated with a named type. This is how the
|
2001-02-24 13:40:27 +01:00
|
|
|
org.postgresql.geometric package operates.
|
1998-10-25 02:27:44 +02:00
|
|
|
ResultSet.getObject() will return this class for any type that is
|
2001-02-24 13:40:27 +01:00
|
|
|
not recognized on having it's own handler. Because of this, any
|
|
|
|
<productname>PostgreSQL</productname> data type is supported.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
|
|
|
public PGobject()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This is called by org.postgresql.Connection.getObject() to
|
1998-10-25 02:27:44 +02:00
|
|
|
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
|
2001-02-24 13:40:27 +01:00
|
|
|
overridden.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden, to return the value of the object,
|
|
|
|
in the form required by <productname>PostgreSQL</productname>.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Returns:
|
|
|
|
the value of this object
|
|
|
|
|
|
|
|
public boolean equals(Object obj)
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow comparisons of objects
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Parameters:
|
|
|
|
obj - Object to compare with
|
|
|
|
|
|
|
|
Returns:
|
2001-09-12 17:55:00 +02:00
|
|
|
true if the two objects are identical
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
equals in class Object
|
|
|
|
|
|
|
|
public Object clone()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This must be overridden to allow the object to be cloned
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
clone in class Object
|
|
|
|
|
|
|
|
public String toString()
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This is defined here, so user code need not override it.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Returns:
|
|
|
|
the value of this object, in the syntax expected by
|
2001-02-24 13:40:27 +01:00
|
|
|
<productname>PostgreSQL</productname>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Overrides:
|
|
|
|
toString in class Object
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.util.PGtokenizer
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.PGtokenizer
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
public class PGtokenizer extends Object
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This class is used to tokenize the text output of <productname>PostgreSQL</productname>.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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
|
2001-02-24 13:40:27 +01:00
|
|
|
any output from custom data types output from <productname>PostgreSQL</productname>.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
See Also:
|
|
|
|
PGbox, PGcircle, PGlseg, PGpath, PGpoint, PGpolygon
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
|
|
|
|
public PGtokenizer(String string,
|
|
|
|
char delim)
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
Create a tokenizer.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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
|
2001-02-24 13:40:27 +01:00
|
|
|
geometric data types use this to process nested tokens (usually
|
1998-10-25 02:27:44 +02:00
|
|
|
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
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<!-- **************************************************************** -->
|
|
|
|
Class org.postgresql.util.Serialize
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
This was documented earlier under Object Serialization.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
Class org.postgresql.util.UnixCrypt
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
java.lang.Object
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
+----org.postgresql.util.UnixCrypt
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2001-09-12 17:49:10 +02:00
|
|
|
See John Dumas's Java Crypt page for the original source.
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-09-12 17:49:10 +02:00
|
|
|
(Invalid URL) http://www.zeh.com/local/jfd/crypt.html
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Methods
|
|
|
|
|
|
|
|
public static final String crypt(String salt,
|
|
|
|
String original)
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
Encrypt a password given the clear-text password and a
|
1998-10-25 02:27:44 +02:00
|
|
|
"salt".
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
salt - A two-character string representing the salt
|
|
|
|
used
|
|
|
|
to iterate the encryption engine in lots of different
|
|
|
|
ways. If you are generating a new encryption then this
|
2001-02-24 13:40:27 +01:00
|
|
|
value should be randomized.
|
1998-10-25 02:27:44 +02:00
|
|
|
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)
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
Encrypt a password given the clear-text password. This method
|
1998-10-25 02:27:44 +02:00
|
|
|
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
|
2001-02-24 13:40:27 +01:00
|
|
|
(or otherwise acquired).
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
Returns:
|
|
|
|
true if the password should be considered correct.
|
2001-02-24 13:40:27 +01:00
|
|
|
</programlisting>
|
|
|
|
</sect2>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
</sect1>
|
|
|
|
<!-- **************************************************************** -->
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect1 id="jdbc-thread">
|
|
|
|
<title>Using the driver in a multi-threaded or a servlet environment</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
A problem with many <acronym>JDBC</acronym> drivers is that only
|
|
|
|
one thread can use a <classname>Connection</classname> at any one
|
|
|
|
time -- otherwise a thread could send a query while another one is
|
|
|
|
receiving results, and this would be a bad thing for the database
|
|
|
|
engine.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
<productname>PostgreSQL</productname> 6.4 brought thread safety to
|
|
|
|
the entire driver. (Standard <acronym>JDBC</acronym> was thread
|
|
|
|
safe in 6.3, but the Fastpath <acronym>API</acronym> was not.)
|
|
|
|
Consequently, if your application uses multiple threads then you do
|
|
|
|
not have to worry about complex algorithms to ensure that only one
|
|
|
|
uses the database at any time.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
If a thread attempts to use the connection while another one is
|
|
|
|
using it, it will wait until the other thread has finished its
|
|
|
|
current operation. If it is a regular <acronym>SQL</acronym>
|
|
|
|
statement, then the operation consists of sending the statement and
|
|
|
|
retrieving any <classname>ResultSet</classname> (in full). If it
|
|
|
|
is a <classname>Fastpath</classname> call (e.g., reading a block
|
|
|
|
from a <classname>LargeObject</classname>) then it is the time to
|
|
|
|
send and retrieve that block.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
This is fine for applications and applets but can cause a
|
|
|
|
performance problem with servlets. With servlets you can have a
|
|
|
|
heavy load on the connection. If you have several threads
|
|
|
|
performing queries then each but one will pause, which may not be what
|
|
|
|
you are after.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<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>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
So, with servlets, it is up to you to use either a single
|
|
|
|
connection, or a pool. The plus side for a pool is that threads
|
|
|
|
will not be hit by the bottle neck caused by a single network
|
|
|
|
connection. The down side is that it increases the load on the
|
|
|
|
server, as a backend process is created for each
|
|
|
|
<classname>Connection</classname>. It is up to you and your
|
|
|
|
applications requirements.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<sect1 id="jdbc-reading">
|
|
|
|
<title>Further Reading</title>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
If you have not yet read it, I'd advise you read the
|
|
|
|
<acronym>JDBC</acronym> <acronym>API</acronym> Documentation
|
|
|
|
(supplied with Sun's <acronym>JDK</acronym>), and the
|
|
|
|
<acronym>JDBC</acronym> Specification. Both are available from
|
|
|
|
<ulink
|
|
|
|
url="http://java.sun.com/products/jdbc/index.html">http://java.sun.com/products/jdbc/index.html</ulink>.
|
|
|
|
</para>
|
1998-10-25 02:27:44 +02:00
|
|
|
|
2001-02-24 13:40:27 +01:00
|
|
|
<para>
|
|
|
|
<ulink
|
|
|
|
url="http://jdbc.postgresql.org">http://jdbc.postgresql.org</ulink>
|
|
|
|
contains updated information not included in this document, and
|
|
|
|
also includes precompiled drivers.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
1998-12-29 03:24:47 +01:00
|
|
|
</chapter>
|
1999-10-04 17:16:35 +02:00
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
2000-03-31 05:27:42 +02:00
|
|
|
mode:sgml
|
1999-10-04 17:16:35 +02:00
|
|
|
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
|
2000-03-31 05:27:42 +02:00
|
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
1999-10-04 17:16:35 +02:00
|
|
|
sgml-local-ecat-files:nil
|
|
|
|
End:
|
1999-10-09 04:30:02 +02:00
|
|
|
-->
|