Applied doc patch for the jdbc docs submitted by Nic Ferrier for functionality

he supplied a few months ago, but didn't get around to docing until now.  And
he also added some doc for calling stored functions in general from jdbc that was missing.

 Modified Files:
 	sgml/jdbc.sgml
This commit is contained in:
Barry Lind 2003-08-06 23:50:19 +00:00
parent 3efb2af4b6
commit 1d1df53f82

View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.45 2003/06/30 16:39:42 barry Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.46 2003/08/06 23:50:19 barry Exp $
-->
<chapter id="jdbc">
@ -323,8 +323,9 @@ db.close();
a <classname>Statement</classname> or
<classname>PreparedStatement</classname>, you can use issue a
query. This will return a <classname>ResultSet</classname>
instance, which contains the entire result. <xref
linkend="jdbc-query-example"> illustrates this process.
instance, which contains the entire result (see <xref linkend="jdbc-query-with-cursor">
here for how to alter this behaviour).
<xref linkend="jdbc-query-example"> illustrates this process.
</para>
<example id="jdbc-query-example">
@ -364,6 +365,50 @@ st.close();
</para>
</example>
<sect2 id="query-with-cursor">
<title>Getting results based on a cursor</title>
<para>By default the driver collects all the results for the
query at once. This can be inconvieniant for large data sets so
the JDBC driver provides a means of basing
a <classname>ResultSet</classname> on a database cursor and
only fetching a small number of rows.</para>
<para>A small number of rows are cached on the
client side of the connection and when exhausted the next
block of rows is retrieved by repositioning the cursor.
</para>
<example>
<title>Setting fetch size to turn cursors on and off.</title>
<para>Changing code to cursor mode is as simple as setting the
fetch size of the <classname>Statement</classname> to the
appropriate size. Setting the fetch size back to 0 will cause
all rows to be cached (the default behaviour).
<programlisting>
Statement st = db.createStatement();
// Turn use of the cursor on.
st.setFetchSize(50);
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
while (rs.next()) {
System.out.print("a row was returned.");
}
rs.close();
// Turn the cursor off.
st.setFetchSize(0);
ResultSet rs = st.executeQuery("SELECT * FROM mytable");
while (rs.next()) {
System.out.print("many rows were returned.");
}
rs.close();
// Close the statement.
st.close();
</programlisting>
</para>
<sect2>
<title>Using the <classname>Statement</classname> or <classname>PreparedStatement</classname> Interface</title>
@ -494,6 +539,120 @@ st.close();
</example>
</sect1>
<sect1 id="jdbc-callproc">
<title>Calling Stored Functions</title>
<para><productname>PostgreSQL's</productname> jdbc driver fully
supports calling <productname>PostgreSQL</productname> stored
functions.</para>
<example id="jdbc-call-function">
<title>Calling a built in stored function</title>
<para>This example shows how to call
a <productname>PostgreSQL</productname> built in
function, <command>upper</command>, which simply converts the
supplied string argument to uppercase.
<programlisting>
// Turn transactions off.
con.setAutoCommit(false);
// Procedure call.
CallableStatement upperProc = con.prepareCall("{ ? = call upper( ? ) }");
upperProc.registerOutParameter(1, Types.VARCHAR);
upperProc.setString(2, "lowercase to uppercase");
upperProc.execute();
String upperCased = upperProc.getString(1);
upperProc.close();
</programlisting>
</para>
</example>
<sect2>
<title>Using the <classname>CallableStatement</classname> Interface</title>
<para>
All the considerations that apply
for <classname>Statement</classname>
and <classname>PreparedStatement</classname> apply
for <classname>CallableStatement</classname> but in addition
you must also consider one extra restriction:
</para>
<itemizedlist>
<listitem>
<para>You can only call a stored function from within a
transaction.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Obtaining <classname>ResultSet</classname> from a stored function</title>
<para><productname>PostgreSQL's</productname> stored function
can return results by means of a <type>refcursor</type>
value. A <type>refcursor</type>.</para>
<para>As an extension to JDBC,
the <productname>PostgreSQL</productname> JDBC driver can
return <type>refcursor</type> values
as <classname>ResultSet</classname> values.</para>
<example id="get-refcursor-from-function-call">
<title>Gettig <type>refcursor</type> values from a
function</title>
<para>When calling a function that returns
a <type>refcursor</type> you must cast the return type
of <methodname>getObject</methodname> to
a <classname>ResultSet</classname></para>
<programlisting>
// Turn transactions off.
con.setAutoCommit(false);
// Procedure call.
CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }");
proc.registerOutParameter(1, Types.Other);
proc.setInt(2, -1);
proc.execute();
ResultSet results = (ResultSet) proc.getObject(1);
while (results.next()) {
// do something with the results...
}
results.close();
proc.close();
</programlisting>
</example>
<para>It is also possible to treat the <type>refcursor</type>
return value as a distinct type in itself. The JDBC driver
provides
the <classname>org.postgresql.PGRefCursorResultSet</classname>
class for this purpose.</para>
<example>
<title>Treating <type>refcursor</type> as a distinct
type</title>
<programlisting>
con.setAutoCommit(false);
CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }");
proc.registerOutParameter(1, Types.Other);
proc.setInt(2, 0);
org.postgresql.PGRefCursorResultSet refcurs
= (PGRefCursorResultSet) con.getObject(1);
String cursorName = refcurs.getRefCursor();
proc.close();
</programlisting>
</example>
</sect2>
</sect1>
<sect1 id="jdbc-ddl">
<title>Creating and Modifying Database Objects</title>