svn commit: r542150 - in /db/derby/docs/trunk/src/ref: crefjavstateautogen.dita rrefjdbcjavasqlconnection30.dita rrefjdbcjavasqlstatement30.dita

[my...@apache.org]

Author: myrnavl
Date: Mon May 28 01:32:13 2007
New Revision: 542150

URL: http://svn.apache.org/viewvc?view=rev&rev=542150
Log:
DERBY-2654: Document newly-supported (in embedded mode) JDBC methods for autogenerated keys. 
Patch contributed by Kim Haase.


Modified:
    db/derby/docs/trunk/src/ref/crefjavstateautogen.dita
    db/derby/docs/trunk/src/ref/rrefjdbcjavasqlconnection30.dita
    db/derby/docs/trunk/src/ref/rrefjdbcjavasqlstatement30.dita

Modified: db/derby/docs/trunk/src/ref/crefjavstateautogen.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/crefjavstateautogen.dita?view=diff&rev=542150&r1=542149&r2=542150
==============================================================================
--- db/derby/docs/trunk/src/ref/crefjavstateautogen.dita (original)
+++ db/derby/docs/trunk/src/ref/crefjavstateautogen.dita Mon May 28 01:32:13 2007
@@ -23,7 +23,6 @@
 <keywords><indexterm>autogenerated keys</indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p></p>
 <p>JDBC 3.0's autogenerated keys feature provides a way to retrieve values
 from columns that are part of an index or have a default value assigned. <ph
 conref="../conrefs.dita#prod/productshortname"></ph> supports the autoincrement
@@ -32,17 +31,62 @@
 be called to retrieve the value of such a column. This method returns a <i>ResultSet</i> object
 with a column for the automatically generated key. Calling <i>ResultSet.getMetaData</i> on
 the <i>ResultSet</i> object returned by <i>getGeneratedKeys</i> produces a <i>ResultSetMetaData</i> object that is similar to that returned by <xref href="rrefidentityvallocal.dita#rrefidentityvallocal">IDENTITY_VAL_LOCAL</xref>.
-A flag indicating that any auto-generated columns should be returned is passed
-to the methods <i>execute</i>, <i>executeUpdate</i>, or <i>prepareStatement</i> when
-the statement is executed or prepared.</p>
-<p>Here's an example that returns a ResultSet with values for auto-generated
-columns in TABLE1:   <codeblock expanse="column"><b>Statement stmt = conn.createStatement();
-int rows = stmt.executeUpdate("INSERT INTO TABLE1 (C11, C12) VALUES (1,1)",
-  Statement.RETURN_GENERATED_KEYS);
-ResultSet rs = stmt.getGeneratedKeys();</b></codeblock></p>
-<p>To use Autogenerated Keys in INSERT statements, pass the <codeph>Statement.RETURN_GENERATED_KEYS</codeph> flag
-to the <i>execute</i> or <i>executeUpdate</i> method. <ph
-conref="../conrefs.dita#prod/productshortname"></ph> does not support passing column names or column indexes to the <i>execute</i>, <i>executeUpdate</i>, or <i>prepareStatement</i> methods.</p>
+</p><p>
+Users can indicate that auto-generated columns should be made available for 
+retrieval by passing one of the following values as a second argument to the 
+<i>Connection.prepareStatement</i>, <i>Statement.execute</i>, or 
+<i>Statement.executeUpdate</i> methods:</p>
+<ul>
+<li>A constant indicating that auto-generated keys should be made available. 
+The specific constant to use is 
+<codeph>Statement.RETURN_GENERATED_KEYS</codeph>.
+</li>
+<li>An array of the names of the columns in the inserted row that should be 
+made available.  If any column name in the array does <i>not</i> designate an 
+auto-increment column, Derby will throw an error.
+</li>
+<li>An array of the positions of the columns in the inserted row that should be 
+made available. If any column position in the array does <i>not</i> correlate 
+to an auto-increment column, Derby will throw an error.
+</li>
+</ul>
+<section><title>Example</title>
+<p>Assume that we have a table TABLE1 defined as follows:</p>
+<codeblock>CREATE TABLE TABLE1 (C11 int, C12 int GENERATED ALWAYS AS IDENTITY)
+</codeblock>
+<p>The following three code fragments will all do the same thing: that is, they 
+will create a <i>ResultSet</i> that contains the value of <codeph>C12</codeph> 
+that is inserted into TABLE1.</p>
+<p>Code fragment 1:</p>
+<codeblock>
+Statement stmt = conn.createStatement(); 
+stmt.execute(
+    "INSERT INTO TABLE1 (C11) VALUES (1)",
+    Statement.RETURN_GENERATED_KEY);
+ResultSet rs = stmt.getGeneratedKeys();
+</codeblock>
+<p>Code fragment 2:</p>
+<codeblock>
+Statement stmt = conn.createStatement(); 
+String [] colNames = new String [] { "C12" };
+stmt.execute(
+    "INSERT INTO TABLE1 (C11) VALUES (1)",
+    colNames);
+ResultSet rs = stmt.getGeneratedKeys();
+</codeblock>
+<p>Code fragment 3:</p>
+<codeblock>
+Statement stmt = conn.createStatement(); 
+int [] colIndexes = new int [] { 2 };
+stmt.execute(
+    "INSERT INTO TABLE1 (C11) VALUES (1)",
+    colIndexes);
+ResultSet rs = stmt.getGeneratedKeys();
+</codeblock>
+<p>If there is no indication that auto-generated columns should be made 
+available for retrieval, a call to <i>Statement.getGeneratedKeys</i> will 
+return a null <i>ResultSet</i>.</p>
+</section>
 </conbody>
 </concept>
 

