From 1d1df53f82d6d6e61c855430e9e247bbe9209f03 Mon Sep 17 00:00:00 2001 From: Barry Lind Date: Wed, 6 Aug 2003 23:50:19 +0000 Subject: [PATCH] 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 --- doc/src/sgml/jdbc.sgml | 165 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 162 insertions(+), 3 deletions(-) diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml index 7170aedccf..6e70134574 100644 --- a/doc/src/sgml/jdbc.sgml +++ b/doc/src/sgml/jdbc.sgml @@ -1,5 +1,5 @@ @@ -323,8 +323,9 @@ db.close(); a Statement or PreparedStatement, you can use issue a query. This will return a ResultSet - instance, which contains the entire result. illustrates this process. + instance, which contains the entire result (see + here for how to alter this behaviour). + illustrates this process. @@ -364,6 +365,50 @@ st.close(); + + Getting results based on a cursor + + 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 ResultSet on a database cursor and + only fetching a small number of rows. + + 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. + + + + Setting fetch size to turn cursors on and off. + + Changing code to cursor mode is as simple as setting the + fetch size of the Statement to the + appropriate size. Setting the fetch size back to 0 will cause + all rows to be cached (the default behaviour). + + +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(); + + + + Using the <classname>Statement</classname> or <classname>PreparedStatement</classname> Interface @@ -494,6 +539,120 @@ st.close(); + + + Calling Stored Functions + + PostgreSQL's jdbc driver fully + supports calling PostgreSQL stored + functions. + + + Calling a built in stored function + + This example shows how to call + a PostgreSQL built in + function, upper, which simply converts the + supplied string argument to uppercase. + + +// 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(); + + + + + + Using the <classname>CallableStatement</classname> Interface + + + All the considerations that apply + for Statement + and PreparedStatement apply + for CallableStatement but in addition + you must also consider one extra restriction: + + + + + You can only call a stored function from within a + transaction. + + + + + + + Obtaining <classname>ResultSet</classname> from a stored function + + PostgreSQL's stored function + can return results by means of a refcursor + value. A refcursor. + + As an extension to JDBC, + the PostgreSQL JDBC driver can + return refcursor values + as ResultSet values. + + + Gettig <type>refcursor</type> values from a + function + + When calling a function that returns + a refcursor you must cast the return type + of getObject to + a ResultSet + + +// 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(); + + + + It is also possible to treat the refcursor + return value as a distinct type in itself. The JDBC driver + provides + the org.postgresql.PGRefCursorResultSet + class for this purpose. + + + Treating <type>refcursor</type> as a distinct + type + + +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(); + + + + + + + Creating and Modifying Database Objects