database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-27 12:41:57 +03:00
Code Activity

Add mention of transactions and large objects.

Browse Source 
Still need the code updated for LO examples.
This commit is contained in:
Thomas G. Lockhart
1999-10-04 15:16:35 +00:00
parent 0655b1500f
commit ee8d39a852
1 changed files with 449 additions and 404 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
doc/src/sgml/jdbc.sgml
View File

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