Modified: db/derby/docs/trunk/src/ref/rrefjdbcjavasqlconnection30.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbcjavasqlconnection30.dita?view=diff&rev=542150&r1=542149&r2=542150
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbcjavasqlconnection30.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbcjavasqlconnection30.dita Mon May 28 01:32:13 2007
@@ -60,9 +60,35 @@
 <entry colname="3">Undoes all changes made after the given Savepoint object
 was set.</entry>
 </row>
+<row>
+<entry colname="1"><i>PreparedStatement</i></entry>
+<entry colname="2"><i>prepareStatement(String sql, int autoGeneratedKeys)</i></entry>
+<entry colname="3"><i>autoGeneratedKeys</i> argument is ignored unless 
+<i>sql</i> is an INSERT statement.</entry>
+</row>
+<row>
+<entry colname="1"><i>PreparedStatement</i></entry>
+<entry colname="2"><i>prepareStatement(String sql, int [] columnIndexes)</i></entry>
+<entry colname="3">Column indexes are ignored unless <i>sql</i> is an INSERT 
+statement. Every column index in the array must correlate to an 
+<xref href="rrefsqlj37836.dita#rrefsqlj37836">auto-increment</xref>
+column within the target table of the INSERT.</entry>
+</row>
+<row>
+<entry colname="1"><i>PreparedStatement</i></entry>
+<entry colname="2"><i>prepareStatement(String sql, String [] columnNames)</i></entry>
+<entry colname="3">Column names are ignored unless <i>sql</i> is an INSERT 
+statement.  Every column name in the array must designate an 
+<xref href="rrefsqlj37836.dita#rrefsqlj37836">auto-increment</xref>
+column within the target table of the INSERT.</entry>
+</row>
 </tbody>
 </tgroup>
-</table></p></section>
+</table></p>
+<ul>
+<li><b><xref href="crefjavstateautogen.dita#crefjavstateautogen"></xref></b></li>
+</ul>
+</section>
 </refbody>
 </reference>
 

Modified: db/derby/docs/trunk/src/ref/rrefjdbcjavasqlstatement30.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbcjavasqlstatement30.dita?view=diff&rev=542150&r1=542149&r2=542150
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbcjavasqlstatement30.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbcjavasqlstatement30.dita Mon May 28 01:32:13 2007
@@ -36,7 +36,54 @@
 <row>
 <entry colname="1"><i>ResultSet</i></entry>
 <entry colname="2"><i>getGeneratedKeys()</i></entry>
-<entry colname="3"></entry>
+<entry colname="3">If the user has indicated that auto-generated keys 
+should be made available, this method returns the same results as a call to the 
+<xref href="rrefidentityvallocal.dita#rrefidentityvallocal">IDENTITY_VAL_LOCAL</xref>
+function. Otherwise this method returns null.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>execute(String sql, int autoGeneratedKeys)</i></entry>
+<entry colname="3"><i>autoGeneratedKeys</i> argument is ignored unless 
+<i>sql</i> is an INSERT statement.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>execute(String sql, int [] columnIndexes)</i></entry>
+<entry colname="3">Column indexes are ignored unless <i>sql</i> is an INSERT 
+statement. Every column index in the array must correlate to an 
+<xref href="rrefsqlj37836.dita#rrefsqlj37836">auto-increment</xref>
+column within the target table of the INSERT.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>execute(String sql, String [] columnNames)</i></entry>
+<entry colname="3">Column names are ignored unless <i>sql</i> is an INSERT 
+statement. Every column name in the array must designate an 
+<xref href="rrefsqlj37836.dita#rrefsqlj37836">auto-increment</xref>
+column within the target table of the INSERT.</entry>
+</row>
+<row>
+<entry colname="1"><i>int</i></entry>
+<entry colname="2"><i>executeUpdate(String sql, int autoGeneratedKeys)</i></entry>
+<entry colname="3"><i>autoGeneratedKeys</i> argument is ignored unless 
+<i>sql</i> is an INSERT statement.</entry>
+</row>
+<row>
+<entry colname="1"><i>int</i></entry>
+<entry colname="2"><i>executeUpdate(String sql, int [] columnIndexes)</i></entry>
+<entry colname="3">Column indexes are ignored unless <i>sql</i> is an INSERT 
+statement. Every column index in the array must correlate to an 
+<xref href="rrefsqlj37836.dita#rrefsqlj37836">auto-increment</xref>
+column within the target table of the INSERT.</entry>
+</row>
+<row>
+<entry colname="1"><i>int</i></entry>
+<entry colname="2"><i>executeUpdate(String sql, String [] columnNames)</i></entry>
+<entry colname="3">Column names are ignored unless <i>sql</i> is an INSERT 
+statement. Every column name in the array must designate an 
+<xref href="rrefsqlj37836.dita#rrefsqlj37836">auto-increment</xref>
+column within the target table of the INSERT.</entry>
 </row>
 </tbody>
 </tgroup>