You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by an...@apache.org on 2006/06/13 13:57:08 UTC
svn commit: r413877 - in /db/derby/docs/trunk/src: adminguide/ devguide/
ref/ tools/ tuning/
Author: andreask
Date: Tue Jun 13 04:57:07 2006
New Revision: 413877
URL: http://svn.apache.org/viewvc?rev=413877&view=rev
Log:
DERBY-717 updatable cursors and result sets
Added:
db/derby/docs/trunk/src/devguide/rdevconceptsfor.dita (with props)
db/derby/docs/trunk/src/devguide/rdevconceptsinsertrow.dita (with props)
db/derby/docs/trunk/src/devguide/rdevconceptssur.dita (with props)
Modified:
db/derby/docs/trunk/src/adminguide/radminappsresultsetdiffs.dita
db/derby/docs/trunk/src/devguide/cdevconcepts22641.dita
db/derby/docs/trunk/src/devguide/cdevconcepts23987.dita
db/derby/docs/trunk/src/devguide/cdevconcepts28351.dita
db/derby/docs/trunk/src/devguide/cdevconcepts30811.dita
db/derby/docs/trunk/src/devguide/cdevconcepts41275.dita
db/derby/docs/trunk/src/devguide/cdevconcepts840995.dita
db/derby/docs/trunk/src/devguide/cdevconcepts842385.dita
db/derby/docs/trunk/src/devguide/cdevstandards805664.dita
db/derby/docs/trunk/src/devguide/derbydev.ditamap
db/derby/docs/trunk/src/devguide/rdevconcepts1119.dita
db/derby/docs/trunk/src/devguide/rdevconcepts38274.dita
db/derby/docs/trunk/src/devguide/rdevconcepts88082.dita
db/derby/docs/trunk/src/devguide/rdevconceptsholdablecursors.dita
db/derby/docs/trunk/src/ref/rrefexcept71493.dita
db/derby/docs/trunk/src/ref/rrefjdbc77156.dita
db/derby/docs/trunk/src/ref/rrefjdbc80004.dita
db/derby/docs/trunk/src/ref/rrefsql9241891.dita
db/derby/docs/trunk/src/ref/rrefsqlj26498.dita
db/derby/docs/trunk/src/ref/rrefsqlj31783.dita
db/derby/docs/trunk/src/ref/rrefsqlj35981.dita
db/derby/docs/trunk/src/ref/rrefsqlj41360.dita
db/derby/docs/trunk/src/tools/rtoolsijcomref62772.dita
db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita
Modified: db/derby/docs/trunk/src/adminguide/radminappsresultsetdiffs.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/radminappsresultsetdiffs.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/radminappsresultsetdiffs.dita (original)
+++ db/derby/docs/trunk/src/adminguide/radminappsresultsetdiffs.dita Tue Jun 13 04:57:07 2006
@@ -19,7 +19,7 @@
<concept id="radminappsresultsetdiffs" xml:lang="en-us">
<title>Updatable Result Sets</title>
<conbody>
-<p>The functionality of updatable resultsets in a server environment are similar
+<p>The functionality of updatable result sets in a server environment are similar
to an embedded environment in <ph conref="adminconrefs.dita#prod/productshortname"></ph>,
with the exception of the following differences:<ul>
<li>The Network Client requires that there be at least one column in the select
@@ -29,11 +29,11 @@
cannot determine the target table for update/delete by looking at the column
metadata. This requirement is not necessary in an embedded environment.</li>
<li>The embedded driver allows for statement name changes when there is an
-open resultset on the statement object. This is not supported in a server
+open result set on the statement object. This is not supported in a server
environment.</li>
-</ul>Other differences between updatable resultsets in a server or embedded
+</ul>Other differences between updatable result sets in a server or embedded
environment can be found in the following table.<table><title>Comparison of
-updatable resultsets features in server and embedded environments</title>
+updatable result sets features in server and embedded environments</title>
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row valign="bottom">
@@ -43,21 +43,12 @@
</thead>
<tbody>
<row>
-<entry colname="col1">updateString on SMALLINT, INTEGER, BIGINT, DECIMAL datatypes
-supported.</entry>
-<entry colname="col2">Not supported</entry>
-</row>
-<row>
<entry colname="col1">updateBytes on CHAR, VARCHAR, LONG VARCHAR datatypes
supported.</entry>
<entry colname="col2">Not supported</entry>
</row>
<row>
<entry colname="col1">updateTime on TIMESTAMP datatypes supported.</entry>
-<entry colname="col2">Not supported</entry>
-</row>
-<row>
-<entry colname="col1">updateObject with null values supported.</entry>
<entry colname="col2">Not supported</entry>
</row>
<row>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts22641.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts22641.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts22641.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts22641.dita Tue Jun 13 04:57:07 2006
@@ -18,56 +18,84 @@
limitations under the License.
-->
<concept id="cdevconcepts22641" xml:lang="en-us">
-<title>Scrolling insensitive ResultSets</title>
-<shortdesc>JDBC 2.0 adds a new kind of <codeph><i>ResultSet</i></codeph>,
-one that allows you to scroll in either direction or to move the cursor to
-a particular row. <ph conref="devconrefs.dita#prod/productshortname"></ph> implements
-scrolling insensitive <codeph><i>ResultSets</i></codeph>.</shortdesc>
+<title>Scrollable result sets</title>
+<shortdesc>JDBC 2.0 adds two new types of result sets which allows
+you to scroll in either direction or to move the cursor to a
+particular row. <ph conref="devconrefs.dita#prod/productshortname"></ph> supports one of
+these types: scrollable insensitive result sets
+(<codeph>ResultSet.TYPE_SCROLL_INSENSITIVE</codeph>).
+</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Scrolling insensitive cursors</indexterm><indexterm>ResultSets<indexterm>scrolling
-insensitive (JDBC 2.0)</indexterm></indexterm><indexterm>Cursors<indexterm>scrolling
-insensitive</indexterm></indexterm></keywords>
+<keywords><indexterm>result set</indexterm><indexterm>Scrollable cursors</indexterm><indexterm>ResultSets<indexterm>scrollable insensitive (JDBC 2.0)</indexterm></indexterm><indexterm>Cursors<indexterm>scrollable insensitive</indexterm></indexterm></keywords>
</metadata></prolog>
<conbody>
-<p>When you use a scroll insensitive <codeph><i>ResultSets</i></codeph> cursor
-to facilitate the insensitive scrolling action, <ph conref="devconrefs.dita#prod/productshortname"></ph> materializes
-in memory all rows from the first one in the result set up to the one with
-the biggest row number.</p>
+<section>
+
+<p>When you use a result set of type of type
+<codeph>ResultSet.TYPE_SCROLL_INSENSITIVE</codeph>, <ph
+conref="devconrefs.dita#prod/productshortname"></ph> materializes rows
+from the first one in the result set up to the one with the biggest
+row number as the rows are requested. The materialized rows will be
+backed to disk if necessary, to avoid excessive memory usage.
+</p>
+
+<p>
+Insensitive result sets, in contrast to sensitive result sets,
+are insensitive to changes made by others on the rows which have been
+materialized. <ph conref="devconrefs.dita#prod/productshortname"></ph>
+allows updates of scrollable insensitive result sets, please see <xref
+href="rdevconceptssur.dita#visibility">Visibilty of changes</xref>,
+which also explains visibility of own changes.
+</p>
+
+<p>
+<note>
+<ph conref="devconrefs.dita#prod/productshortname"></ph> does not
+support result sets of type ResultSet.TYPE_SCROLL_SENSITIVE.
+</note>
+</p>
+
+
<codeblock><b>//autocommit does not have to be off because even if
//we accidentally scroll past the last row, the implicit commit
//on the the statement will not close the result set because result sets
//are held over commit by default</b>
conn.setAutoCommit(false);
-Statement s4 = conn.createStatement(
-ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);
+Statement s4 = conn.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE,
+ ResultSet.CONCUR_READ_ONLY);
s4.execute("set schema 'SAMP'");
ResultSet scroller=s4.executeQuery(
"SELECT sales_person, region, sales FROM sales " +
"WHERE sales > 8 ORDER BY sales DESC");
-if (scroller.first())
- System.out.println("The sales rep who sold the highest number
- of sales is " +
- scroller.getString("SALES_PERSON"));
-else
+if (scroller.first()) { // One row is now materialized
+ System.out.println("The sales rep who sold the highest number" +
+ " of sales is " +
+ scroller.getString("SALES_PERSON"));
+} else {
System.out.println("There are no rows.");
+}
scroller.beforeFirst();
-scroller.afterLast();
+scroller.afterLast(); // By calling afterlast(), all rows will be materialized
scroller.absolute(3);
-if (!scroller.isAfterLast())
- System.out.println("The employee with the third highest number
- of sales is " +
- scroller.getString("SALES_PERSON") + ", with " +
- scroller.getInt("SALES") + " sales");
-if (scroller.isLast())
+if (!scroller.isAfterLast()) {
+ System.out.println("The employee with the third highest number " +
+ "of sales is " +
+ scroller.getString("SALES_PERSON") + ", with " +
+ scroller.getInt("SALES") + " sales");
+}
+if (scroller.isLast()) {
System.out.println("There are only three rows.");
-if (scroller.last())
- System.out.println("The least highest number
- of sales of the top three sales is: " +
- scroller.getInt("SALES"));
+}
+if (scroller.last()) {
+ System.out.println("The least highest number " +
+ "of sales of the top three sales is: " +
+ scroller.getInt("SALES"));
+}
scroller.close();
s4.close();
conn.commit()
conn.close();
System.out.println("Closed connection");</codeblock>
+</section>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts23987.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts23987.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts23987.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts23987.dita Tue Jun 13 04:57:07 2006
@@ -18,15 +18,18 @@
limitations under the License.
-->
<concept id="cdevconcepts23987" xml:lang="en-us">
-<title>ResultSets and auto-commit</title>
+<title>Result sets and auto-commit</title>
<shortdesc>Except for the result sets associated with holdable cursors, issuing
a commit will cause all result sets on your connection to be closed.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>ResultSets<indexterm>behavior of with auto-commit</indexterm></indexterm>
+<keywords><indexterm>Result sets<indexterm>behavior of with auto-commit</indexterm></indexterm>
</keywords>
</metadata></prolog>
<conbody>
-<p>The JDBC program is not required to have auto-commit off when using updatable
-ResultSets.</p>
+<p>The JDBC application is not required to have auto-commit off when
+using update methods on updatable result set, even if the result set
+is not holdable. Positioned updates and deletes cannot be used in
+combination with autocommit and non-holdable result sets.
+</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts28351.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts28351.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts28351.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts28351.dita Tue Jun 13 04:57:07 2006
@@ -18,12 +18,50 @@
limitations under the License.
-->
<concept id="cdevconcepts28351" xml:lang="en-us">
-<title>Updatable cursors</title>
-<shortdesc>Cursors are read-only by default. For a cursor to be updatable,
-you must specify <codeph>SELECT . . . FOR UPDATE</codeph>.</shortdesc>
+<title>Updatable result sets</title>
+<shortdesc>
+Updatable result sets in <ph
+conref="devconrefs.dita#prod/productshortname"></ph> can be updated by
+using result set update methods
+(<codeph>updateRow()</codeph>,<codeph>deleteRow()</codeph> and
+<codeph>insertRow()</codeph>), or by using positioned update or delete
+queries.
+</shortdesc>
<prolog></prolog>
<conbody>
-<p>Use <codeph>FOR UPDATE</codeph> only when you will be modifying rows to
-avoid excessive locking of tables.</p>
+<section>
+
+<p> Both scrollable and non-scrollable result sets can be updatable in <ph
+conref="devconrefs.dita#prod/productshortname"></ph>.
+</p>
+
+<p> If the query which was executed to create the result set is not updatable,
+<ph conref="devconrefs.dita#prod/productshortname"></ph> will downgrade
+the concurrency mode to <codeph>ResultSet.CONCUR_READ_ONLY</codeph>,
+and add a warning about this on the <codeph>ResultSet</codeph>. The
+compilation of the query fails if the result set cannot be updatable,
+and contains a <codeph>FOR UPDATE</codeph> clause. </p>
+
+<p>Positioned updates and deletes can be performed if the query
+contains <codeph>FOR UPDATE</codeph> or if the concurrency mode for
+the result set is <codeph>ResultSet.CONCUR_UPDATABLE</codeph>.</p>
+
+<p>To use the result set update methods, the concurrency mode for the
+result set must be <codeph>ResultSet.CONCUR_UPDATABLE</codeph>.
+The query does not need to contain <codeph>FOR UPDATE</codeph> to
+use these methods. </p>
+
+<p>Updatable cursors lock the current row with an update lock when
+positioned on the row, regardless of isolation level. Therefore, to
+avoid excessive locking of rows, only use concurrency mode
+<codeph>ResultSet.CONCUR_UPDATABLE</codeph> or the <codeph>FOR
+UPDATE</codeph> clause when you actually need to update the rows.
+For more information about locking, see
+<xref href="cdevconcepts36402.dita">Types and scope of locks in Derby
+systems.</xref>
+
+</p>
+</section>
+
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts30811.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts30811.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts30811.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts30811.dita Tue Jun 13 04:57:07 2006
@@ -18,7 +18,7 @@
limitations under the License.
-->
<concept id="cdevconcepts30811" xml:lang="en-us">
-<title>Requirements for updatable cursors</title>
+<title>Requirements for updatable result sets</title>
<shortdesc>Only specific SELECT statements- simple accesses of a single table-allow
you to update or delete rows as you step through them.</shortdesc>
<prolog><metadata>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts41275.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts41275.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts41275.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts41275.dita Tue Jun 13 04:57:07 2006
@@ -18,17 +18,25 @@
limitations under the License.
-->
<concept id="cdevconcepts41275" xml:lang="en-us">
-<title>SQL and JDBC ResultSet/Cursor mechanisms</title>
-<shortdesc>A cursor provides you with the ability to step through and process
-the rows in a <i>ResultSet</i> one by one.</shortdesc>
+<title>Result set and cursor mechanisms</title>
+<shortdesc>
+A result set maintains a cursor, which points to its current row of
+data. It can be used to step through and process the rows one by one.
+</shortdesc>
<prolog><metadata>
<keywords><indexterm>Cursors<indexterm>working with</indexterm></indexterm>
<indexterm>ResultSets<indexterm>working with</indexterm></indexterm></keywords>
</metadata></prolog>
<conbody>
-<p>A <codeph><i>java.sql.ResultSet</i></codeph> object constitutes a cursor.
-You do not need to use a language construct, such as SQL-92's DECLARE CURSOR,
-to work with cursors in a Java application. In <ph conref="devconrefs.dita#prod/productshortname"></ph>,
-any SELECT statement generates a cursor.</p>
+<p>
+In <ph conref="devconrefs.dita#prod/productshortname"></ph>, any
+SELECT statement generates a cursor which can be controlled by a
+<codeph><i>java.sql.ResultSet</i></codeph> object.
+<ph conref="devconrefs.dita#prod/productshortname"></ph> does not
+support SQL-92's DECLARE CURSOR language construct to create cursors,
+however <ph conref="devconrefs.dita#prod/productshortname"></ph>
+supports positioned deletes and positioned updates of updatable
+cursors.
+</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts840995.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts840995.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts840995.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts840995.dita Tue Jun 13 04:57:07 2006
@@ -18,13 +18,27 @@
limitations under the License.
-->
<concept id="cdevconcepts840995" xml:lang="en-us">
-<title>Holdable cursors and autocommit</title>
-<shortdesc>When autocommit is on, positioned updates and deletes are not supported
-for <i>ResultSet</i> objects that hold cursors open. If you attempt an update
-or delete, an exception is thrown.</shortdesc>
+<title>Holdable result sets and autocommit</title>
+<shortdesc>When autocommit is on, a positioned update or delete
+statement will automatically cause the transaction to commit.
+
+</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Holdable cursors and autocommit</indexterm><indexterm>Autocommit<indexterm>holdable
-cursors and</indexterm></indexterm></keywords>
+<keywords><indexterm>Holdable result sets and
+autocommit</indexterm><indexterm>Autocommit<indexterm>Result set
+holdability</indexterm></indexterm></keywords>
</metadata></prolog>
-<conbody></conbody>
+<conbody>
+<section>
+
+<p>If the result set has holdability
+<codeph>ResultSet.CLOSE_CURSORS_AT_COMMIT</codeph>, combined with
+autocommit on, <ph conref="devconrefs.dita#prod/productshortname"></ph>
+gives an exception on positioned updates and deletes because the
+cursor is closed immediately before the positioned statement is
+commenced, as mandated by JDBC. In contrast, no such implicit commit
+is done when using result set updates methods.
+</p>
+</section>
+</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts842385.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts842385.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts842385.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts842385.dita Tue Jun 13 04:57:07 2006
@@ -19,7 +19,9 @@
<concept id="cdevconcepts842385" xml:lang="en-us">
<title>Update locks</title>
<shortdesc>When a user-defined update cursor (created with the FOR UPDATE
-clause) reads data, its transaction obtains an <i>update</i> lock on the data.</shortdesc>
+clause or by using concurrency mode
+<codeph>ResultSet.CONCUR_UPDATABLE</codeph>) reads data, its
+transaction obtains an <i>update</i> lock on the data.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Update locks</indexterm></keywords>
</metadata></prolog>
Modified: db/derby/docs/trunk/src/devguide/cdevstandards805664.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevstandards805664.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevstandards805664.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevstandards805664.dita Tue Jun 13 04:57:07 2006
@@ -19,10 +19,10 @@
-->
<concept id="cdevstandards805664" xml:lang="en-us">
<title>Cursors</title>
-<shortdesc><ph conref="devconrefs.dita#prod/productshortname"></ph> uses JDBC's
-Result Sets, and does not provide SQL for manipulating cursors except for
+<shortdesc><ph conref="devconrefs.dita#prod/productshortname"></ph>
+uses JDBC's result sets, and does not provide SQL for manipulating cursors except for
positioned update and delete. <ph conref="devconrefs.dita#prod/productshortname"></ph>'s
-scrolling insensitive cursors are provided through JDBC, not through SQL commands.</shortdesc>
+scrollable insensitive cursors are provided through JDBC, not through SQL commands.</shortdesc>
<prolog></prolog>
<conbody></conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Tue Jun 13 04:57:07 2006
@@ -679,7 +679,7 @@
</topicref>
</relcell>
<relcell>
-<topicref href="cdevconcepts41275.dita" navtitle="SQL and JDBC ResultSet/Cursor mechanisms">
+<topicref href="cdevconcepts41275.dita" navtitle="Result set and cursor mechanisms">
</topicref>
<topicref href="cdevconcepts30291.dita" navtitle="Locking, concurrency, and isolation">
</topicref>
@@ -695,7 +695,7 @@
</relrow>
<relrow>
<relcell>
-<topicref href="cdevconcepts41275.dita" navtitle="SQL and JDBC ResultSet/Cursor mechanisms">
+<topicref href="cdevconcepts41275.dita" navtitle="Result set and cursor mechanisms">
</topicref>
</relcell>
<relcell>
@@ -779,19 +779,19 @@
<topicref href="cdevconcepts838179.dita" navtitle="Statements"></topicref>
</relcell>
<relcell>
-<topicref href="cdevconcepts838315.dita" navtitle="ResultSets and Cursors">
+<topicref href="cdevconcepts838315.dita" navtitle="Result sets and Cursors">
</topicref>
<topicref href="cdevconcepts26633.dita" navtitle="Nested connections"></topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="cdevconcepts838315.dita" navtitle="ResultSets and Cursors">
+<topicref href="cdevconcepts838315.dita" navtitle="Result sets and Cursors">
</topicref>
</relcell>
<relcell>
<topicref href="cdevconcepts26633.dita" navtitle="Nested connections"></topicref>
-<topicref href="cdevconcepts41275.dita" navtitle="SQL and JDBC ResultSet/Cursor mechanisms">
+<topicref href="cdevconcepts41275.dita" navtitle="Result set and cursor mechanisms">
</topicref>
</relcell>
</relrow>
@@ -817,7 +817,7 @@
</topicref>
<topicref href="cdevconcepts14433.dita" navtitle="Statement versus transaction runtime rollback">
</topicref>
-<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable cursors">
+<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable result sets">
</topicref>
</relcell>
</relrow>
@@ -832,7 +832,7 @@
</topicref>
<topicref href="cdevconcepts14433.dita" navtitle="Statement versus transaction runtime rollback">
</topicref>
-<topicref href="cdevconcepts41275.dita" navtitle="SQL and JDBC ResultSet/Cursor mechanisms">
+<topicref href="cdevconcepts41275.dita" navtitle="Result set and cursor mechanisms">
</topicref>
</relcell>
</relrow>
@@ -860,63 +860,63 @@
</relrow>
<relrow>
<relcell>
-<topicref href="rdevconcepts88082.dita" navtitle="Simple non-updatable ResultSets">
+<topicref href="rdevconcepts88082.dita" navtitle="Simple non-updatable result sets">
</topicref>
</relcell>
<relcell>
-<topicref href="cdevconcepts28351.dita" navtitle="Updatable cursors"></topicref>
-<topicref href="cdevconcepts23987.dita" navtitle="ResultSets and auto-commit">
+<topicref href="cdevconcepts28351.dita" navtitle="Updatable result sets"></topicref>
+<topicref href="cdevconcepts23987.dita" navtitle="Result sets and auto-commit">
</topicref>
-<topicref href="cdevconcepts22641.dita" navtitle="Scrolling insensitive ResultSets">
+<topicref href="cdevconcepts22641.dita" navtitle="Scrollable result sets">
</topicref>
-<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable cursors">
+<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable result sets">
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="cdevconcepts28351.dita" navtitle="Updatable cursors"></topicref>
+<topicref href="cdevconcepts28351.dita" navtitle="Updatable result sets"></topicref>
</relcell>
<relcell>
-<topicref href="cdevconcepts23987.dita" navtitle="ResultSets and auto-commit">
+<topicref href="cdevconcepts23987.dita" navtitle="Result sets and auto-commit">
</topicref>
-<topicref href="cdevconcepts22641.dita" navtitle="Scrolling insensitive ResultSets">
+<topicref href="cdevconcepts22641.dita" navtitle="Scrollable result sets">
</topicref>
-<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable cursors">
+<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable result sets">
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="cdevconcepts23987.dita" navtitle="ResultSets and auto-commit">
+<topicref href="cdevconcepts23987.dita" navtitle="Result sets and auto-commit">
</topicref>
</relcell>
<relcell>
-<topicref href="cdevconcepts22641.dita" navtitle="Scrolling insensitive ResultSets">
+<topicref href="cdevconcepts22641.dita" navtitle="Scrollable result sets">
</topicref>
-<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable cursors">
+<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable result sets">
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable cursors">
+<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable result sets">
</topicref>
</relcell>
<relcell>
-<topicref href="cdevconcepts22641.dita" navtitle="Scrolling insensitive ResultSets">
+<topicref href="cdevconcepts22641.dita" navtitle="Scrollable result sets">
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="cdevconcepts30811.dita" navtitle="Requirements for updatable cursors">
+<topicref href="cdevconcepts30811.dita" navtitle="Requirements for updatable result sets">
</topicref>
</relcell>
<relcell>
<topicref href="tdevconcepts41704.dita" navtitle="Naming or accessing the name of a cursor">
</topicref>
-<topicref href="rdevconcepts38274.dita" navtitle="Extended updatable cursor example">
+<topicref href="rdevconcepts38274.dita" navtitle="Extended updatable result set example">
</topicref>
</relcell>
</relrow>
@@ -926,17 +926,17 @@
</topicref>
</relcell>
<relcell>
-<topicref href="rdevconcepts38274.dita" navtitle="Extended updatable cursor example">
+<topicref href="rdevconcepts38274.dita" navtitle="Extended updatable result set example">
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
-<topicref href="cdevconcepts840995.dita" navtitle="Holdable cursors and autocommit">
+<topicref href="cdevconcepts840995.dita" navtitle="Holdable result sets and autocommit">
</topicref>
</relcell>
<relcell>
-<topicref href="rdevconcepts1119.dita" navtitle="Non-holdable cursor example">
+<topicref href="rdevconcepts1119.dita" navtitle="Non-holdable result set example">
</topicref>
</relcell>
</relrow>
@@ -2171,7 +2171,7 @@
<topicref href="cdevconcepts38375.dita" navtitle="The JDBC Connection and Transaction Model">
<topicref href="cdevconcepts36881.dita" navtitle="Connections">
<topicref href="cdevconcepts838179.dita" navtitle="Statements"></topicref>
-<topicref href="cdevconcepts838315.dita" navtitle="ResultSets and Cursors">
+<topicref href="cdevconcepts838315.dita" navtitle="Result sets and Cursors">
</topicref>
<topicref href="cdevconcepts26633.dita" navtitle="Nested connections"></topicref>
</topicref>
@@ -2187,25 +2187,29 @@
</topicref>
</topicref>
</topicref>
-<topicref href="cdevconcepts41275.dita" navtitle="SQL and JDBC ResultSet/Cursor mechanisms">
-<topicref href="rdevconcepts88082.dita" navtitle="Simple non-updatable ResultSets">
+<topicref href="cdevconcepts41275.dita" navtitle="Result set and cursor mechanisms">
+<topicref href="rdevconcepts88082.dita" navtitle="Simple non-updatable result sets">
</topicref>
-<topicref href="cdevconcepts28351.dita" navtitle="Updatable cursors">
-<topicref href="cdevconcepts30811.dita" navtitle="Requirements for updatable cursors">
+<topicref href="cdevconcepts28351.dita" navtitle="Updatable result sets">
+<topicref href="cdevconcepts30811.dita" navtitle="Requirements for updatable result sets">
</topicref>
+<topicref href="rdevconceptsfor.dita" navtitle="Forward only updatable result sets"> </topicref>
+<topicref href="rdevconceptssur.dita" navtitle="Scrollable updatable result sets"> </topicref>
+<topicref href="rdevconceptsinsertrow.dita" navtitle="Inserting rows
+with updatable result sets"> </topicref>
<topicref href="tdevconcepts41704.dita" navtitle="Naming or accessing the name of a cursor">
</topicref>
-<topicref href="rdevconcepts38274.dita" navtitle="Extended updatable cursor example">
+<topicref href="rdevconcepts38274.dita" navtitle="Extended updatable result set example">
</topicref>
</topicref>
-<topicref href="cdevconcepts23987.dita" navtitle="ResultSets and auto-commit">
+<topicref href="cdevconcepts23987.dita" navtitle="Result sets and auto-commit">
</topicref>
-<topicref href="cdevconcepts22641.dita" navtitle="Scrolling insensitive ResultSets">
+<topicref href="cdevconcepts22641.dita" navtitle="Scrollable result sets">
</topicref>
-<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable cursors">
-<topicref href="cdevconcepts840995.dita" navtitle="Holdable cursors and autocommit">
+<topicref href="rdevconceptsholdablecursors.dita" navtitle="Holdable result sets">
+<topicref href="cdevconcepts840995.dita" navtitle="Holdable result sets and autocommit">
</topicref>
-<topicref href="rdevconcepts1119.dita" navtitle="Non-holdable cursor example">
+<topicref href="rdevconcepts1119.dita" navtitle="Non-holdable result set example">
</topicref>
</topicref>
</topicref>
Modified: db/derby/docs/trunk/src/devguide/rdevconcepts1119.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconcepts1119.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconcepts1119.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevconcepts1119.dita Tue Jun 13 04:57:07 2006
@@ -18,7 +18,7 @@
limitations under the License.
-->
<reference id="rdevconcepts1119" xml:lang="en-us">
-<title>Non-holdable cursor example</title>
+<title>Non-holdable result set example</title>
<shortdesc>The following example uses <i>Connection.createStatement</i> to
return a <codeph><i>ResultSet</i></codeph> that will close after a commit
is performed.</shortdesc>
Modified: db/derby/docs/trunk/src/devguide/rdevconcepts38274.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconcepts38274.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconcepts38274.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevconcepts38274.dita Tue Jun 13 04:57:07 2006
@@ -16,48 +16,48 @@
-->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
<reference xml:lang="en-us" id="rdevconcepts38274">
-<title>Extended updatable cursor example</title>
+<title>Extended updatable result set example</title>
<prolog>
</prolog>
<refbody><example>
-<codeblock>String URL = "jdbc:derby:sample";
-<b>// autocommit must be turned off for updatable cursors</b>
+<codeblock>
+Connection conn = DriverManager.getConnection("jdbc:derby:sample");
conn.setAutoCommit(false);
-Statement s3 = conn.createStatement();
-<b>// name the statement so we can reference the result set
-// it generates</b>
-s3.setCursorName("UPDATABLESTATEMENT");
+
+<b>// Create the statement with concurrency mode CONCUR_UPDATABLE</b>
+<b>// to allow result sets to be updatable</b>
+Statement stmt = conn.createStatement(ResultSet.TYPE_FORWARD_ONLY,
+ ResultSet.CONCUR_UPDATABLE,
+ ResultSet.CLOSE_CURSORS_AT_COMMIT);
<b>// Updatable statements have some requirements</b>
<b>// for example, select must be on a single table</b>
-ResultSet Updatable = s3.executeQuery(
- "SELECT firstnme, lastname, workdept, bonus" +
- "FROM employee FOR UPDATE of bonus");
-<b>// we need a separate statement to do the</b>
-<b>// update PreparedStatement</b>
-PreparedStatement ps2 = conn.prepareStatement("UPDATE employee " +
-<b>// we could use the cursor name known by the system,</b>
-<b>// as the following line shows</b>
-<b>//"SET bonus = ? WHERE CURRENT OF " + Updatable.getCursorName());</b>
-<b>// but we already know the cursor name</b>
-"SET bonus = ? WHERE CURRENT OF UPDATABLESTATEMENT");
+ResultSet uprs = stmt.executeQuery(
+ "SELECT FIRSTNME, LASTNAME, WORKDEPT, BONUS" +
+ "FROM EMPLOYEE FOR UPDATE of BONUS"); // Only bonus can be updated
+
String theDept="E21";
-while (Updatable.next()) {
- String firstnme = Updatable.getString("FIRSTNME");
- String lastName = Updatable.getString("LASTNAME");
- String workDept = Updatable.getString("WORKDEPT");
- BigDecimal bonus = Updatable.getBigDecimal("BONUS");
+
+while (uprs.next()) {
+ String firstnme = uprs.getString("FIRSTNME");
+ String lastName = uprs.getString("LASTNAME");
+ String workDept = uprs.getString("WORKDEPT");
+ BigDecimal bonus = uprs.getBigDecimal("BONUS");
if (workDept.equals(theDept)) {
- <b>// if the current row meets our criteria,
- // update the updatable column in the row</b>
- ps2.setBigDecimal(1, bonus.add(new BigDecimal(250)));
- ps2.executeUpdate();
- System.out.println("Updating bonus in employee" +
- " table for employee " + firstnme +
- ", department " + theDept );
+ <b> // if the current row meets our criteria,
+ // update the updatable column in the row</b>
+ uprs.updateBigDecimal("BONUS", bonus.add(BigDecimal.valueOf(250L)));
+ uprs.updateRow();
+ System.out.println("Updating bonus for employee:" +
+ firstnme + lastName);
}
- }
-Updatable.close();
-s3.close();
-ps2.close();
-conn.commit();</codeblock></example>
+}
+conn.commit(); // commit the transaction
+<b>// close object </b>
+uprs.close();
+stmt.close();
+<b>// Close connection if the application does not need it any more</b>
+conn.close();
+
+</codeblock>
+</example>
</refbody></reference>
Modified: db/derby/docs/trunk/src/devguide/rdevconcepts88082.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconcepts88082.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconcepts88082.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevconcepts88082.dita Tue Jun 13 04:57:07 2006
@@ -18,9 +18,9 @@
limitations under the License.
-->
<reference id="rdevconcepts88082" xml:lang="en-us">
-<title>Simple non-updatable ResultSets</title>
+<title>Simple non-updatable result sets</title>
<shortdesc>This example is an excerpt from a sample JDBC application that
-generates a <i>ResultSet</i> with a simple SELECT statement and then processes
+generates a result set with a simple SELECT statement and then processes
the rows.</shortdesc>
<prolog></prolog>
<refbody>
Added: db/derby/docs/trunk/src/devguide/rdevconceptsfor.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconceptsfor.dita?rev=413877&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconceptsfor.dita (added)
+++ db/derby/docs/trunk/src/devguide/rdevconceptsfor.dita Tue Jun 13 04:57:07 2006
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!--
+Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="rdevconceptsfor" xml:lang="en-us">
+<title>Forward only updatable result sets</title>
+<shortdesc>A forward only updatable result set maintains a cursor
+which can only move in one direction (forward), and also update rows.
+</shortdesc>
+<prolog></prolog>
+<conbody>
+<section>
+<p>To create a forward only updatable result set, the
+statement has to be created with concurrency mode
+<codeph>ResultSet.CONCUR_UPDATABLE</codeph> and type
+<codeph>ResultSet.TYPE_FORWARD_ONLY</codeph>.
+<note> The default type is
+<codeph>ResultSet.TYPE_FORWARD_ONLY</codeph>.</note>
+</p>
+
+<p>Example of using <codeph>ResultSet.updateXXX() +
+ResultSet.updateRow()</codeph> to update a row: </p>
+
+<codeblock>
+ Statement stmt = conn.createStatement(ResultSet.TYPE_FORWARD_ONLY,
+ ResultSet.CONCUR_UPDATABLE);
+ ResultSet uprs = stmt.executeQuery(
+ "SELECT FIRSTNAME, LASTNAME, WORKDEPT, BONUS" +
+ "FROM EMPLOYEE");
+
+ while (uprs.next()) {
+ int newBonus = uprs.getInt("BONUS") + 100;
+ uprs.updateInt("BONUS", newBonus);
+ uprs.updateRow();
+ }
+</codeblock>
+
+<p>Example of using <codeph>ResultSet.deleteRow()</codeph> to delete a row: </p>
+
+<codeblock>
+ Statement stmt = conn.createStatement(ResultSet.TYPE_FORWARD_ONLY,
+ ResultSet.CONCUR_UPDATABLE);
+ ResultSet uprs = stmt.executeQuery(
+ "SELECT FIRSTNAME, LASTNAME, WORKDEPT, BONUS" +
+ "FROM EMPLOYEE");
+
+ while (uprs.next()) {
+ if (uprs.getInt("WORKDEPT")==300) {
+ uprs.deleteRow();
+ }
+ }
+</codeblock>
+
+</section>
+
+<section>
+
+<title>Visibility of changes </title>
+<ul>
+<li>After an update or delete is made on a forward only result set,
+the result set's cursor is no longer on the row just updated or
+deleted, but immediately before the next row in the result set (it is
+necessary to move to the next row before any further row operations
+are allowed). This means that changes made by
+<codeph>ResultSet.updateRow()</codeph> and
+<codeph>ResultSet.deleteRow()</codeph> are never visible.
+</li>
+<li>If a row has been inserted, i.e using
+<codeph>ResultSet.insertRow()</codeph> it may be visible in a forward
+only result set.</li>
+</ul>
+</section>
+
+<section>
+<title>Conflicting operations</title>
+<p> The current row of the result set cannot be changed by other
+transactions, since it will be locked with an update lock.
+Result sets held open after a commit have to move to the next row
+before allowing any operations on it. </p>
+
+Some conflicts may prevent the result set from doing updates/deletes:
+<ul>
+<li>If the current row is deleted by a statement in the same transaction, calls to
+<codeph>ResultSet.updateRow()</codeph> will cause an exception, since
+the cursor is no longer positioned on a valid row. </li>
+</ul>
+</section>
+
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/devguide/rdevconceptsfor.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/devguide/rdevconceptsholdablecursors.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconceptsholdablecursors.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconceptsholdablecursors.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevconceptsholdablecursors.dita Tue Jun 13 04:57:07 2006
@@ -18,55 +18,63 @@
limitations under the License.
-->
<reference id="rdevconceptsholdablecursors" xml:lang="en-us">
-<title>Holdable cursors</title>
-<shortdesc>The holdable cursor feature permits an application to keep cursors
-open after implicit or explicit commits. By default, the cursors are held
-open after a commit.</shortdesc>
+<title>Holdable result sets</title>
+<shortdesc>The holdable result set feature permits an application to
+keep result sets open after implicit or explicit commits. By default,
+the cursor controlled by the result set is held open after a commit.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Cursors<indexterm>holdable</indexterm></indexterm></keywords>
</metadata></prolog>
<refbody>
-<section> <note> Non-holdable cursors are only available in Java 2 Platform,
-Standard Edition, v 1.4 (J2SE) environments.</note></section>
+<section> <note> <ph conref="devconrefs.dita#prod/productshortname"></ph>, supports
+non-holdable result sets on platforms which support JDBC
+3.</note>
+</section>
<section><p>Starting with Java 2 Platform, Standard Edition, v 1.4 (J2SE),
-cursors can be created with close when a commit occurs option. Such cursors
-will be automatically closed when a commit happens. Cursors are automatically
+result sets can be created with close when a commit occurs option.
+Such result sets
+will be automatically closed when a commit happens. Result sets are automatically
closed when a transaction aborts, whether or not they have been specified
to be held open.</p></section>
-<section> <note> Holdable cursors do not work with XA transactions, in <ph
-conref="devconrefs.dita#prod/productshortname"></ph> Version 10.1, therefore
-cursors should be opened with holdability false when working with XA transactions.</note></section>
-<section><p>To specify whether a cursor should be held open after a commit
+<section><p>To specify whether a result set should be held open after a commit
takes place, supply one of the following <i>ResultSet</i> parameters to the <codeph><i>Connection</i></codeph> method <codeph><i>createStatement</i
></codeph>, <codeph><i>prepareStatement</i></codeph>, or <codeph><i>prepareCall</i></codeph>:</p></section>
-<section> <ul>
-<li><i><i>CLOSE_CURSORS_AT_COMMIT</i></i> <p>Cursors are closed when an
+<section>
+<ul>
+<li><i><i>CLOSE_CURSORS_AT_COMMIT</i></i> <p>Result sets are closed when an
implicit or explicit commit is performed.</p></li>
-<li><i><i>HOLD_CURSORS_OVER_COMMIT</i></i> <p>Cursors are held open when
+<li><i><i>HOLD_CURSORS_OVER_COMMIT</i></i> <p>Result sets are held open when
a commit is performed, implicitly or explicitly. This is the default behavior.</p></li>
</ul></section>
<section><p>The method <i>Statement.getResultSetHoldability()</i> indicates
-whether a cursor generated by the Statement object stays open or closes, upon
+whether a result set generated by the Statement object stays open or closes, upon
commit. See the <cite><ph conref="devconrefs.dita#pub/citref"></ph></cite> for
more information.</p></section>
-<section><p>When an implicit or explicit commit occurs, <i>ResultSets</i> that
-hold cursors open behave as follows:</p></section>
+<section><p>When an implicit or explicit commit occurs, result sets
+that hold cursors open behave as follows:</p></section>
<section> <ul>
-<li>Open <i>ResultSets</i> remain open. The cursor is positioned before the
-next logical row of the result set.</li>
-<li>When the session is terminated, the <i>ResultSet</i> is closed and destroyed.</li>
-<li>All locks are released, except locks protecting the current cursor position
-of open cursors specified to stay open after commits.</li>
-<li>Immediately following a commit, the only valid operations that can be
-performed on the <i>ResultSet</i> are: <ul>
-<li>positioning the <i>ResultSet</i> to the next valid row in the result with <codeph><i>ResultSet.next()</i></codeph>.</li>
-<li>closing the <i>ResultSet</i> with <codeph><i>ResultSet.close()</i></codeph>.</li>
+<li>Open result sets remain open. Non-scrollable result sets becomes
+positioned before the next logical row of the result set. Scrollable
+insensitive result sets keep their current position.</li>
+<li>When the session is terminated, the result set is closed and destroyed.</li>
+<li>All locks are released, including locks protecting the current
+cursor position.</li>
+<li>For non-scrollable result sets, immediately following a commit, the
+only valid operations that can be performed on the <i>ResultSet</i>
+object are: <ul>
+<li>positioning the result set to the next row with <codeph><i>ResultSet.next()</i></codeph>.</li>
+<li>closing the result set with <codeph><i>ResultSet.close()</i></codeph>.</li>
</ul></li>
</ul></section>
-<section><p>When a rollback occurs either explicitly or implicitly, the following
+<section><p>When a rollback or rollback to savepoint occurs, either explicitly or implicitly, the following
behavior applies:<ul>
-<li>All open <i>ResultSets</i> are closed.</li>
+<li>All open result sets are closed.</li>
<li>All locks acquired during the unit of work are released.</li>
</ul></p></section>
+<section> <note> Holdable result sets do not work with XA
+transactions in <ph
+conref="devconrefs.dita#prod/productshortname"></ph>. When working
+with XA transactions, the result set should be opened with holdability
+<codeph>ResultSet.CLOSE_CURSORS_AT_COMMIT</codeph>.</note></section>
</refbody>
</reference>
Added: db/derby/docs/trunk/src/devguide/rdevconceptsinsertrow.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconceptsinsertrow.dita?rev=413877&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconceptsinsertrow.dita (added)
+++ db/derby/docs/trunk/src/devguide/rdevconceptsinsertrow.dita Tue Jun 13 04:57:07 2006
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!--
+Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="rdevconceptsinsertrow" xml:lang="en-us">
+<title>Inserting rows with updatable result sets</title>
+<shortdesc>
+Updatable result set can be used to insert rows to the table, by
+using <codeph>ResultSet.insertRow()</codeph>.
+</shortdesc>
+<prolog></prolog>
+<conbody>
+<section>
+When inserting a row, each column in the insert row that does not
+allow null as a value and does not have a default value must be given
+a value using the appropriate update method.
+
+If the inserted row satisfies the query predicate, it may become
+visible in the result set.
+
+<p>Example of using <codeph>ResultSet.insertRow()</codeph> to insert a
+row: </p>
+
+<codeblock>
+ Statement stmt = conn.createStatement(ResultSet.TYPE_FORWARD_ONLY,
+ ResultSet.CONCUR_UPDATABLE);
+ ResultSet uprs = stmt.executeQuery(
+ "SELECT firstname, lastname, workdept, bonus" +
+ "FROM employee");
+ uprs.moveToInsertRow();
+ uprs.updateString("FIRSTNAME", "Andreas");
+ uprs.updateString("LASTNAME", "Korneliussen");
+ uprs.updateInt("WORKDEPT", 123);
+ uprs.insertRow();
+ uprs.moveToCurrentRow();
+
+</codeblock>
+
+</section>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/devguide/rdevconceptsinsertrow.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/devguide/rdevconceptssur.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevconceptssur.dita?rev=413877&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevconceptssur.dita (added)
+++ db/derby/docs/trunk/src/devguide/rdevconceptssur.dita Tue Jun 13 04:57:07 2006
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
+<!--
+Copyright 2006 The Apache Software Foundation or its licensors, as applicable.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="rdevconceptssur" xml:lang="en-us">
+<title>Scrollable updatable result sets</title>
+<shortdesc>A scrollable updatable result set maintains a cursor which
+can both scroll and update rows.
+</shortdesc>
+<prolog></prolog>
+<conbody>
+
+<section>
+<p>
+<ph conref="devconrefs.dita#prod/productshortname"></ph> only supports
+<xref href="cdevconcepts22641.dita">scrollable insensitive result sets.</xref>
+To create a scrollable insensitive result set which is updatable, the
+statement has to be created with concurrency mode
+<codeph>ResultSet.CONCUR_UPDATABLE</codeph> and type
+<codeph>ResultSet.TYPE_SCROLL_INSENSITIVE</codeph>.
+</p>
+
+<p>Example of using result set update methods to update a row: </p>
+
+<codeblock>
+ Statement stmt = conn.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE,
+ ResultSet.CONCUR_UPDATABLE);
+ ResultSet uprs = stmt.executeQuery(
+ "SELECT FIRSTNAME, LASTNAME, WORKDEPT, BONUS" +
+ "FROM EMPLOYEE");
+
+ uprs.absolute(5); // update the fifth row
+ int newBonus = uprs.getInt("BONUS") + 100;
+ uprs.updateInt("BONUS", newBonus);
+ uprs.updateRow();
+</codeblock>
+
+<p>Example of using <codeph>ResultSet.deleteRow()</codeph> to delete a row: </p>
+
+<codeblock>
+ Statement stmt = conn.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE,
+ ResultSet.CONCUR_UPDATABLE);
+ ResultSet uprs = stmt.executeQuery(
+ "SELECT FIRSTNAME, LASTNAME, WORKDEPT, BONUS" +
+ "FROM EMPLOYEE");
+
+ uprs.last();
+ uprs.relative(-5); // moves to the 5th from the last row
+ uprs.deleteRow();
+</codeblock>
+</section>
+
+<section id="visibility">
+<title>Visibility of changes </title>
+<ul>
+<li>Changes caused by other statements, triggers and other
+transactions (others) are considered as other changes, and are not visible in
+scrollable insensitive result sets. </li>
+<li>Own updates and deletes are visible in Derby's scrollable
+insensitive result sets. <note> <ph
+conref="devconrefs.dita#prod/productshortname"></ph> handles changes
+made using positioned updates and deletes as own changes, so when made
+via a result set's cursor such changes are also visible in that result
+set.
+</note>
+</li>
+<li>Rows inserted to the table may become visible in the result set.</li>
+<li><codeph>ResultSet.rowDeleted()</codeph> returns true if the row
+has been deleted using the cursor or result set. It does not detect
+deletes made by other statements or transactions. </li>
+<li><codeph>ResultSet.rowUpdated()</codeph> returns true if the row
+has been updated using the cursor or result set. It does not detect
+updates made by other statements or transactions. </li>
+<li> <note>Both <codeph>ResultSet.rowUpdated()</codeph> and
+<codeph>ResultSet.rowDeleted()</codeph> return true if the row
+first is updated and later deleted. </note> </li>
+</ul>
+
+Please be aware that even if changes caused by others are not visible
+in the result set, SQL operations, including positioned updates,
+which access the current row will read and use the row data as it is
+in the database, not as it is reflected in the result set.
+
+</section>
+
+<section>
+<title>Conflicting operations</title>
+<p>A conflict may occur in scrollable insensitive result sets if a row is
+updated/deleted by another committed transaction, or if a row is
+updated by another statement in the same transaction. The row which
+the cursor is positioned on is locked, however once it moves
+to another row, the lock may be released depending on transaction
+isolation level. This means that rows in the scrollable insensitive result
+set may have been updated/deleted by other transactions after they
+were fetched.</p>
+
+<p>Since the result set is <b>insensitive</b>, it will not detect the
+changes made by others. When doing updates using the result set,
+conflicting changes on the columns being changed will be overwritten. </p>
+
+Some conflicts may prevent the result set from doing updates/deletes:
+<ul>
+<li> The row has been deleted after it was read into the result set:
+Scrollable insensitive result sets will give a warning with <codeph>
+<i>SQLState</i> 01001 </codeph>. </li>
+<li> The table has been compressed: Scrollable insensitive
+result sets will give a warning with <codeph> <i>SQLState</i>
+01001</codeph>. A compress conflict may happen if the cursor is held
+over a commit. This is because the table intent lock is released on
+commit, and not reclaimed until the cursor moves to another row.
+</li>
+</ul>
+
+To avoid conflicts with other transactions, you may increase the
+transaction isolation level to repeatable read or serializable. This
+will make the transaction hold locks on the rows which have been read
+until it commits.
+
+<note>When you use holdable result sets, be aware that the locks will
+be released on commit, and conflicts may occur regardless of isolation level.
+You should probably avoid using holdable result sets if your
+application relies on transactional behavior for the result set.
+</note>
+
+</section>
+
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/devguide/rdevconceptssur.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/ref/rrefexcept71493.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefexcept71493.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefexcept71493.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefexcept71493.dita Tue Jun 13 04:57:07 2006
@@ -34,6 +34,10 @@
</thead>
<tbody>
<row>
+<entry colname="col1">01001</entry>
+<entry colname="col2">An attempt to update or delete an already deleted row was made: No row was updated or deleted.</entry>
+</row>
+<row>
<entry colname="col1">01003 </entry>
<entry colname="col2">Null values were eliminated from the argument of a column
function. </entry>
@@ -85,11 +89,6 @@
<entry colname="col2">Scroll sensitive cursors are not currently implemented. </entry>
</row>
<row>
-<entry colname="col1">01J03</entry>
-<entry colname="col2">Scroll sensitive and scroll insensitive updatable ResultSets
-are not currently implemented. </entry>
-</row>
-<row>
<entry colname="col1">01J04</entry>
<entry colname="col2">The class '<<i>className</i>>' for column '<<i>columnName</i>>'
does not implement java.io.Serializable or java.sql.SQLData. Instances must
@@ -3040,6 +3039,10 @@
<entry colname="col1">XJ081</entry>
<entry colname="col2">Invalid value '<<i>value</i>>' passed as parameter
'<<i>parameterName</i>>' to method '<<i>moduleName</i>>'.</entry>
+</row>
+<row>
+<entry colname="col1">XJ086</entry>
+<entry colname="col2">This method cannot be invoked while the cursor is not on the insert row or if the concurrency of this ResultSet object is CONCUR_READ_ONLY.</entry>
</row>
</tbody>
</tgroup>
Modified: db/derby/docs/trunk/src/ref/rrefjdbc77156.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc77156.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc77156.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc77156.dita Tue Jun 13 04:57:07 2006
@@ -33,6 +33,10 @@
</thead>
<tbody>
<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>absolute(int row)</i></entry>
+<entry colname="3"></entry>
+</row><row>
<entry colname="1"><i>void</i></entry>
<entry colname="2"><i>afterLast()</i></entry>
<entry colname="3"></entry>
@@ -50,10 +54,10 @@
<row>
<entry colname="1"><i>void</i></entry>
<entry colname="2"><i>deleteRow()</i></entry>
-<entry colname="3">After the row is updated, the ResultSet object will be
-positioned before the next row. Before issuing any methods other than close
-on the ResultSet object, the program will need to reposition the ResultSet
-object by using the <i>next()</i> method.</entry>
+<entry colname="3">After the row is deleted, the ResultSet object will
+be positioned before the next row. Before issuing any methods other
+than close on the ResultSet object, the program will need to
+reposition the ResultSet object.</entry>
</row>
<row>
<entry colname="1"><i>boolean</i></entry>
@@ -104,6 +108,11 @@
<entry colname="3"></entry>
</row>
<row>
+<entry colname="1"><i>void</i></entry>
+<entry colname="2"><i>insertRow()</i></entry>
+<entry colname="3"></entry>
+</row>
+<row>
<entry colname="1"><i>boolean</i></entry>
<entry colname="2"><i>isAfterLast()</i></entry>
<entry colname="3"></entry>
@@ -129,12 +138,39 @@
<entry colname="3"></entry>
</row>
<row>
+<entry colname="1"><i>void</i></entry>
+<entry colname="2"><i>moveToCurrentRow()</i></entry>
+<entry colname="3"></entry>
+</row>
+<row>
+<entry colname="1"><i>void</i></entry>
+<entry colname="2"><i>moveToInsertRow()</i></entry>
+<entry colname="3"></entry>
+</row>
+<row>
<entry colname="1"><i>boolean</i></entry>
<entry colname="2"><i>previous()</i></entry>
<entry colname="3"></entry>
</row>
<row>
<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>rowDeleted()</i></entry>
+<entry colname="3">For forward-only result sets this methods always returns <i>false</i>, for
+scrollable result sets it returns <i>true</i> if the row has been deleted.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>rowInserted()</i></entry>
+<entry colname="3">Always returns <i>false</i></entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>rowUpdated()</i></entry>
+<entry colname="3">For forward-only result sets this methods always returns <i>false</i>, for
+scrollable result sets it returns <i>true</i> if the row has been updated.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
<entry colname="2"><i>relative(int rows)</i></entry>
<entry colname="3"></entry>
</row>
@@ -154,18 +190,17 @@
<entry colname="3">After the row is updated, the ResultSet object will be
positioned before the next row. Before issuing any methods other than close
on the ResultSet object, the program will need to reposition the ResultSet
-object by using the <i>next()</i> method.</entry>
+object.</entry>
</row>
</tbody>
</tgroup>
</table>
-<section> <note>When working with scrolling insensitive <i>ResultSets</i> when
+<section> <note>When working with scrollable insensitive <i>ResultSets</i> when
auto-commit mode is turned on, the only positioning method that can close
the <i>ResultSet</i> automatically is the <i>next()</i> method. When auto-commit
mode is on, this method automatically closes the <i>ResultSet</i> if it is
-called and there are no more rows. <i>afterLast()</i> does not close the <i>ResultSet</i>,
-for example.<p>JDBC is not required to have auto-commit off when using updatable
-ResultSets.</p><p>At this moment, <ph conref="refconrefs.dita#prod/productshortname"></ph> does not support the insertRow() method for updatable <i>ResultSets</i>.</p></note></section>
+called and there are no more rows. <i>afterLast()</i> does not close
+the <i>ResultSet</i>.</note></section>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefjdbc80004.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc80004.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc80004.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc80004.dita Tue Jun 13 04:57:07 2006
@@ -19,8 +19,8 @@
<reference id="rrefjdbc80004" xml:lang="en-us">
<title>java.sql.Connection </title>
<prolog><metadata>
-<keywords><indexterm>Scroll insensitive cursors (JDBC)</indexterm><indexterm>Scrolling
-insensitive cursors</indexterm><indexterm>Cursors<indexterm>scrolling insensitive</indexterm></indexterm>
+<keywords><indexterm>Scrollable insensitive cursors (JDBC)</indexterm><indexterm>Scrollable
+insensitive cursors</indexterm><indexterm>Cursors<indexterm>scrollable insensitive</indexterm></indexterm>
</keywords>
</metadata></prolog>
<refbody>
@@ -51,14 +51,10 @@
</tgroup>
</table>
<section><title>Implementation notes</title><i>ResultSet.TYPE_FORWARD_ONLY</i> and <i>ResultSet.TYPE_SCROLL_INSENSITIVE</i> are
-the only scrolling types supported. If you request <i>TYPE_SCROLL_SENSITIVE</i>, <ph
+the only result set types supported. If you request <i>TYPE_SCROLL_SENSITIVE</i>, <ph
conref="refconrefs.dita#prod/productshortname"></ph> issues an <i>SQLWarning</i> and
returns a <i>TYPE_SCROLL_INSENSITIVE ResultSet</i>. <p> These methods support
both <i>ResultSet.CONCUR_READ_ONLY</i> and <i>ResultSet.CONCUR_UPDATABLE</i> concurrencies.
-However, you can only request an updatable ResultSet that has a <i>TYPE_FORWARD_ONLY</i> scrolling
-type. If you request an updatable ResultSet with <i>SCROLL_SENSITIVE</i> or <i>SCROLL_INSENSITIVE</i> types, <ph
-conref="refconrefs.dita#prod/productshortname"></ph> issues an <i>SQLWarning</i> and
-returns <i>TYPE_SCROLL_INSENSITIVE READ_ONLY ResultSet</i>.</p><p>(Use <i>Connection.getWarnings</i> to
-see warnings.)</p></section>
+</p></section>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefsql9241891.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsql9241891.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsql9241891.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsql9241891.dita Tue Jun 13 04:57:07 2006
@@ -925,7 +925,7 @@
<row>
<entry colname="col1">Scrolled cursors</entry>
<entry colname="col2">SQL92I</entry>
-<entry colname="col3">partial (scrolling insensitive result sets through JDBC
+<entry colname="col3">partial (scrollable insensitive result sets through JDBC
2.0)</entry>
</row>
<row>
Modified: db/derby/docs/trunk/src/ref/rrefsqlj26498.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj26498.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj26498.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj26498.dita Tue Jun 13 04:57:07 2006
@@ -23,10 +23,6 @@
<keywords><indexterm>UPDATE statement</indexterm></keywords>
</metadata></prolog>
<refbody>
-<section> <p>An UPDATE statement sets the value in a column.</p> <p>You can
-update the current row of an open, updatable cursor. If there is no current
-row, or if the current row no longer satisfies the cursor's query, an exception
-is raised.</p></section>
<refsyn><title>Syntax</title> <codeblock><b>{
UPDATE <i><xref href="rreftablename.dita#rreftablename">table-Name</xref></i>
SET <i><xref href="rrefcolumnname.dita#rrefcolumnname">column-Name</xref></i> = <i><xref
@@ -40,17 +36,18 @@
[ , <i><xref href="rrefcolumnname.dita#rrefcolumnname">column-Name</xref></i> = <i><xref
href="rrefsqlj76354.dita#rrefsqlj76354">Value</xref></i> ]*
<i><xref href="rrefsqlj15309.dita#rrefsqlj15309">WHERE CURRENT OF</xref></i>
-}</b></codeblock> <p>The first syntactical form is called a searched update.
-The second syntactical form is called a positioned update.</p> <p>For searched
-updates, you update all rows of the table for which the WHERE clause evaluates
-to TRUE.</p> <p>For positioned updates, you can update only columns that were
-included in the <xref href="rrefsqlj31783.dita#rrefsqlj31783">FOR UPDATE clause</xref> of the SELECT
-statement that created the cursor. If the SELECT statement did not include
-a FOR UPDATE clause, the cursor is read-only and cannot be used to update.</p> <p>Specifying
+}</b></codeblock> <p>The first syntactical form, called a searched update, updates the value of
+one or more columns for all rows of the table for which the WHERE clause evaluates to TRUE.</p>
+<p>The second syntactical form, called a positioned update, updates one or more columns on the
+current row of an open, updatable cursor. If columns were specified in the
+<xref href="rrefsqlj31783.dita#rrefsqlj31783">FOR UPDATE clause</xref> of the SELECT
+statement used to generate the cursor, only those columns can be updated. If no columns were specified
+or the select statement did not include a FOR UPDATE clause, all columns may be updated.</p>
+<p>Specifying
DEFAULT for the update value sets the value of the column to the default defined
for that table.</p> </refsyn>
-<example> <codeblock><b><ph>-- All the employees except the manager of department (WORKDEPT) 'E21' have
-been temporarily reassigned.
+<example><title>Example</title> <codeblock><b><ph>-- All the employees except the manager of
+department (WORKDEPT) 'E21' have been temporarily reassigned.
-- Indicate this by changing their job (JOB) to NULL and their pay
-- (SALARY, BONUS, COMM) values to zero in the EMPLOYEE table.</ph>
UPDATE EMPLOYEE
Modified: db/derby/docs/trunk/src/ref/rrefsqlj31783.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj31783.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj31783.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj31783.dita Tue Jun 13 04:57:07 2006
@@ -24,23 +24,33 @@
</keywords>
</metadata></prolog>
<refbody>
-<section> <p><indexterm>Cursors</indexterm><indexterm>In-place updates</indexterm>The
+<section> <indexterm>Cursors</indexterm><indexterm>In-place updates</indexterm> <p> The
FOR UPDATE clause is an optional part of a <xref href="rrefsqlj41360.dita#rrefsqlj41360">SELECT statement</xref>.
-The FOR UPDATE clause specifies whether the <i>ResultSet</i> of a simple <xref
-href="rrefsqlj41360.dita#rrefsqlj41360">SELECT statement</xref> that meets the requirements for a <i>cursor</i> is
-updatable or not. For more information about updatability, see <xref href="rrefsqlj41360.dita#rrefsqlj41360/sqlj15384">Requirements
-for Updatable Cursors</xref>.</p></section>
+Cursors are read-only by default. The FOR UPDATE clause specifies that the cursor should be updatable, and
+enforces a check during compilation that
+the SELECT statement meets the requirements for an updatable <i>cursor</i>.
+For more information about updatability, see <xref href="rrefsqlj41360.dita#rrefsqlj41360/sqlj15384">Requirements
+for Updatable Cursors</xref>.</p> </section>
<refsyn><title>Syntax</title> <codeblock><b>FOR
{
READ ONLY | FETCH ONLY |
UPDATE [ OF <i><xref href="rrefsimplecolumnname.dita#rrefsimplecolumnname">Simple-column-Name</xref></i> [ , <i><xref
href="rrefsimplecolumnname.dita#rrefsimplecolumnname">Simple-column-Name</xref></i>]* ]
}</b></codeblock> <p><i>Simple-column-Name</i> refers to the names visible
-for the table specified in the FROM clause of the underlying query.</p> <p>Cursors
-are read-only by default. For a cursor to be updatable, you must specify FOR
-UPDATE.</p> <p>The optimizer is able to use an index even if the column in
+for the table specified in the FROM clause of the underlying query.</p>
+</refsyn>
+<section>
+<p><note>The use of the FOR UPDATE clause is not mandatory to obtain an updatable
+JDBC ResultSets. As long as the statement used to generate the JDBC ResultSet meets
+the requirements for updatable cursor, it is sufficient for the JDBC Statement that
+generates the JDBC ResultSet to have concurrency mode
+<codeph>ResultSet.CONCUR_UPDATABLE</codeph> for the ResultSet to be updatable.
+</note></p>
+<p>The optimizer is able to use an index even if the column in
the index is being updated. For more information about how indexes affect
-cursors, see <cite><ph conref="refconrefs.dita#pub/cittuning"></ph></cite>.</p> </refsyn>
+cursors, see <cite><ph
+conref="refconrefs.dita#pub/cittuning"></ph></cite>.</p>
+</section>
<example> <codeblock><b>SELECT RECEIVED, SOURCE, SUBJECT, NOTE_TEXT FROM SAMP.IN_TRAY FOR UPDATE;
</b></codeblock> </example>
</refbody>
Modified: db/derby/docs/trunk/src/ref/rrefsqlj35981.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj35981.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj35981.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj35981.dita Tue Jun 13 04:57:07 2006
@@ -32,14 +32,15 @@
<section><p>The first syntactical form, called a searched delete, removes
all rows identified by the table name and WHERE clause.</p></section>
<section><p>The second syntactical form, called a positioned delete, deletes
-the current row of an open, updatable cursor. If there is no current row or
-if it no longer satisfies the cursor's query, an exception is raised. For
-more information about updatable cursors, see <xref href="rrefsqlj41360.dita#rrefsqlj41360"></xref>.</p></section>
+the current row of an open, updatable cursor. For more information
+about updatable cursors, see <xref
+href="rrefsqlj41360.dita#rrefsqlj41360"></xref>.</p></section>
<section><title>Examples</title> <codeblock><b>DELETE FROM SAMP.IN_TRAY;
stmt.executeUpdate("DELETE FROM SAMP.IN_TRAY WHERE CURRENT OF " +
resultSet.getCursorName())</b></codeblock></section>
-<section><p>A searched delete statement depends on the table being updated,
+<section><title>Statement dependency system</title>
+<p>A searched delete statement depends on the table being updated,
all of its conglomerates (units of storage such as heaps or indexes), and
any other table named in the WHERE clause. A CREATE or DROP INDEX statement
for the target table of a prepared searched delete statement invalidates the
Modified: db/derby/docs/trunk/src/ref/rrefsqlj41360.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj41360.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj41360.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj41360.dita Tue Jun 13 04:57:07 2006
@@ -24,22 +24,23 @@
to guarantee order of results</indexterm></indexterm></keywords>
</metadata></prolog>
<refbody>
+<refsyn><title>Syntax</title> <codeblock><b><i><xref href="rrefsqlj21571.dita#rrefsqlj21571">Query</xref></i>
+[<i><xref href="rrefsqlj13658.dita#rrefsqlj13658">ORDER BY clause</xref></i>]
+[<i><xref href="rrefsqlj31783.dita#rrefsqlj31783">FOR UPDATE clause</xref></i>]
+WITH {RR|RS|CS|UR}</b></codeblock></refsyn>
<section> <p>A SELECT statement consists of a query with an optional <xref
href="rrefsqlj13658.dita#rrefsqlj13658">ORDER BY clause</xref> and an optional <xref href="rrefsqlj31783.dita#rrefsqlj31783">FOR UPDATE clause</xref>.
The SELECT statement is so named because the typical first word of the query
construct is SELECT. (<i>Query</i> includes the VALUES expression and UNION, INTERSECT, and EXCEPT
expressions as well as SELECT expressions).</p> <p>The <xref href="rrefsqlj13658.dita#rrefsqlj13658">ORDER BY clause</xref> guarantees
the ordering of the <i>ResultSet</i>. The <xref href="rrefsqlj31783.dita#rrefsqlj31783">FOR UPDATE clause</xref> makes
-the result an updatable cursor. The SELECT statement supports the FOR FETCH
+the result set's cursor updatable. The SELECT statement supports the FOR FETCH
ONLY clause. The FOR FETCH ONLY clause is synonymous with the FOR READ ONLY
-clause.</p><note type="remember">In order to get an updatable ResultSet, you
-must include a FOR UPDATE clause with the SELECT clause.</note></section>
-<refsyn><title>Syntax</title> <codeblock><b><i><xref href="rrefsqlj21571.dita#rrefsqlj21571">Query</xref></i>
-[<i><xref href="rrefsqlj13658.dita#rrefsqlj13658">ORDER BY clause</xref></i>]
-[<i><xref href="rrefsqlj31783.dita#rrefsqlj31783">FOR UPDATE clause</xref></i>]
-WITH {RR|RS|CS|UR}</b></codeblock> <p>You can set the isolation level in a
-SELECT statement using the WITH {RR|RS|CS|UR} syntax.</p> </refsyn>
-<example> <codeblock><b><ph>-- lists the names of the expression SAL+BONUS+COMM as TOTAL_PAY and
+clause.</p> <p>You can set the isolation level in a
+SELECT statement using the WITH {RR|RS|CS|UR} syntax.</p></section>
+
+<example><title>Example</title> <codeblock><b><ph>-- lists the names of the expression
+SAL+BONUS+COMM as TOTAL_PAY and
-- orders by the new name TOTAL_PAY</ph>
SELECT FIRSTNME, SALARY+BONUS+COMM AS TOTAL_PAY
FROM EMPLOYEE
@@ -56,18 +57,20 @@
WHERE flight_id BETWEEN 'AA1111' AND 'AA1112'
WITH RR;</b></codeblock> <p>A SELECT statement returns a <i>ResultSet</i>.
A <i>cursor</i> is a pointer to a specific row in <i>ResultSet</i>. In Java
-applications, all <i>ResultSets</i> are cursors. A cursor is updatable; that
-is, you can update or delete rows as you step through the <i>ResultSet</i> if
+applications, all <i>ResultSets</i> have an underlying associated SQL
+cursor, often referred to as the result set's cursor. The cursor can
+be updatable, that is, you can update or delete rows as you step through the <i>ResultSet</i> if
the SELECT statement that generated it and its underlying query meet cursor
-updatability requirements, as detailed below. You use a FOR UPDATE clause
-when you want to generate an updatable cursor. <note>The ORDER BY clause
+updatability requirements, as detailed below. The FOR UPDATE clause can be used
+to ensure a compilation check that the SELECT statement meets the requiremments
+of a updatable cursors, or to limit the columns that can be updated.
+<note>The ORDER BY clause
allows you to order the results of the SELECT. Without the ORDER BY clause,
-the results are returned in random order.</note></p><p>If a SELECT statement
-meets the requirements listed below, cursors are updatable only if you specify
-FOR UPDATE in the FOR clause (see <xref href="rrefsqlj31783.dita#rrefsqlj31783"></xref>).</p> </example>
+the results are returned in random order.</note></p> </example>
<section id="sqlj15384"><title>Requirements for updatable cursors and updatable
-ResultSets</title><p>Only simple, single-table SELECT cursors and FORWARD_ONLY
-ResultSets can be updatable. The SELECT statement for updatable ResultSets
+ResultSets</title>
+<p>Only simple, single-table SELECT cursors
+can be updatable. The SELECT statement for updatable ResultSets
has the same syntax as the SELECT statement for updatable cursors. To generate
updatable cursors: <ul>
<li>The SELECT statement must not include an ORDER BY clause.</li>
@@ -78,6 +81,7 @@
<li>Aggregates</li>
<li>GROUP BY clause</li>
<li>HAVING clause</li>
+<li>ORDER BY clause</li>
</ul></li>
<li>The FROM clause in the underlying <i>Query</i> must not have: <ul>
<li>more than one table in its FROM clause</li>
@@ -85,12 +89,17 @@
<li><i><xref href="rrefselectexpression.dita#rrefselectexpression">SelectExpression</xref>s</i></li>
<li>subqueries</li>
</ul></li>
-</ul></p> <p>There is no SQL language statement to <i>assign</i> a name to
-a cursor. Instead, you use the JDBC API to assign names to cursors or retrieve
-system-generated names. For more information, see "Naming or Accessing the
-Name of a Cursor" in Chapter 5 of the <cite><ph conref="refconrefs.dita#pub/citdevelop"></ph></cite>.</p> <p>Cursors
-are read-only by default. For a cursor to be updatable, you must specify FOR
-UPDATE in the FOR clause (see <xref href="rrefsqlj31783.dita#rrefsqlj31783"></xref>).</p> </section>
+</ul></p>
+<note>Cursors are read-only by default. To produce an updatable
+cursor besides meeting the requirements listed above, the concurrency mode for
+the ResultSet must be <codeph>ResultSet.CONCUR_UPDATABLE</codeph> or the SELECT
+statement must have FOR UPDATE in the FOR clause
+(see <xref href="rrefsqlj31783.dita#rrefsqlj31783"></xref>).</note>
+<p>There is no SQL language statement to <i>assign</i> a name to
+a cursor. Instead, one can use the JDBC API to assign names to cursors or retrieve
+system-generated names. For more information, see
+<xref href="../devguide/tdevconcepts41704.dita">Naming or accessing the name of a cursor</xref>
+in the <cite><ph conref="refconrefs.dita#pub/citdevelop"></ph></cite>.</p> </section>
<section><title>Statement dependency system</title> <p>The SELECT depends
on all the tables and views named in the query and the conglomerates (units
of storage such as heaps and indexes) chosen for access paths on those tables.
Modified: db/derby/docs/trunk/src/tools/rtoolsijcomref62772.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsijcomref62772.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsijcomref62772.dita (original)
+++ db/derby/docs/trunk/src/tools/rtoolsijcomref62772.dita Tue Jun 13 04:57:07 2006
@@ -32,12 +32,11 @@
Edition, v 1.4 (J2SE) or higher.</note>
</refsyn>
<section><title>Description</title>
-<p>Creates a scroll insensitive cursor with the name of the <i>Identifier</i>. (It does this by issuing a <i>createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE,
+<p>Creates a scrollable insensitive cursor with the name of the <i>Identifier</i>. (It does this by issuing a <i>createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_READ_ONLY</i>) call and then executing the statement with <i>java.sql.StatementExecuteQuery</i> request on the value of
the String.)
<note>This command only works in a Java 2 Platform,
Standard Edition, v 1.2 (J2SE) or higher environment.</note></p>
-<p>Scroll insensitive cursors are not updatable.</p>
<p>If the <i>String</i> is a statement that does not generate
a result set, the behavior of the underlying database determines whether an
empty result set or an error is issued. If there is an error in executing
@@ -45,7 +44,7 @@
<p>ij sets the cursor name using a <i>java.sql.Statement.setCursorName </i>request. Behavior with respect to duplicate cursor names is controlled
by the underlying database. <ph conref="toolsconrefs.dita#prod/productshortname"></ph> does not allow multiple open cursors
with the same name.</p>
-<p>Once a scrolling cursor has been created, you can use the follow commands
+<p>Once a scrollable cursor has been created, you can use the follow commands
to work with the result set:
<ul>
<li><xref href="rtoolsijcomref94092.dita#rtoolsijcomref94092"/></li>
@@ -62,7 +61,7 @@
<example><title>Example</title>
<codeblock>ij> <b>autocommit off;</b>
ij> <b>get scroll insensitive cursor scrollCursor as
-'SELECT * FROM menu FOR UPDATE OF price';</b>
+'SELECT * FROM menu';</b>
ij> <b>absolute 5 scrollCursor;</b>
COURSE |ITEM |PRICE
-----------------------------------------------
Modified: db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita?rev=413877&r1=413876&r2=413877&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita Tue Jun 13 04:57:07 2006
@@ -38,4 +38,7 @@
FROM Flights</b></codeblock></p>
<p><ph conref="tunconrefs.dita#prod/productshortname"></ph> can get all required data out of the index instead of from
the table.</p>
+<note>If the query produces an updatable result set,
+<ph conref="tunconrefs.dita#prod/productshortname"></ph> will retrieve all
+data from the data pages even if there is an index that covers the query.</note>
</conbody></concept>