2000-03-31 05:27:42 +02:00
<!--
2003-12-14 00:59:07 +01:00
$PostgreSQL: pgsql/doc/src/sgml/jdbc.sgml,v 1.52 2003/12/13 23:59:06 neilc 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
2003-08-31 19:32:24 +02:00
<indexterm zone="jdbc">
<primary>JDBC</primary>
</indexterm>
<indexterm zone="jdbc">
<primary>Java</primary>
</indexterm>
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-11-21 06:53:41 +01:00
<productname>PostgreSQL</> provides a <firstterm>type
2003-04-07 03:29:26 +02:00
4</firstterm> <acronym>JDBC</acronym> driver. Type 4 indicates
2001-02-24 13:40:27 +01:00
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.
2003-04-07 03:29:26 +02:00
Also, take a look at the examples included with the source.
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
<sect1 id="jdbc-setup">
<title>Setting up the <acronym>JDBC</acronym> Driver</title>
1999-10-04 17:16:35 +02:00
2003-04-07 03:29:26 +02:00
<para>
This section describes the steps you need to take before you can
2003-06-30 18:39:42 +02:00
write or run programs that use the <acronym>JDBC</> interface.
2003-04-07 03:29:26 +02:00
</para>
2001-02-24 13:40:27 +01:00
<sect2 id="jdbc-build">
2001-10-26 00:00:31 +02:00
<title>Getting the Driver</title>
1999-10-04 17:16:35 +02:00
2001-02-24 13:40:27 +01:00
<para>
2001-10-26 00:00:31 +02:00
Precompiled versions of the driver can be downloaded from
2001-02-24 13:40:27 +01:00
the <ulink
url="http://jdbc.postgresql.org"><productname>PostgreSQL</productname>
2001-10-26 00:00:31 +02:00
<acronym>JDBC</acronym> web site</ulink>.
</para>
<para>
2002-11-15 04:11:18 +01:00
Alternatively you can build the driver from source, but you should
only need to do this if you are making changes to the source code.
2003-06-30 18:39:42 +02:00
For details, refer to the <productname>PostgreSQL</>
<link linkend="installation">installation instructions</link>.
After installation, the driver should be found in
2002-09-18 22:09:32 +02:00
<filename><replaceable>PREFIX</>/share/java/postgresql.jar</filename>.
The resulting driver will be built for the version of Java you are
2002-11-15 04:11:18 +01:00
running. If you build with a 1.1 <acronym>JDK</> you will build a
2003-06-30 18:39:42 +02:00
version that supports the <acronym>JDBC</> 1 specification, if you build
with a 1.2 or 1.3 <acronym>JDK</> you will build a version that supports
the <acronym>JDBC</> 2 specification, and finally if you build with a
1.4 <acronym>JDK</acronym> you will build a version that supports the
<acronym>JDBC</> 3 specification.
2001-02-24 13:40:27 +01:00
</para>
</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
2003-08-31 19:32:24 +02:00
<indexterm zone="jdbc-classpath">
<primary>class path</primary>
</indexterm>
<indexterm zone="jdbc-classpath">
<primary>CLASSPATH</primary>
</indexterm>
2001-02-24 13:40:27 +01:00
<para>
2002-09-18 22:09:32 +02:00
To use the driver, the JAR archive (named
2001-10-26 00:00:31 +02:00
<filename>postgresql.jar</filename> if you built from source, otherwise
2003-06-30 18:39:42 +02:00
it will likely be named <filename>pg&majorversion;jdbc1.jar</filename>,
<filename>pg&majorversion;jdbc2.jar</filename>, or
<filename>pg&majorversion;jdbc3.jar</filename> for the <acronym>JDBC</> 1,
<acronym>JDBC</> 2, and <acronym>JDBC</> 3 versions respectively)
needs to be included in the class path, either by putting it in the
<envar>CLASSPATH</envar> environment variable, or by using flags on the
2002-09-18 22:09:32 +02:00
<command>java</command> command line.
2001-02-24 13:40:27 +01:00
</para>
1999-10-04 17:16:35 +02:00
2003-04-07 03:29:26 +02:00
<para>
For instance, assume we have an application that uses the
<acronym>JDBC</acronym> driver to access a database, and that
application is installed as
2003-12-14 00:59:07 +01:00
<filename>/usr/local/lib/myapp.jar</filename>. The
<productname>PostgreSQL</> <acronym>JDBC</> driver installed as
2003-04-07 03:29:26 +02:00
<filename>/usr/local/pgsql/share/java/postgresql.jar</>. To run
the application, we would use:
2001-02-24 13:40:27 +01:00
<programlisting>
2003-04-07 03:29:26 +02:00
export CLASSPATH=/usr/local/lib/myapp.jar:/usr/local/pgsql/share/java/postgresql.jar:.
java MyApp
2001-02-24 13:40:27 +01:00
</programlisting>
</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>
</sect2>
1999-10-04 17:16:35 +02:00
2001-02-24 13:40:27 +01:00
<sect2 id="jdbc-prepare">
2003-04-07 03:29:26 +02:00
<title>Preparing the Database Server for <acronym>JDBC</acronym></title>
1999-10-04 17:16:35 +02:00
<para>
2001-10-26 00:00:31 +02:00
Because Java only uses TCP/IP connections, the
2003-12-14 00:59:07 +01:00
<productname>PostgreSQL</productname> server must be configured to
accept TCP/IP connections. This can be done by setting
<literal>tcpip_socket = true</literal> in the
2001-10-26 00:00:31 +02:00
<filename>postgresql.conf</filename> file or by supplying the
<option>-i</option> option flag when starting
2001-02-24 13:40:27 +01:00
<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.
2003-03-25 17:15:44 +01:00
Refer to <xref linkend="client-authentication"> for details. The
2003-06-30 18:39:42 +02:00
<acronym>JDBC</acronym> driver supports the <literal>trust</>,
<literal>ident</>, <literal>password</>, <literal>md5</>, and
<literal>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">
2003-04-07 03:29:26 +02:00
<title>Initializing the Driver</title>
<para>
2003-06-30 18:39:42 +02:00
This section describes how to load and initialize the <acronym>JDBC</>
driver in your programs.
2003-04-07 03:29:26 +02:00
</para>
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>
2003-04-07 03:29:26 +02:00
</para>
1999-10-04 17:16:35 +02:00
2003-04-07 03:29:26 +02:00
<note>
1999-10-04 17:16:35 +02:00
<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>
2003-04-07 03:29:26 +02:00
</note>
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.
2001-11-21 06:53:41 +01:00
For <productname>PostgreSQL</>, you would use:
1999-10-04 17:16:35 +02:00
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>.
2003-04-07 03:29:26 +02:00
</para>
1999-10-04 17:16:35 +02:00
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>
2001-02-24 13:40:27 +01:00
This is the most common method to use, but restricts your code to
2001-11-21 06:53:41 +01:00
use just <productname>PostgreSQL</productname>. If your code may
2001-02-24 13:40:27 +01:00
access another database system in the future, and you do not use
2001-11-21 06:53:41 +01:00
any <productname>PostgreSQL</productname>-specific extensions, then
2001-02-24 13:40:27 +01:00
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
2003-12-14 00:59:07 +01:00
<productname>PostgreSQL</productname>, this takes one of the
2001-02-24 13:40:27 +01:00
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>
2003-09-20 22:12:05 +02:00
The parameters have the following meanings:
1999-10-04 17:16:35 +02:00
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
2003-06-30 18:39:42 +02:00
The host name of the server. Defaults to <literal>localhost</literal>. To specify an IPv6 address your must enclose the <replaceable class="parameter">host</replaceable> parameter with square brackets, for example:
<programlisting>
jdbc:postgresql://[::1]:5740/accounting
</programlisting>
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
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> 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,
2003-04-07 03:29:26 +02:00
you 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>
2003-08-31 19:32:24 +02:00
<indexterm zone="jdbc-query">
<primary>Statement</primary>
</indexterm>
<indexterm zone="jdbc-query">
<primary>PreparedStatement</primary>
</indexterm>
<indexterm zone="jdbc-query">
<primary>ResultSet</primary>
</indexterm>
1999-10-04 17:16:35 +02:00
<para>
2001-02-24 13:40:27 +01:00
Any time you want to issue <acronym>SQL</acronym> statements to
2001-11-26 06:57:57 +01:00
the database, you require a <classname>Statement</classname> or
<classname>PreparedStatement</classname> instance. Once you have
2001-11-27 02:20:17 +01:00
a <classname>Statement</classname> or
<classname>PreparedStatement</classname>, you can use issue a
2001-02-24 13:40:27 +01:00
query. This will return a <classname>ResultSet</classname>
2003-08-07 01:50:19 +02:00
instance, which contains the entire result (see <xref linkend="jdbc-query-with-cursor">
here for how to alter this behaviour).
<xref linkend="jdbc-query-example"> illustrates this process.
1999-10-04 17:16:35 +02:00
</para>
2001-02-24 13:40:27 +01:00
<example id="jdbc-query-example">
2002-10-01 06:09:13 +02:00
<title>Processing a Simple Query in <acronym>JDBC</acronym></title>
2001-02-24 13:40:27 +01:00
<para>
2001-11-26 06:57:57 +01:00
This example will issue a simple query and print out the first
column of each row using a <classname>Statement</classname>.
2001-02-24 13:40:27 +01:00
<programlisting>
Statement st = db.createStatement();
2003-04-07 03:29:26 +02:00
ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnfoo = 500");
while (rs.next()) {
2001-11-26 06:57:57 +01:00
System.out.print("Column 1 returned ");
System.out.println(rs.getString(1));
}
rs.close();
st.close();
</programlisting>
</para>
<para>
2003-04-07 03:29:26 +02:00
This example issues the same query as before but uses
2001-11-26 06:57:57 +01:00
a <classname>PreparedStatement</classname>
and a bind value in the query.
<programlisting>
int foovalue = 500;
2003-04-07 03:29:26 +02:00
PreparedStatement st = db.prepareStatement("SELECT * FROM mytable WHERE columnfoo = ?");
2001-11-26 06:57:57 +01:00
st.setInt(1, foovalue);
ResultSet rs = st.executeQuery();
2003-04-07 03:29:26 +02:00
while (rs.next()) {
2001-02-24 13:40:27 +01:00
System.out.print("Column 1 returned ");
System.out.println(rs.getString(1));
}
rs.close();
st.close();
</programlisting>
</para>
</example>
2003-08-07 07:06:40 +02:00
<sect2 id="jdbc-query-with-cursor">
2003-08-07 01:50:19 +02:00
<title>Getting results based on a cursor</title>
<para>By default the driver collects all the results for the
2003-09-20 22:12:05 +02:00
query at once. This can be inconvenient for large data sets so
2003-08-07 01:50:19 +02:00
the JDBC driver provides a means of basing
a <classname>ResultSet</classname> on a database cursor and
only fetching a small number of rows.</para>
<para>A small number of rows are cached on the
client side of the connection and when exhausted the next
block of rows is retrieved by repositioning the cursor.
</para>
<example>
<title>Setting fetch size to turn cursors on and off.</title>
<para>Changing code to cursor mode is as simple as setting the
fetch size of the <classname>Statement</classname> to the
appropriate size. Setting the fetch size back to 0 will cause
all rows to be cached (the default behaviour).
<programlisting>
Statement st = db.createStatement();
// Turn use of the cursor on.
st.setFetchSize(50);
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
while (rs.next()) {
System.out.print("a row was returned.");
}
rs.close();
// Turn the cursor off.
st.setFetchSize(0);
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
while (rs.next()) {
System.out.print("many rows were returned.");
}
rs.close();
// Close the statement.
st.close();
</programlisting>
</para>
2003-08-07 07:06:40 +02:00
</example>
</sect2>
2003-08-07 01:50:19 +02:00
1999-10-04 17:16:35 +02:00
<sect2>
2003-04-07 03:29:26 +02:00
<title>Using the <classname>Statement</classname> or <classname>PreparedStatement</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
2001-11-27 02:20:17 +01:00
<classname>Statement</classname> or
<classname>PreparedStatement</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
2001-11-27 02:20:17 +01:00
<classname>Statement</classname> or
<classname>PreparedStatement</classname> at a given time.
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>
2001-11-26 06:57:57 +01:00
<listitem>
<para>
When you are done using the <classname>Statement</classname>
2001-11-27 02:20:17 +01:00
or <classname>PreparedStatement</classname>
you should close it.
2001-11-26 06:57:57 +01:00
</para>
</listitem>
1999-10-04 17:16:35 +02:00
</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
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> driver will allow you to
2001-02-24 13:40:27 +01:00
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>
2001-11-29 06:35:51 +01:00
1999-10-04 17:16:35 +02:00
</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>
2003-04-07 03:29:26 +02:00
To change data (perform an <command>INSERT</command>,
<command>UPDATE</command>, or <command>DELETE</command>) you use
the <function>executeUpdate()</function> method. This method is
similar to the method <function>executeQuery()</function> used to
issue a <command>SELECT</command> statement, but it doesn't return
a <classname>ResultSet</classname>; instead it returns the number
of rows affected by the <command>INSERT</command>,
<command>UPDATE</command>, or <command>DELETE</command> statement.
<xref linkend="jdbc-delete-example"> illustrates the usage.
2001-11-26 06:57:57 +01:00
</para>
1998-10-25 02:27:44 +02:00
2001-11-27 02:20:17 +01:00
<example id="jdbc-delete-example">
2003-04-07 03:29:26 +02:00
<title>Deleting Rows in <acronym>JDBC</acronym></title>
2001-11-26 06:57:57 +01:00
<para>
2003-04-07 03:29:26 +02:00
This example will issue a simple <command>DELETE</command>
statement and print out the number of rows deleted.
2001-02-24 13:40:27 +01:00
<programlisting>
2001-11-26 06:57:57 +01:00
int foovalue = 500;
2003-04-07 03:29:26 +02:00
PreparedStatement st = db.prepareStatement("DELETE FROM mytable WHERE columnfoo = ?");
2001-11-26 06:57:57 +01:00
st.setInt(1, foovalue);
int rowsDeleted = st.executeUpdate();
System.out.println(rowsDeleted + " rows deleted");
st.close();
2001-02-24 13:40:27 +01:00
</programlisting>
1999-10-04 17:16:35 +02:00
</para>
2001-11-27 02:20:17 +01:00
</example>
1999-10-04 17:16:35 +02:00
</sect1>
2003-08-07 01:50:19 +02:00
<sect1 id="jdbc-callproc">
<title>Calling Stored Functions</title>
2003-11-01 02:56:29 +01:00
<para><productname>PostgreSQL's</productname> JDBC driver fully
2003-08-07 01:50:19 +02:00
supports calling <productname>PostgreSQL</productname> stored
functions.</para>
<example id="jdbc-call-function">
<title>Calling a built in stored function</title>
<para>This example shows how to call
a <productname>PostgreSQL</productname> built in
function, <command>upper</command>, which simply converts the
supplied string argument to uppercase.
<programlisting>
// Turn transactions off.
con.setAutoCommit(false);
// Procedure call.
CallableStatement upperProc = con.prepareCall("{ ? = call upper( ? ) }");
upperProc.registerOutParameter(1, Types.VARCHAR);
upperProc.setString(2, "lowercase to uppercase");
upperProc.execute();
String upperCased = upperProc.getString(1);
upperProc.close();
</programlisting>
</para>
</example>
<sect2>
<title>Using the <classname>CallableStatement</classname> Interface</title>
<para>
All the considerations that apply
for <classname>Statement</classname>
and <classname>PreparedStatement</classname> apply
for <classname>CallableStatement</classname> but in addition
you must also consider one extra restriction:
</para>
<itemizedlist>
<listitem>
<para>You can only call a stored function from within a
transaction.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Obtaining <classname>ResultSet</classname> from a stored function</title>
<para><productname>PostgreSQL's</productname> stored function
can return results by means of a <type>refcursor</type>
value. A <type>refcursor</type>.</para>
<para>As an extension to JDBC,
the <productname>PostgreSQL</productname> JDBC driver can
return <type>refcursor</type> values
as <classname>ResultSet</classname> values.</para>
<example id="get-refcursor-from-function-call">
2003-09-20 22:12:05 +02:00
<title>Getting <type>refcursor</type> values from a
2003-08-07 01:50:19 +02:00
function</title>
<para>When calling a function that returns
a <type>refcursor</type> you must cast the return type
2003-11-01 02:56:29 +01:00
of <function>getObject</function> to
2003-08-07 01:50:19 +02:00
a <classname>ResultSet</classname></para>
<programlisting>
// Turn transactions off.
con.setAutoCommit(false);
// Procedure call.
CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }");
proc.registerOutParameter(1, Types.Other);
proc.setInt(2, -1);
proc.execute();
ResultSet results = (ResultSet) proc.getObject(1);
while (results.next()) {
// do something with the results...
}
results.close();
proc.close();
</programlisting>
</example>
<para>It is also possible to treat the <type>refcursor</type>
return value as a distinct type in itself. The JDBC driver
provides
the <classname>org.postgresql.PGRefCursorResultSet</classname>
class for this purpose.</para>
<example>
<title>Treating <type>refcursor</type> as a distinct
type</title>
<programlisting>
con.setAutoCommit(false);
CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }");
proc.registerOutParameter(1, Types.Other);
proc.setInt(2, 0);
org.postgresql.PGRefCursorResultSet refcurs
= (PGRefCursorResultSet) con.getObject(1);
String cursorName = refcurs.getRefCursor();
proc.close();
</programlisting>
</example>
</sect2>
</sect1>
2001-11-26 06:57:57 +01:00
<sect1 id="jdbc-ddl">
<title>Creating and Modifying Database Objects</title>
<para>
To create, modify or drop a database object like a table or view
2003-04-07 03:29:26 +02:00
you use the <function>execute()</function> method. This method is
similar to the method <function>executeQuery()</function>, but it
doesn't return a result. <xref linkend="jdbc-drop-table-example">
illustrates the usage.
2001-11-26 06:57:57 +01:00
</para>
2001-11-27 02:20:17 +01:00
<example id="jdbc-drop-table-example">
2003-04-07 03:29:26 +02:00
<title>Dropping a Table in JDBC</title>
2001-11-26 06:57:57 +01:00
<para>
This example will drop a table.
<programlisting>
Statement st = db.createStatement();
2003-04-07 03:29:26 +02:00
st.execute("DROP TABLE mytable");
2001-11-26 06:57:57 +01:00
st.close();
</programlisting>
</para>
2001-11-27 02:20:17 +01:00
</example>
2001-11-26 06:57:57 +01:00
</sect1>
<sect1 id="jdbc-binary-data">
<title>Storing Binary Data</title>
2003-08-31 19:32:24 +02:00
<indexterm zone="jdbc-binary-data">
<primary>bytea</primary>
<secondary sortas="JDBC">in JDBC</secondary>
</indexterm>
<indexterm zone="jdbc-binary-data">
<primary>large object</primary>
<secondary sortas="JDBC">in JDBC</secondary>
</indexterm>
2001-11-26 06:57:57 +01:00
<para>
2003-12-14 00:59:07 +01:00
<productname>PostgreSQL</productname> provides two distinct ways to
2001-11-26 06:57:57 +01:00
store binary data. Binary data can be stored in a table using
2003-04-07 03:29:26 +02:00
the data type <type>bytea</type> or by using the Large Object
2001-11-26 06:57:57 +01:00
feature which stores the binary data in a separate table in a special
2003-04-07 03:29:26 +02:00
format and refers to that table by storing a value of type
<type>oid</type> in your table.
2001-11-26 06:57:57 +01:00
</para>
<para>
In order to determine which method is appropriate you
need to understand the limitations of each method. The
2002-01-20 23:19:57 +01:00
<type>bytea</type> data type is not well suited for storing very
2001-11-26 06:57:57 +01:00
large amounts of binary data. While a column of type
2002-09-21 20:32:54 +02:00
<type>bytea</type> can hold up to 1 GB of binary data, it would
2003-04-07 03:29:26 +02:00
require a huge amount of memory to
2001-11-26 06:57:57 +01:00
process such a large value. The Large Object method for
storing binary data is better suited to storing very large values,
but it has its own limitations. Specifically deleting a row
2003-04-07 03:29:26 +02:00
that contains a Large Object reference does not delete the Large Object.
2001-11-26 06:57:57 +01:00
Deleting the Large Object is a separate operation that needs to
be performed. Large Objects also have some security
2003-09-20 22:12:05 +02:00
issues since anyone connected to the database can view
2001-11-26 06:57:57 +01:00
and/or modify any Large Object, even if they don't have
2003-04-07 03:29:26 +02:00
permissions to view/update the row containing the Large Object reference.
2001-11-26 06:57:57 +01:00
</para>
<para>
2003-04-07 03:29:26 +02:00
Version 7.2 was the first release of the <acronym>JDBC</acronym> driver
2002-01-20 23:19:57 +01:00
that supports the <type>bytea</type> data type. The introduction of
2001-11-26 06:57:57 +01:00
this functionality in 7.2 has introduced a change in behavior
2003-04-07 03:29:26 +02:00
as compared to previous releases. Since 7.2, the methods
2001-11-26 06:57:57 +01:00
<function>getBytes()</function>, <function>setBytes()</function>,
<function>getBinaryStream()</function>, and
<function>setBinaryStream()</function> operate on
2003-04-07 03:29:26 +02:00
the <type>bytea</type> data type. In 7.1 and earlier, these methods operated
on the <type>oid</type> data type associated with Large Objects.
2001-11-26 06:57:57 +01:00
It is possible to revert the driver back to the old 7.1 behavior
2003-04-07 03:29:26 +02:00
by setting the property <literal>compatible</literal> on
the <classname>Connection</classname> object to the value
<literal>7.1</literal>.
2001-11-26 06:57:57 +01:00
</para>
1999-10-04 17:16:35 +02:00
2001-02-24 13:40:27 +01:00
<para>
2002-01-20 23:19:57 +01:00
To use the <type>bytea</type> data type you should simply use
2001-11-26 06:57:57 +01:00
the <function>getBytes()</function>, <function>setBytes()</function>,
<function>getBinaryStream()</function>, or
<function>setBinaryStream()</function> methods.
</para>
<para>
2003-12-14 00:59:07 +01:00
To use the Large Object functionality you can use either the
<classname>LargeObject</classname> class provided by the
<productname>PostgreSQL</> <acronym>JDBC</acronym> driver, or by
using the <function>getBLOB()</function> and
<function>setBLOB()</function> methods.
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
<important>
1999-10-04 17:16:35 +02:00
<para>
2003-04-07 03:29:26 +02:00
You must access Large Objects within an <acronym>SQL</acronym>
transaction block. You can start a transaction block by calling
<function>setAutoCommit(false)</function>.
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
2003-04-07 03:29:26 +02:00
<note>
<para>
In a future release of the
<acronym>JDBC</acronym> driver, the <function>getBLOB()</function>
2001-11-26 06:57:57 +01:00
and <function>setBLOB()</function> methods may no longer
2003-04-07 03:29:26 +02:00
interact with Large Objects and will instead work on the data type
<type>bytea</type>. So it is recommended that you
2001-11-26 20:07:11 +01:00
use the <classname>LargeObject</classname> <acronym>API</acronym>
2001-11-26 06:57:57 +01:00
if you intend to use Large Objects.
2003-04-07 03:29:26 +02:00
</para>
</note>
1999-10-04 17:16:35 +02:00
2003-04-07 03:29:26 +02:00
<para>
<xref linkend="jdbc-binary-data-example"> contains some examples on
2003-12-14 00:59:07 +01:00
how to process binary data using the <productname>PostgreSQL</>
<acronym>JDBC</> driver.
2003-04-07 03:29:26 +02:00
</para>
1999-10-04 17:16:35 +02:00
2001-11-26 06:57:57 +01:00
<example id="jdbc-binary-data-example">
2003-06-30 18:39:42 +02:00
<title>Processing Binary Data in <acronym>JDBC</></title>
1999-10-04 17:16:35 +02:00
2001-02-24 13:40:27 +01:00
<para>
2003-04-07 03:29:26 +02:00
For example, suppose you have a table containing the file names of
images and you also want to store the image in a <type>bytea</type>
2001-11-26 06:57:57 +01:00
column:
2001-02-24 13:40:27 +01:00
<programlisting>
2001-11-26 06:57:57 +01:00
CREATE TABLE images (imgname text, img bytea);
2001-02-24 13:40:27 +01:00
</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-11-26 06:57:57 +01:00
PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)");
2001-02-24 13:40:27 +01:00
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>
2001-11-26 06:57:57 +01:00
Here, <function>setBinaryStream()</function> transfers a set number
of bytes from a stream into the column of type <type>bytea</type>.
This also could have been done using the <function>setBytes()</function>
method if the contents of the image was already in a
<classname>byte[]</classname>.
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>
2003-04-07 03:29:26 +02:00
PreparedStatement ps = con.prepareStatement("SELECT img 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) {
2003-04-07 03:29:26 +02:00
while (rs.next()) {
2001-11-26 06:57:57 +01:00
byte[] imgBytes = rs.getBytes(1);
2003-04-07 03:29:26 +02:00
// use the data in some way here
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-11-27 02:20:17 +01:00
Here the binary data was retrieved as an
2001-11-26 06:57:57 +01:00
<classname>byte[]</classname>. You could have used a
<classname>InputStream</classname> object instead.
1999-10-04 17:16:35 +02:00
</para>
2001-11-26 06:57:57 +01:00
<para>
2002-01-20 23:19:57 +01:00
Alternatively you could be storing a very large file and want to use
2001-11-26 06:57:57 +01:00
the <classname>LargeObject</classname> <acronym>API</acronym> to
store the file:
<programlisting>
2003-04-07 03:29:26 +02:00
CREATE TABLE imageslo (imgname text, imgoid oid);
2001-11-26 06:57:57 +01:00
</programlisting>
</para>
<para>
To insert an image, you would use:
<programlisting>
2003-04-07 03:29:26 +02:00
// All LargeObject API calls must be within a transaction block
2001-11-26 06:57:57 +01:00
conn.setAutoCommit(false);
2001-11-27 02:20:17 +01:00
// Get the Large Object Manager to perform operations with
2002-11-11 08:31:28 +01:00
LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI();
2001-11-26 06:57:57 +01:00
2003-04-07 03:29:26 +02:00
// Create a new large object
2001-11-26 06:57:57 +01:00
int oid = lobj.create(LargeObjectManager.READ | LargeObjectManager.WRITE);
2003-04-07 03:29:26 +02:00
// Open the large object for writing
2001-11-26 06:57:57 +01:00
LargeObject obj = lobj.open(oid, LargeObjectManager.WRITE);
// Now open the file
File file = new File("myimage.gif");
FileInputStream fis = new FileInputStream(file);
2003-04-07 03:29:26 +02:00
// Copy the data from the file to the large object
2001-11-26 06:57:57 +01:00
byte buf[] = new byte[2048];
int s, tl = 0;
2003-04-07 03:29:26 +02:00
while ((s = fis.read(buf, 0, 2048)) > 0) {
obj.write(buf, 0, s);
tl += s;
2001-11-26 06:57:57 +01:00
}
// Close the large object
obj.close();
2003-04-07 03:29:26 +02:00
// Now insert the row into imageslo
PreparedStatement ps = conn.prepareStatement("INSERT INTO imageslo VALUES (?, ?)");
2001-11-26 06:57:57 +01:00
ps.setString(1, file.getName());
ps.setInt(2, oid);
ps.executeUpdate();
ps.close();
fis.close();
</programlisting>
2003-04-07 03:29:26 +02:00
</para>
2001-11-26 06:57:57 +01:00
<para>
Retrieving the image from the Large Object:
<programlisting>
2003-04-07 03:29:26 +02:00
// All LargeObject API calls must be within a transaction block
2001-11-26 06:57:57 +01:00
conn.setAutoCommit(false);
2001-11-27 02:20:17 +01:00
// Get the Large Object Manager to perform operations with
2002-11-11 08:31:28 +01:00
LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI();
2001-11-26 06:57:57 +01:00
2003-04-07 03:29:26 +02:00
PreparedStatement ps = con.prepareStatement("SELECT imgoid FROM imageslo WHERE imgname = ?");
2001-11-26 06:57:57 +01:00
ps.setString(1, "myimage.gif");
ResultSet rs = ps.executeQuery();
if (rs != null) {
2003-04-07 03:29:26 +02:00
while (rs.next()) {
// Open the large object for reading
int oid = rs.getInt(1);
LargeObject obj = lobj.open(oid, LargeObjectManager.READ);
// Read the data
byte buf[] = new byte[obj.size()];
obj.read(buf, 0, obj.size());
// Do something with the data read here
// Close the object
obj.close();
2001-11-26 06:57:57 +01:00
}
rs.close();
}
ps.close();
</programlisting>
</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">
2003-12-14 00:59:07 +01:00
<title><productname>PostgreSQL</productname> Extensions to the
2001-02-24 13:40:27 +01:00
<acronym>JDBC</acronym> <acronym>API</acronym></title>
1999-10-04 17:16:35 +02:00
2001-02-24 13:40:27 +01:00
<para>
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> is an extensible database
2003-11-01 02:56:29 +01:00
system. You can add your own functions to the server, which can
2001-02-24 13:40:27 +01:00
then be called from queries, or even add your own data types. As
2001-11-21 06:53:41 +01:00
these are facilities unique to <productname>PostgreSQL</productname>,
2001-02-24 13:40:27 +01:00
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
2002-11-11 08:31:28 +01:00
methods in the <classname>org.postgresql.PGConnection</classname>
2001-02-24 13:40:27 +01:00
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
2002-11-11 08:31:28 +01:00
Fastpath fp = ((org.postgresql.PGConnection)db).getFastpathAPI();
2001-02-24 13:40:27 +01:00
</programlisting>
</para>
1998-10-25 02:27:44 +02:00
2001-02-24 13:40:27 +01:00
<sect3>
2002-11-11 08:31:28 +01:00
<title>Class <classname>org.postgresql.PGConnection</classname></title>
1998-10-25 02:27:44 +02:00
2001-02-24 13:40:27 +01:00
<synopsis>
2002-11-11 08:31:28 +01:00
public class PGConnection
2001-02-24 13:40:27 +01:00
</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
2002-11-11 08:31:28 +01:00
<productname>PostgreSQL</productname>'s extensions.
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
<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>
2003-11-01 02:56:29 +01:00
This returns the fast-path <acronym>API</acronym> for the
2001-02-24 13:40:27 +01:00
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.*;
...
2002-11-11 08:31:28 +01:00
Fastpath fp = ((org.postgresql.PGConnection)myconn).getFastpathAPI();
2001-02-24 13:40:27 +01:00
</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>
2003-11-01 02:56:29 +01:00
<classname>Fastpath</> object allowing access to functions on the
<productname>PostgreSQL</productname> server.
2001-02-24 13:40:27 +01:00
</para>
</formalpara>
<formalpara>
<title>Throws:</title>
<para>
2003-11-01 02:56:29 +01:00
<classname>SQLException</> by <classname>Fastpath</> 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 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.*;
...
2002-11-11 08:31:28 +01:00
LargeObjectManager lo = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
2001-02-24 13:40:27 +01:00
</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
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname>'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
...
2002-11-11 08:31:28 +01:00
((org.postgresql.PGConnection)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
2003-11-01 02:56:29 +01:00
to execute a function on the database server. Most client code
2001-02-24 13:40:27 +01:00
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>
2002-11-11 08:31:28 +01:00
Fastpath fp = ((org.postgresql.PGConnection)conn).getFastpathAPI();
2001-02-24 13:40:27 +01:00
</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
2002-11-11 08:31:28 +01:00
<classname>org.postgresql.PGConnection</classname> is required, as
2001-02-24 13:40:27 +01:00
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
2003-11-01 02:56:29 +01:00
<function>fastpath()</function> methods to execute a server
2001-02-24 13:40:27 +01:00
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>
2003-11-01 02:56:29 +01:00
Send a function call to the <productname>PostgreSQL</productname> server.
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>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
2003-11-01 02:56:29 +01:00
<parameter>args</> - <classname>FastpathArguments</classname> to pass to fast-path call
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>
2003-11-01 02:56:29 +01:00
Send a function call to the <productname>PostgreSQL</productname> server by name.
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
<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
2003-11-01 02:56:29 +01:00
between versions of the server. For an example of how this
2001-02-24 13:40:27 +01:00
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
2003-11-01 02:56:29 +01:00
<parameter>args</> - <classname>FastpathArguments</classname> to pass to fast-path call
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,
2002-09-21 20:32:54 +02:00
rather than hard coding the OID. The OID for a function is not
2001-02-24 13:40:27 +01:00
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
2002-09-21 20:32:54 +02:00
contains the function name, Column 2 the OID. It reads the
2001-02-24 13:40:27 +01:00
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>
2001-11-21 06:53:41 +01:00
<productname>PostgreSQL</productname> 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>
2002-03-22 20:20:45 +01:00
Do not think that manually converting them to the OIDs 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>
2003-11-01 02:56:29 +01:00
Each fast-path call requires an array of arguments, the number and
2001-02-24 13:40:27 +01:00
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:
2001-11-21 06:53:41 +01:00
s - Box definition in <productname>PostgreSQL</productname> syntax
1998-10-25 02:27:44 +02:00
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:
2001-11-21 06:53:41 +01:00
s - definition of the circle in <productname>PostgreSQL</productname>'s syntax.
1998-10-25 02:27:44 +02:00
Throws: SQLException
on conversion failure
public PGcircle()
This constructor is used by the driver.
Methods
public void setValue(String s) throws SQLException
Parameters:
2001-11-21 06:53:41 +01:00
s - definition of the circle in <productname>PostgreSQL</productname>'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 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
2003-11-01 02:56:29 +01:00
not yet implemented in the server, but this class ensures that when
1998-10-25 02:27:44 +02:00
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-11-21 06:53:41 +01:00
s - definition of the line in <productname>PostgreSQL</productname>'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:
2001-11-21 06:53:41 +01:00
s - Definition of the line segment in <productname>PostgreSQL</productname>'s
1998-10-25 02:27:44 +02:00
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-11-21 06:53:41 +01:00
s - Definition of the line segment in <productname>PostgreSQL</productname>'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:
2001-11-21 06:53:41 +01:00
s - Definition of the line segment in <productname>PostgreSQL</productname>'s
1998-10-25 02:27:44 +02:00
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-11-21 06:53:41 +01:00
s - definition of the path in <productname>PostgreSQL</productname>'s syntax.
1998-10-25 02:27:44 +02:00
Throws: SQLException
on conversion failure
Methods
public void setValue(String s) throws SQLException
Parameters:
2001-11-21 06:53:41 +01:00
s - Definition of the path in <productname>PostgreSQL</productname>'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 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:
2001-11-21 06:53:41 +01:00
value - Definition of this point in <productname>PostgreSQL</productname>'s
1998-10-25 02:27:44 +02:00
syntax
public PGpoint()
Required by the driver
Methods
public void setValue(String s) throws SQLException
Parameters:
2001-11-21 06:53:41 +01:00
s - Definition of this point in <productname>PostgreSQL</productname>'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 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-11-21 06:53:41 +01:00
This implements the polygon data type within <productname>PostgreSQL</productname>.
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-11-21 06:53:41 +01:00
s - definition of the polygon in <productname>PostgreSQL</productname>'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:
2001-11-21 06:53:41 +01:00
s - Definition of the polygon in <productname>PostgreSQL</productname>'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 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
2001-11-21 06:53:41 +01:00
limited, and the <acronym>API</acronym> provided by <productname>PostgreSQL</productname> allows for random
2001-02-24 13:40:27 +01:00
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>
2001-11-26 06:57:57 +01:00
Normally, client code would use the methods in
<classname>BLOB</classname> to access large objects.
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
<para>
2001-11-26 06:57:57 +01:00
However, sometimes lower level access to Large Objects is
required, that is not supported by the <acronym>JDBC</acronym>
2001-02-24 13:40:27 +01:00
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>
2002-09-21 20:32:54 +02:00
<term><parameter>buf</></term>
2001-02-24 13:40:27 +01:00
<listitem>
<simpara>destination array</simpara>
</listitem>
</varlistentry>
<varlistentry>
2002-09-21 20:32:54 +02:00
<term><parameter>off</></term>
2001-02-24 13:40:27 +01:00
<listitem>
<simpara>offset within array</simpara>
</listitem>
</varlistentry>
<varlistentry>
2002-09-21 20:32:54 +02:00
<term><parameter>len</></term>
2001-02-24 13:40:27 +01:00
<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>
2002-09-21 20:32:54 +02:00
<term><parameter>buf</></term>
2001-02-24 13:40:27 +01:00
<listitem>
<simpara>destination array</simpara>
</listitem>
</varlistentry>
<varlistentry>
2002-09-21 20:32:54 +02:00
<term><parameter>off</></term>
2001-02-24 13:40:27 +01:00
<listitem>
<simpara>offset within array</simpara>
</listitem>
</varlistentry>
<varlistentry>
2002-09-21 20:32:54 +02:00
<term><parameter>len</></term>
2001-02-24 13:40:27 +01:00
<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>
2002-11-11 08:31:28 +01:00
This class can only be created by org.postgresql.PGConnection. To
2001-02-24 13:40:27 +01:00
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 ...
2002-11-11 08:31:28 +01:00
lobj = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
2001-02-24 13:40:27 +01:00
</programlisting>
</para>
1998-10-25 02:27:44 +02:00
2001-02-24 13:40:27 +01:00
<para>
2001-11-26 06:57:57 +01:00
Normally, client code would use the <classname>BLOB</classname>
methods to access large objects. However, sometimes
lower level access to Large Objects is required, that is not
2001-02-24 13:40:27 +01:00
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>
2002-09-21 20:32:54 +02:00
<term><literal>public static final int WRITE</></term>
2001-02-24 13:40:27 +01:00
<listitem>
<simpara>This mode indicates we want to write to an object.</simpara>
</listitem>
</varlistentry>
<varlistentry>
2002-09-21 20:32:54 +02:00
<term><literal>public static final int READ</></term>
2001-02-24 13:40:27 +01:00
<listitem>
<simpara>This mode indicates we want to read an object.</simpara>
</listitem>
</varlistentry>
<varlistentry>
2002-09-21 20:32:54 +02:00
<term><literal>public static final int READWRITE</></term>
2001-02-24 13:40:27 +01:00
<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
2002-09-21 20:32:54 +02:00
method assumes that <symbol>READ</> and
<symbol>WRITE</> access is required (the default).
2001-02-24 13:40:27 +01:00
</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.
2002-09-21 20:32:54 +02:00
It defaults to <symbol>READWRITE</> for the new object's attributes.
2001-02-24 13:40:27 +01:00
</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
</sect1>
2001-11-26 06:57:57 +01:00
1998-10-25 02:27:44 +02:00
2001-02-24 13:40:27 +01:00
<sect1 id="jdbc-thread">
2003-04-07 03:29:26 +02:00
<title>Using the Driver in a Multithreaded or a Servlet Environment</title>
1998-10-25 02:27:44 +02:00
2003-08-31 19:32:24 +02:00
<indexterm zone="jdbc-thread">
<primary>threads</primary>
<secondary sortas="JDBC">with JDBC</secondary>
</indexterm>
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
2003-04-07 03:29:26 +02:00
time --- otherwise a thread could send a query while another one is
receiving results, and this could cause severe confusion.
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
<para>
2003-04-07 03:29:26 +02:00
The <productname>PostgreSQL</productname> <acronym>JDBC</acronym> driver
2001-11-26 06:57:57 +01:00
is thread safe.
2001-02-24 13:40:27 +01:00
Consequently, if your application uses multiple threads then you do
2003-04-07 03:29:26 +02:00
not have to worry about complex algorithms to ensure that only one thread
uses the database at a time.
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
<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
2003-04-07 03:29:26 +02:00
current operation. If the operation is a regular <acronym>SQL</acronym>
2001-02-24 13:40:27 +01:00
statement, then the operation consists of sending the statement and
retrieving any <classname>ResultSet</classname> (in full). If it
2003-04-07 03:29:26 +02:00
is a fast-path call (e.g., reading a block
from a large object) then it consists of
sending and retrieving the respective data.
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
<para>
This is fine for applications and applets but can cause a
2003-04-07 03:29:26 +02:00
performance problem with servlets. If you have several threads
performing queries then each but one will pause.
To solve this, you are advised to create a pool of connections.
When ever a thread needs to use the database, it asks a manager
class for a <classname>Connection</classname> object. The manager
hands a free connection to the thread and marks it as busy. If a
free connection is not available, it opens one. Once the thread
has finished using the connection, it returns it to the manager
which can then either close it or add it to the pool. The manager
would also check that the connection is still alive and remove it
from the pool if it is dead. The down side of a connection pool is
that it increases the load on the server because a new session is
created for each <classname>Connection</classname> object. It is
up to you and your applications' requirements.
2001-02-24 13:40:27 +01:00
</para>
</sect1>
1998-10-25 02:27:44 +02:00
2002-10-01 06:09:13 +02:00
<sect1 id="jdbc-datasource">
2003-04-07 03:29:26 +02:00
<title>Connection Pools and Data Sources</title>
2002-10-01 06:09:13 +02:00
2003-08-31 19:32:24 +02:00
<indexterm zone="jdbc-datasource">
<primary>connection pool</primary>
<secondary sortas="JDBC">in JDBC</secondary>
</indexterm>
<indexterm zone="jdbc-datasource">
<primary>DataSource</primary>
</indexterm>
2003-04-07 03:29:26 +02:00
<para>
2003-06-30 18:39:42 +02:00
<acronym>JDBC</> 2 introduced standard connection pooling features in an
add-on <acronym>API</> known as the <acronym>JDBC</acronym> 2.0 Optional
2002-10-01 06:09:13 +02:00
Package (also known as the <acronym>JDBC</acronym> 2.0
Standard Extension). These features have since been included in
2003-06-30 18:39:42 +02:00
the core <acronym>JDBC</> 3 <acronym>API</>. The
<productname>PostgreSQL</productname> <acronym>JDBC</acronym> drivers
support these features if it has been compiled with
2002-10-01 06:09:13 +02:00
<acronym>JDK</acronym> 1.3.x in combination with the
<acronym>JDBC</acronym> 2.0 Optional Package
2003-04-07 03:29:26 +02:00
(<acronym>JDBC</acronym> 2), or with <acronym>JDK</acronym> 1.4 or higher
2002-10-01 06:09:13 +02:00
(<acronym>JDBC</acronym> 3). Most application servers include
the <acronym>JDBC</acronym> 2.0 Optional Package, but it is
also available separately from the Sun
<ulink
url="http://java.sun.com/products/jdbc/download.html#spec"><acronym>JDBC</acronym> download site</ulink>.
</para>
<sect2 id="jdbc-ds-intro">
2003-04-07 03:29:26 +02:00
<title>Overview</title>
<para>
2003-06-30 18:39:42 +02:00
The <acronym>JDBC</acronym> <acronym>API</> provides a client
2002-10-01 06:09:13 +02:00
and a server interface for connection pooling. The client
interface is <literal>javax.sql.DataSource</literal>,
which is what application code will typically use to
acquire a pooled database connection. The server interface
is <literal>javax.sql.ConnectionPoolDataSource</literal>,
which is how most application servers will interface with
the <productname>PostgreSQL</productname> <acronym>JDBC</acronym>
2003-04-07 03:29:26 +02:00
driver.
</para>
<para>
In an application server environment, the
2002-10-01 06:09:13 +02:00
application server configuration will typically refer to
the <productname>PostgreSQL</productname>
<literal>ConnectionPoolDataSource</literal> implementation,
while the application component code will typically acquire a
<literal>DataSource</literal> implementation provided by
the application server (not by
2003-04-07 03:29:26 +02:00
<productname>PostgreSQL</productname>).
</para>
<para>
For an environment without an application server,
2002-10-01 06:09:13 +02:00
<productname>PostgreSQL</productname> provides two implementations
of <literal>DataSource</literal> which an application can use
directly. One implementation performs connection pooling,
while the other simply provides access to database connections
through the <literal>DataSource</literal> interface without
any pooling. Again, these implementations should not be used
in an application server environment unless the application
server does not support the
2003-04-07 03:29:26 +02:00
<literal>ConnectionPoolDataSource</literal> interface.
</para>
2002-10-01 06:09:13 +02:00
</sect2>
<sect2 id="jdbc-ds-cpds">
2003-04-07 03:29:26 +02:00
<title>Application Servers: <classname>ConnectionPoolDataSource</classname></title>
<para>
<productname>PostgreSQL</productname> includes one implementation
of <classname>ConnectionPoolDataSource</classname> for
<acronym>JDBC</acronym> 2 and one for <acronym>JDBC</acronym> 3,
as shown in <xref linkend="jdbc-ds-cpds-imp-table">.
</para>
2002-10-01 06:09:13 +02:00
2003-04-07 03:29:26 +02:00
<table id="jdbc-ds-cpds-imp-table">
<title><classname>ConnectionPoolDataSource</classname> Implementations</title>
2002-10-01 06:09:13 +02:00
<tgroup cols=2>
<thead>
<row>
<entry><acronym>JDBC</acronym></entry>
<entry>Implementation Class</entry>
</row>
</thead>
<tbody>
<row>
<entry>2</entry>
<entry><literal>org.postgresql.jdbc2.optional.ConnectionPool</literal></entry>
</row>
<row>
<entry>3</entry>
<entry><literal>org.postgresql.jdbc3.Jdbc3ConnectionPool</literal></entry>
</row>
</tbody>
</tgroup>
2003-04-07 03:29:26 +02:00
</table>
2002-10-01 06:09:13 +02:00
2003-04-07 03:29:26 +02:00
<para>
Both implementations use the same configuration scheme.
<acronym>JDBC</acronym> requires that a
<classname>ConnectionPoolDataSource</classname> be configured via
JavaBean properties, shown in <xref linkend="jdbc-ds-cpds-props">,
so there are get and set methods for each of these properties.
</para>
<table id="jdbc-ds-cpds-props">
<title><classname>ConnectionPoolDataSource</> Configuration Properties</title>
2002-10-01 06:09:13 +02:00
<tgroup cols=3>
<thead>
<row>
<entry>Property</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>serverName</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry><productname>PostgreSQL</productname> database server
2003-04-07 03:29:26 +02:00
host name</entry>
2002-10-01 06:09:13 +02:00
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>databaseName</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry><productname>PostgreSQL</productname> database name</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>portNumber</literal></entry>
<entry><type>int</type></entry>
<entry>
TCP port which the <productname>PostgreSQL</productname>
database server is listening on (or 0 to use the default port)
</entry>
2002-10-01 06:09:13 +02:00
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>user</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry>User used to make database connections</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>password</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry>Password used to make database connections</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>defaultAutoCommit</literal></entry>
<entry><type>boolean</type></entry>
<entry>
Whether connections should have autocommit enabled or disabled
when they are supplied to the caller. The default is
<literal>false</literal>, to disable autocommit.
</entry>
2002-10-01 06:09:13 +02:00
</row>
</tbody>
</tgroup>
2003-04-07 03:29:26 +02:00
</table>
2002-10-01 06:09:13 +02:00
2003-04-07 03:29:26 +02:00
<para>
Many application servers use a properties-style syntax to
configure these properties, so it would not be unusual to enter
properties as a block of text. If the application server provides
a single area to enter all the properties, they might be listed
like this:
2002-10-01 06:09:13 +02:00
<programlisting>
serverName=localhost
databaseName=test
user=testuser
password=testpassword
</programlisting>
2003-04-07 03:29:26 +02:00
Or, if semicolons are used as separators instead of newlines, it
could look like this:
2002-10-01 06:09:13 +02:00
<programlisting>
serverName=localhost;databaseName=test;user=testuser;password=testpassword
</programlisting>
2003-04-07 03:29:26 +02:00
</para>
2002-10-01 06:09:13 +02:00
</sect2>
<sect2 id="jdbc-ds-ds">
2003-04-07 03:29:26 +02:00
<title>Applications: <classname>DataSource</></title>
2002-10-01 06:09:13 +02:00
<para><productname>PostgreSQL</productname> includes two
implementations of <literal>DataSource</literal>
2003-04-07 03:29:26 +02:00
for <acronym>JDBC</acronym> 2 and two for <acronym>JDBC</acronym>
3, as shown in <xref linkend="jdbc-ds-ds-imp">.
The pooling implementations do not actually close connections
2002-10-01 06:09:13 +02:00
when the client calls the <literal>close</literal> method, but
instead return the connections to a pool of available connections
for other clients to use. This avoids any overhead of repeatedly
opening and closing connections, and allows a large number of
clients to share a small number of database connections.</para>
2003-04-07 03:29:26 +02:00
<para>The pooling data-source implementation provided here is not
2002-10-01 06:09:13 +02:00
the most feature-rich in the world. Among other things,
connections are never closed until the pool itself is closed;
there is no way to shrink the pool. As well, connections
requested for users other than the default configured user are
not pooled. Many application servers
2003-04-07 03:29:26 +02:00
provide more advanced pooling features and use the
2002-10-01 06:09:13 +02:00
<literal>ConnectionPoolDataSource</literal> implementation
instead.</para>
2003-04-07 03:29:26 +02:00
<table id="jdbc-ds-ds-imp">
<title><classname>DataSource</> Implementations</title>
2002-10-01 06:09:13 +02:00
<tgroup cols=3>
<thead>
<row>
<entry><acronym>JDBC</acronym></entry>
<entry>Pooling</entry>
<entry>Implementation Class</entry>
</row>
</thead>
<tbody>
<row>
<entry>2</entry>
<entry>No</entry>
<entry><literal>org.postgresql.jdbc2.optional.SimpleDataSource</literal></entry>
</row>
<row>
<entry>2</entry>
<entry>Yes</entry>
<entry><literal>org.postgresql.jdbc2.optional.PoolingDataSource</literal></entry>
</row>
<row>
<entry>3</entry>
<entry>No</entry>
<entry><literal>org.postgresql.jdbc3.Jdbc3SimpleDataSource</literal></entry>
</row>
<row>
<entry>3</entry>
<entry>Yes</entry>
<entry><literal>org.postgresql.jdbc3.Jdbc3PoolingDataSource</literal></entry>
</row>
</tbody>
</tgroup>
</table>
2003-04-07 03:29:26 +02:00
<para>
All the implementations use the same configuration scheme.
2002-10-01 06:09:13 +02:00
<acronym>JDBC</acronym> requires that a
2003-04-07 03:29:26 +02:00
<literal>DataSource</literal> be configured via JavaBean
properties, shown in <xref linkend="jdbc-ds-ds-props">, so there
are get and set methods for each of these properties.
</para>
2002-10-01 06:09:13 +02:00
2003-04-07 03:29:26 +02:00
<table id="jdbc-ds-ds-props">
<title><classname>DataSource</> Configuration Properties</title>
2002-10-01 06:09:13 +02:00
<tgroup cols=3>
<thead>
<row>
<entry>Property</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>serverName</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry><productname>PostgreSQL</productname> database server
2003-04-07 03:29:26 +02:00
host name</entry>
2002-10-01 06:09:13 +02:00
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>databaseName</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry><productname>PostgreSQL</productname> database name</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>portNumber</literal></entry>
<entry><type>int</type></entry>
<entry>TCP port which the
2002-10-01 06:09:13 +02:00
<productname>PostgreSQL</productname> database server is
listening on (or 0 to use the default port)</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>user</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry>User used to make database connections</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>password</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry>Password used to make database connections</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The pooling implementations require some additional
2003-04-07 03:29:26 +02:00
configuration properties, which are shown in <xref linkend="jdbc-ds-ds-xprops">.</para>
2002-10-01 06:09:13 +02:00
2003-04-07 03:29:26 +02:00
<table id="jdbc-ds-ds-xprops">
<title>Additional Pooling <classname>DataSource</> Configuration Properties</title>
2002-10-01 06:09:13 +02:00
<tgroup cols=3>
<thead>
<row>
<entry>Property</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>dataSourceName</literal></entry>
<entry><type>String</type></entry>
2002-10-01 06:09:13 +02:00
<entry>Every pooling <literal>DataSource</literal> must have a
2003-04-07 03:29:26 +02:00
unique name.</entry>
2002-10-01 06:09:13 +02:00
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>initialConnections</literal></entry>
<entry><type>int</type></entry>
2002-10-01 06:09:13 +02:00
<entry>The number of database connections to be created
when the pool is initialized.</entry>
</row>
<row>
2003-04-07 03:29:26 +02:00
<entry><literal>maxConnections</literal></entry>
<entry><type>int</type></entry>
2002-10-01 06:09:13 +02:00
<entry>The maximum number of open database connections to
allow. When more connections are requested, the caller
will hang until a connection is returned to the pool.</entry>
</row>
</tbody>
</tgroup>
</table>
2003-04-07 03:29:26 +02:00
<para><xref linkend="jdbc-ds-example"> shows an example of typical application code using a
pooling <literal>DataSource</literal>.</para>
2002-10-01 06:09:13 +02:00
2003-04-07 03:29:26 +02:00
<example id="jdbc-ds-example">
2002-10-01 06:09:13 +02:00
<title><literal>DataSource</literal> Code Example</title>
<para>
2003-04-07 03:29:26 +02:00
Code to initialize a pooling <classname>DataSource</classname> might look like this:
2002-10-01 06:09:13 +02:00
<programlisting>
Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
source.setDataSourceName("A Data Source");
source.setServerName("localhost");
source.setDatabaseName("test");
source.setUser("testuser");
source.setPassword("testpassword");
source.setMaxConnections(10);
</programlisting>
Then code to use a connection from the pool might look
like this. Note that it is critical that the connections
2003-04-07 03:29:26 +02:00
are eventually closed. Else the pool will <quote>leak</> connections and
will eventually lock all the clients out.
2002-10-01 06:09:13 +02:00
<programlisting>
Connection con = null;
try {
con = source.getConnection();
// use connection
2003-04-07 03:29:26 +02:00
} catch (SQLException e) {
2002-10-01 06:09:13 +02:00
// log error
} finally {
2003-04-07 03:29:26 +02:00
if (con != null) {
try { con.close(); } catch (SQLException e) {}
2002-10-01 06:09:13 +02:00
}
}
</programlisting>
</para>
</example>
</sect2>
<sect2 id="jdbc-jndi">
2003-08-31 19:32:24 +02:00
<title>Data Sources and <acronym>JNDI</acronym></title>
<indexterm zone="jdbc-jndi">
<primary>JNDI</primary>
</indexterm>
2003-04-07 03:29:26 +02:00
<para>
All the <literal>ConnectionPoolDataSource</literal> and
2002-10-01 06:09:13 +02:00
<literal>DataSource</literal> implementations can be stored
2003-04-07 03:29:26 +02:00
in <acronym>JNDI</acronym>. In the case of the nonpooling
2002-10-01 06:09:13 +02:00
implementations, a new instance will be created every time the
object is retrieved from <acronym>JNDI</acronym>, with the
2003-04-07 03:29:26 +02:00
same settings as the instance that was stored. For the
2002-10-01 06:09:13 +02:00
pooling implementations, the same instance will be retrieved
2003-04-07 03:29:26 +02:00
as long as it is available (e.g., not a different
2002-10-01 06:09:13 +02:00
<acronym>JVM</acronym> retrieving the pool from
<acronym>JNDI</acronym>), or a new instance with the same
2003-04-07 03:29:26 +02:00
settings created otherwise.
</para>
<para>
In the application server environment, typically the
2002-10-01 06:09:13 +02:00
application server's <literal>DataSource</literal> instance
will be stored in <acronym>JNDI</acronym>, instead of the
<productname>PostgreSQL</productname>
<literal>ConnectionPoolDataSource</literal> implementation.
2003-04-07 03:29:26 +02:00
</para>
<para>
In an application environment, the application may store
2002-10-01 06:09:13 +02:00
the <literal>DataSource</literal> in <acronym>JNDI</acronym>
so that it doesn't have to make a reference to the
<literal>DataSource</literal> available to all application
2003-04-07 03:29:26 +02:00
components that may need to use it. An example of this is
shown in <xref linkend="jdbc-ds-jndi">.
</para>
2002-10-01 06:09:13 +02:00
<example id="jdbc-ds-jndi">
2003-04-07 03:29:26 +02:00
<title><classname>DataSource</classname> <acronym>JNDI</acronym> Code Example</title>
2002-10-01 06:09:13 +02:00
<para>
2003-04-07 03:29:26 +02:00
Application code to initialize a pooling <classname>DataSource</classname> and add
2002-10-01 06:09:13 +02:00
it to <acronym>JNDI</acronym> might look like this:
<programlisting>
Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
source.setDataSourceName("A Data Source");
source.setServerName("localhost");
source.setDatabaseName("test");
source.setUser("testuser");
source.setPassword("testpassword");
source.setMaxConnections(10);
new InitialContext().rebind("DataSource", source);
</programlisting>
Then code to use a connection from the pool might look
like this:
<programlisting>
Connection con = null;
try {
DataSource source = (DataSource)new InitialContext().lookup("DataSource");
con = source.getConnection();
// use connection
2003-04-07 03:29:26 +02:00
} catch (SQLException e) {
2002-10-01 06:09:13 +02:00
// log error
2003-04-07 03:29:26 +02:00
} catch (NamingException e) {
2002-10-01 06:09:13 +02:00
// DataSource wasn't found in JNDI
} finally {
2003-04-07 03:29:26 +02:00
if (con != null) {
try { con.close(); } catch (SQLException e) {}
2002-10-01 06:09:13 +02:00
}
}
</programlisting>
</para>
</example>
</sect2>
</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>
2003-04-07 03:29:26 +02:00
If you have not yet read it, you are advised you read the
2001-02-24 13:40:27 +01:00
<acronym>JDBC</acronym> <acronym>API</acronym> Documentation
2003-04-07 03:29:26 +02:00
(supplied with Sun's <acronym>JDK</acronym>) and the
2001-02-24 13:40:27 +01:00
<acronym>JDBC</acronym> Specification. Both are available from
<ulink
2003-04-07 03:29:26 +02:00
url="http://java.sun.com/products/jdbc/index.html"></ulink>.
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
<para>
<ulink
2003-04-07 03:29:26 +02:00
url="http://jdbc.postgresql.org"></ulink>
contains updated information not included in this chapter and
also offers precompiled drivers.
2001-02-24 13:40:27 +01:00
</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
-->