Add mention of transactions and large objects.
Still need the code updated for LO examples.
This commit is contained in:
parent
0655b1500f
commit
ee8d39a852
|
@ -1,5 +1,5 @@
|
||||||
<Chapter Id="jdbc">
|
<chapter id="jdbc">
|
||||||
<Title>JDBC Interface</Title>
|
<title>JDBC Interface</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<note>
|
<note>
|
||||||
|
@ -16,9 +16,11 @@ author of the <acronym>JDBC</acronym> driver.
|
||||||
It provides a standard set of
|
It provides a standard set of
|
||||||
interfaces to <acronym>SQL</acronym>-compliant databases.
|
interfaces to <acronym>SQL</acronym>-compliant databases.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<application>Postgres</application> provides
|
<application>Postgres</application> provides
|
||||||
a type 4 <acronym>JDBC</acronym> Driver. Type 4 indicates that the driver
|
a <firstterm>type 4</firstterm> <acronym>JDBC</acronym> Driver.
|
||||||
|
Type 4 indicates that the driver
|
||||||
is written in Pure Java, and communicates in the database's own network
|
is written in Pure Java, and communicates in the database's own network
|
||||||
protocol. Because of this, the driver is platform independent. Once compiled,
|
protocol. Because of this, the driver is platform independent. Once compiled,
|
||||||
the driver can be used on any platform.
|
the driver can be used on any platform.
|
||||||
|
@ -63,11 +65,12 @@ The <filename>Makefile</filename> will generate the jar archive.
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To use the driver, the jar archive postgresql.jar needs to be included in
|
To use the driver, the jar archive postgresql.jar needs to be included in
|
||||||
the CLASSPATH.
|
the <envar>CLASSPATH</envar>.
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Example:
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<sect3>
|
||||||
|
<title>Example</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
I have an application that uses the <acronym>JDBC</acronym> driver to access a large database
|
I have an application that uses the <acronym>JDBC</acronym> driver to access a large database
|
||||||
containing astronomical objects. I have the application and the jdbc driver
|
containing astronomical objects. I have the application and the jdbc driver
|
||||||
|
@ -76,15 +79,17 @@ installed in the /usr/local/lib directory, and the java jdk installed in /usr/lo
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To run the application, I would use:
|
To run the application, I would use:
|
||||||
</para>
|
|
||||||
<para>
|
<programlisting>
|
||||||
export CLASSPATH = \
|
export CLASSPATH = /usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
|
||||||
/usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
|
|
||||||
java uk.org.retep.finder.Main
|
java uk.org.retep.finder.Main
|
||||||
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Loading the driver is covered later on in this chapter.
|
Loading the driver is covered later on in this chapter.
|
||||||
</para>
|
</para>
|
||||||
|
</sect3>
|
||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
@ -95,16 +100,17 @@ Loading the driver is covered later on in this chapter.
|
||||||
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
|
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
|
||||||
must be running with the -i flag.
|
must be running with the -i flag.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA
|
Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA
|
||||||
directory. In a default installation, this file permits access only by UNIX
|
directory. In a default installation, this file permits access only by Unix
|
||||||
domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
|
domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
|
||||||
to add something like:
|
to add something like:
|
||||||
</para>
|
|
||||||
<para>
|
<programlisting>
|
||||||
host all 127.0.0.1 255.255.255.255 password
|
host all 127.0.0.1 255.255.255.255 password
|
||||||
</para>
|
</programlisting>
|
||||||
<para>
|
|
||||||
Here access to all databases are possible from the local machine
|
Here access to all databases are possible from the local machine
|
||||||
with <acronym>JDBC</acronym>.
|
with <acronym>JDBC</acronym>.
|
||||||
</para>
|
</para>
|
||||||
|
@ -123,8 +129,6 @@ This section is not intended as a complete guide to
|
||||||
<acronym>JDBC</acronym> programming, but
|
<acronym>JDBC</acronym> programming, but
|
||||||
should help to get you started. For more information refer to the standard
|
should help to get you started. For more information refer to the standard
|
||||||
<acronym>JDBC</acronym> <acronym>API</acronym> documentation.
|
<acronym>JDBC</acronym> <acronym>API</acronym> documentation.
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Also, take a look at the examples included with the source. The basic
|
Also, take a look at the examples included with the source. The basic
|
||||||
example is used here.
|
example is used here.
|
||||||
</para>
|
</para>
|
||||||
|
@ -160,7 +164,8 @@ are two methods available, and it depends on your code to the best one to use.
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In the first method, your code implicitly loads the driver using the
|
In the first method, your code implicitly loads the driver using the
|
||||||
Class.forName() method. For <application>Postgres</application>, you would use:
|
<function>Class.forName()</function> method.
|
||||||
|
For <application>Postgres</application>, you would use:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
Class.forName("postgresql.Driver");
|
Class.forName("postgresql.Driver");
|
||||||
|
@ -172,7 +177,7 @@ register itself with <acronym>JDBC</acronym>.
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Note: The <function>forName()</function> method
|
Note: The <function>forName()</function> method
|
||||||
can throw a ClassNotFoundException, so you will
|
can throw a <literal>ClassNotFoundException</literal>, so you will
|
||||||
need to catch it if the driver is not available.
|
need to catch it if the driver is not available.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -185,21 +190,16 @@ don't use our extensions, then the second method is advisable.
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The second method passes the driver as a parameter to the JVM as it starts,
|
The second method passes the driver as a parameter to the JVM as it starts,
|
||||||
using the -D argument.
|
using the -D argument. Example:
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Example:
|
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
% java -Djdbc.drivers=postgresql.Driver example.ImageViewer
|
% java -Djdbc.drivers=postgresql.Driver example.ImageViewer
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
In this example, the JVM will attempt to load the driver as part of it's
|
In this example, the JVM will attempt to load the driver as part of it's
|
||||||
initialisation. Once done, the ImageViewer is started.
|
initialisation. Once done, the ImageViewer is started.
|
||||||
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Now, this method is the better one to use because it allows your code to
|
Now, this method is the better one to use because it allows your code to
|
||||||
be used with other databases, without recompiling the code. The only thing
|
be used with other databases, without recompiling the code. The only thing
|
||||||
|
@ -233,16 +233,15 @@ jdbc:postgresql:<replaceable class="parameter">database</replaceable>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
|
jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>>/<replaceable class="parameter">database</replaceable>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
|
jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>><replaceable class="parameter">">po</replaceable>e>/<replaceable class="parameter">database</replaceable>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
|
||||||
where:
|
where:
|
||||||
|
@ -281,7 +280,6 @@ The database name.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -289,9 +287,10 @@ The database name.
|
||||||
To connect, you need to get a Connection instance from
|
To connect, you need to get a Connection instance from
|
||||||
<acronym>JDBC</acronym>. To do this,
|
<acronym>JDBC</acronym>. To do this,
|
||||||
you would use the DriverManager.getConnection() method:
|
you would use the DriverManager.getConnection() method:
|
||||||
</para>
|
|
||||||
<para>
|
<programlisting>
|
||||||
Connection db = DriverManager.getConnection(url,user,pwd);
|
Connection db = DriverManager.getConnection(url,user,pwd);
|
||||||
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
@ -354,15 +353,17 @@ there is a result, but more importantly, it prepares the row for processing.
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest
|
Under the <acronym>JDBC</acronym> spec, you should access a
|
||||||
to stick to this rule, although at the current time, the <application>Postgres</application> driver
|
field only once. It's safest to stick to this rule, although
|
||||||
|
at the current time, the <application>Postgres</application> driver
|
||||||
will allow you to access a field as many times as you want.
|
will allow you to access a field as many times as you want.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
You must close a ResultSet by calling <function>close()</function> once you have finished with it.
|
You must close a ResultSet by calling
|
||||||
|
<function>close()</function> once you have finished with it.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
|
@ -397,7 +398,7 @@ st.close();
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To perform an update (or any other SQL statement that does not return a
|
To perform an update (or any other SQL statement that does not return a
|
||||||
result), you simply use the executeUpdate() method:
|
result), you simply use the <function>executeUpdate()</function> method:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
st.executeUpdate("create table basic (a int2, b int2)");
|
st.executeUpdate("create table basic (a int2, b int2)");
|
||||||
|
@ -424,16 +425,39 @@ db.close();
|
||||||
In <application>Postgres</application>,
|
In <application>Postgres</application>,
|
||||||
large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
|
large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
|
||||||
the database that cannot be stored in a normal SQL table. They are stored as a
|
the database that cannot be stored in a normal SQL table. They are stored as a
|
||||||
Table/Index pair, and are refered to from your own tables, by an OID value.
|
Table/Index pair, and are referred to from your own tables by an OID value.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Now, there are you methods of using Large Objects. The first is the
|
<important>
|
||||||
standard <acronym>JDBC</acronym> way, and is documented here. The other, uses our own extension
|
<para>
|
||||||
to the api, which presents the libpq large object <acronym>API</acronym> to Java, providing even
|
For <productname>Postgres</productname>, you must access large
|
||||||
|
objects within an SQL transaction. Although this has always been
|
||||||
|
true in principle, it was not strictly enforced until the
|
||||||
|
release of v6.5. You would open a transaction by using the
|
||||||
|
<function>setAutoCommit()</function> method with an input
|
||||||
|
parameter of <literal>false</literal>:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
Connection mycon;
|
||||||
|
...
|
||||||
|
mycon.setAutoCommit(false);
|
||||||
|
... now use Large Objects
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</important>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Now, there are two methods of using Large Objects. The first is the
|
||||||
|
standard <acronym>JDBC</acronym> way, and is documented here. The
|
||||||
|
other, uses our own extension
|
||||||
|
to the api, which presents the libpq large object
|
||||||
|
<acronym>API</acronym> to Java, providing even
|
||||||
better access to large objects than the standard. Internally, the driver uses
|
better access to large objects than the standard. Internally, the driver uses
|
||||||
the extension to provide large object support.
|
the extension to provide large object support.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
|
In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
|
||||||
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
|
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
|
||||||
|
@ -501,7 +525,8 @@ InputStream returned is closed when ResultSet.next() or ResultSet.close() is cal
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>
|
<title><application>Postgres</application> Extensions to the
|
||||||
|
<acronym>JDBC</acronym> <acronym>API</acronym></title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<application>Postgres</application> is an extensible database system.
|
<application>Postgres</application> is an extensible database system.
|
||||||
|
@ -509,6 +534,7 @@ You can add your own functions
|
||||||
to the backend, which can then be called from queries, or even add your own
|
to the backend, which can then be called from queries, or even add your own
|
||||||
data types.
|
data types.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Now, as these are facilities unique to us, we support them from Java, with
|
Now, as these are facilities unique to us, we support them from Java, with
|
||||||
a set of extension <acronym>API</acronym>'s. Some features within
|
a set of extension <acronym>API</acronym>'s. Some features within
|
||||||
|
@ -2241,7 +2267,8 @@ java.lang.Object
|
||||||
public class PGobject extends Object implements Serializable,
|
public class PGobject extends Object implements Serializable,
|
||||||
Cloneable
|
Cloneable
|
||||||
|
|
||||||
This class is used to describe data types that are unknown by <acronym>JDBC</acronym>
|
This class is used to describe data types that are unknown by
|
||||||
|
<acronym>JDBC</acronym>
|
||||||
Standard.
|
Standard.
|
||||||
A call to postgresql.Connection permits a class that extends this
|
A call to postgresql.Connection permits a class that extends this
|
||||||
class to be associated with a named type. This is how the
|
class to be associated with a named type. This is how the
|
||||||
|
@ -2550,7 +2577,8 @@ while another one is receiving results, and this would be a bad thing
|
||||||
for the database engine.
|
for the database engine.
|
||||||
|
|
||||||
PostgreSQL 6.4, brings thread safety to the entire driver. Standard
|
PostgreSQL 6.4, brings thread safety to the entire driver. Standard
|
||||||
<acronym>JDBC</acronym> was thread safe in 6.3.x, but the Fastpath <acronym>API</acronym> wasn't.
|
<acronym>JDBC</acronym> was thread safe in 6.3.x, but the Fastpath
|
||||||
|
<acronym>API</acronym> wasn't.
|
||||||
|
|
||||||
So, if your application uses multiple threads (which most decent ones
|
So, if your application uses multiple threads (which most decent ones
|
||||||
would), then you don't have to worry about complex schemes to ensure
|
would), then you don't have to worry about complex schemes to ensure
|
||||||
|
@ -2614,3 +2642,20 @@ document, and also includes precompiled drivers for v6.4, and earlier.
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
<!-- Keep this comment at the end of the file
|
||||||
|
Local variables:
|
||||||
|
mode: sgml
|
||||||
|
sgml-omittag:nil
|
||||||
|
sgml-shorttag:t
|
||||||
|
sgml-minimize-attributes:nil
|
||||||
|
sgml-always-quote-attributes:t
|
||||||
|
sgml-indent-step:1
|
||||||
|
sgml-indent-data:t
|
||||||
|
sgml-parent-document:nil
|
||||||
|
sgml-default-dtd-file:"./reference.ced"
|
||||||
|
sgml-exposed-tags:nil
|
||||||
|
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
|
||||||
|
sgml-local-ecat-files:nil
|
||||||
|
End:
|
||||||
|
--></book>
|
||||||
|
|
Loading…
Reference in New Issue