db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r681430 - in /db/derby/docs/branches/10.4/src: devguide/ ref/
Date Thu, 31 Jul 2008 18:24:03 GMT
Author: chaase3
Date: Thu Jul 31 11:24:02 2008
New Revision: 681430

URL: http://svn.apache.org/viewvc?rev=681430&view=rev
Log:
DERBY-3579: The Developer's Guide incorrectly describes the behavior of transactions inside
procedures and functions

Merged DERBY-3579-3.diff to 10.4 docs branch from trunk revision 679509.

Modified:
    db/derby/docs/branches/10.4/src/devguide/cdevconcepts29416.dita
    db/derby/docs/branches/10.4/src/devguide/cdevconcepts32861.dita
    db/derby/docs/branches/10.4/src/devguide/cdevconcepts36881.dita
    db/derby/docs/branches/10.4/src/devguide/cdevconcepts38375.dita
    db/derby/docs/branches/10.4/src/devguide/cdevdgpref11181.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial16181.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial28907.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial29620.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial41728.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial42117.dita
    db/derby/docs/branches/10.4/src/devguide/cdevspecial847513.dita
    db/derby/docs/branches/10.4/src/ref/crefjavgcasyn.dita

Modified: db/derby/docs/branches/10.4/src/devguide/cdevconcepts29416.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevconcepts29416.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevconcepts29416.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevconcepts29416.dita Thu Jul 31 11:24:02 2008
@@ -47,13 +47,13 @@
 and issue multiple commits before closing the cursor, but the cursor must
 be repositioned before any statement following the commit. If this is attempted
 with auto-commit on, an error is generated. </p></li>
-<li><i>Database-side JDBC Procedures (procedures using nested connections)</i>

- <p>You cannot execute procedures within SQL statements if those procedures
-perform a commit or rollback on the current connection. Since in the auto-commit
+<li><i>Database-side JDBC routines (routines using nested connections)</i>

+<p>You cannot execute functions within SQL statements if those functions
+perform a commit or rollback on the current connection. Since in auto-commit
 mode all SQL statements are implicitly committed, <ph conref="../conrefs.dita#prod/productshortname"></ph>
turns
-off auto-commit during execution of database-side procedures and turns it
-back on when the method completes.</p><p>Procedures that use nested connections
-are not permitted to turn auto-commit on or off or to commit or roll back.</p></li>
+off auto-commit during execution of database-side routines and turns it
+back on when the statement completes.</p><p>Routines that use nested connections
+are not permitted to turn auto-commit on or off.</p></li>
 <li><i>Table-level locking and the SERIALIZABLE isolation level</i>   <p>When
 an application uses table-level locking and the SERIALIZABLE isolation level,
 all statements that access tables hold at least shared table locks. Shared
@@ -79,7 +79,7 @@
 <entry colname="3">Commit() or rollback() begins a transaction.</entry>
 </row>
 <row>
-<entry colname="1">Database-side JDBC procedures (routines using nested connections)</entry>
+<entry colname="1">Database-side JDBC routines (routines that use nested connections)</entry>
 <entry colname="2">Auto-commit is turned off.</entry>
 <entry colname="3">Works (no explicit commits or rollbacks are allowed).</entry>
 </row>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevconcepts32861.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevconcepts32861.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevconcepts32861.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevconcepts32861.dita Thu Jul 31 11:24:02 2008
@@ -50,7 +50,7 @@
 <b>// note: do not catch such exceptions in database-side methods; 
 // catch such exceptions only at the outermost level of 
 // application code. 
-// See <xref href="cdevspecial41728.dita#cdevspecial41728">Database-side JDBC procedures
and SQLExceptions</xref>. </b> 
+// See <xref href="cdevspecial41728.dita#cdevspecial41728"></xref>. </b>

 catch (SQLException se) { 
     if (se.getSQLState().equals("40001")) { 
         <b>// it was chosen as a victim of a deadlock. 

Modified: db/derby/docs/branches/10.4/src/devguide/cdevconcepts36881.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevconcepts36881.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevconcepts36881.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevconcepts36881.dita Thu Jul 31 11:24:02 2008
@@ -27,14 +27,14 @@
 to multiple databases</indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>Within the scope of one <codeph><i>Connection</i></codeph>,
you access
+<p>Within the scope of one <i>Connection</i>, you access
 only a single <ph conref="../conrefs.dita#prod/productshortname"></ph> database.
-(Database-side JDBC procedures can allow you to access more than one database
-in some circumstances.) A single application might allow one or more <codeph><i>Connections</i></codeph>
to <ph
+(Database-side JDBC routines can allow you to access more than one database
+in some circumstances.) A single application might allow one or more <i>Connections</i>
to <ph
 conref="../conrefs.dita#prod/productshortname"></ph>, either to a single database
 or to many different databases, provided that all the databases are within
 the same system.</p>
-<p>With DriverManager, you use the connection URL as an argument to get the <codeph><i>getConnection</i></codeph>
method
+<p>With DriverManager, you use the connection URL as an argument to get the <i>getConnection</i>
method
 to specify which database to connect to and other details.</p>
 <p>The following example shows an application establishing three separate
 connections to two different databases in the current system.</p>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevconcepts38375.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevconcepts38375.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevconcepts38375.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevconcepts38375.dita Thu Jul 31 11:24:02 2008
@@ -19,16 +19,16 @@
 limitations under the License.
 -->
 <concept id="cdevconcepts38375" xml:lang="en-us">
-<title>The JDBC Connection and Transaction Model</title>
+<title>The JDBC connection and transaction model</title>
 <shortdesc>Session and transaction capabilities for SQL are handled through
-JDBC procedures, not by SQL commands.</shortdesc>
+JDBC routines, not by SQL commands.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>JDBC Connections</indexterm><indexterm>Transactions</indexterm>
+<keywords><indexterm>JDBC connections</indexterm><indexterm>Transactions</indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
 <p>JDBC defines a system session and transaction model for database access.
 A <i>session</i> is the duration of one connection to the database and is
-handled by a JDBC <codeph><i>Connection</i></codeph> object.</p>
+handled by a JDBC <i>Connection</i> object.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevdgpref11181.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevdgpref11181.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevdgpref11181.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevdgpref11181.dita Thu Jul 31 11:24:02 2008
@@ -26,6 +26,6 @@
 <conbody>
 <p>It describes basic <ph conref="../conrefs.dita#prod/productshortname"></ph>
concepts,
 such as how you create and access <ph conref="../conrefs.dita#prod/productshortname"></ph>
databases
-through JDBC procedures and how you can deploy <ph conref="../conrefs.dita#prod/productshortname"></ph>
applications.</p>
+through JDBC routines and how you can deploy <ph conref="../conrefs.dita#prod/productshortname"></ph>
applications.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial.dita Thu Jul 31 11:24:02 2008
@@ -21,7 +21,7 @@
 <title>Derby server-side programming</title>
 <shortdesc>This section discusses special programming for <ph conref="../conrefs.dita#prod/productshortname"></ph>.</shortdesc>
 <conbody>
-<p>In particular, this section discusses how to program database-side JDBC procedures,
+<p>In particular, this section discusses how to program database-side JDBC routines,
 triggers, and table functions.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial16181.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial16181.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial16181.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial16181.dita Thu Jul 31 11:24:02 2008
@@ -19,20 +19,20 @@
 limitations under the License.
 -->
 <concept id="cdevspecial16181" xml:lang="en-us">
-<title>Database-side JDBC procedures using non-nested connections</title>
-<shortdesc>A database-side JDBC procedure can create a new connection instead
-of using a nested connection. Statements executed in the procedure will be
+<title>Database-side JDBC routines using non-nested connections</title>
+<shortdesc>A database-side JDBC routine can create a new connection instead
+of using a nested connection. Statements executed in the routine will be
 part of a different transaction, and so can issue commits and rollbacks.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>Database-side JDBC procedures<indexterm>using non-nested
+<keywords><indexterm>Database-side JDBC routines<indexterm>using non-nested
 connections</indexterm></indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>Such procedures can connect to a database different from the one to which
-the parent SQL statement that called it is connected. The procedure does not
-use the same transaction or <i>Connection</i>. It establishes a new <codeph><i>Connection</i></codeph>
and
+<p>Such a routine can connect to a database different from the one to which
+the parent SQL statement that called it is connected. The routine does not
+use the same transaction or <i>Connection</i>. It establishes a new <i>Connection</i>
and
 transaction.</p>
-<note>If database-side JDBC procedures do not use nested connections, this
+<note>If database-side JDBC routines do not use nested connections, this
 means that they are operating outside of the normal DBMS transaction control,
 so it is not good practice to use them indiscriminately.</note>
 </conbody>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial28907.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial28907.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial28907.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial28907.dita Thu Jul 31 11:24:02 2008
@@ -19,23 +19,23 @@
 limitations under the License.
 -->
 <concept id="cdevspecial28907" xml:lang="en-us">
-<title>Requirements for database-side JDBC procedures using nested connections</title>
+<title>Requirements for database-side JDBC routines using nested connections</title>
 <shortdesc>In order to preserve transactional atomicity, database-side JDBC
-procedures that use nested connections have the following limitations.</shortdesc>
+routines that use nested connections have the following limitations.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Nested connections<indexterm>limitations of</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
 <p> <ul>
-<li>Cannot issue a commit or rollback, unless called within a CALL statement.
+<li>Can issue a commit or rollback only within a procedure (not a function).
   </li>
-<li>Cannot change connection attributes such as auto-commit.  </li>
+<li>Cannot change the auto-commit connection attribute.</li>
 <li>Cannot modify the data in a table used by the parent statement that called
-the procedure, using INSERT, UPDATE, or DELETE. For example, if a SELECT statement
+the routine, using INSERT, UPDATE, or DELETE. For example, if a SELECT statement
 using the <i>T</i> table calls the <codeph><i>changeTables</i></codeph>
procedure, <codeph><i>changeTables</i></codeph> cannot
-modify data in the <codeph><i>T</i> table.</codeph>  </li>
-<li>Cannot drop a table used by the statement that called the procedure.</li>
+modify data in the <i>T</i> table. </li>
+<li>Cannot drop a table used by the statement that called the routine.</li>
 <li>Cannot be in a class whose static initializer executes DDL statements.</li>
 </ul>In addition, the Connection object that represents the nested connection
 always has its auto-commit mode set to false.</p>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial29620.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial29620.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial29620.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial29620.dita Thu Jul 31 11:24:02 2008
@@ -19,29 +19,30 @@
 limitations under the License.
 -->
 <concept id="cdevspecial29620" xml:lang="en-us">
-<title>Database-side JDBC procedures and nested connections</title>
-<shortdesc>Most database-side JDBC Procedures need to share the same transaction
+<title>Database-side JDBC routines and nested connections</title>
+<shortdesc>Most database-side JDBC routines need to share the same transaction
 space as the statements that called them.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Nested connections<indexterm>getting</indexterm></indexterm>
-<indexterm>Database-side JDBC procedures<indexterm>using nested connections</indexterm></indexterm>
-<indexterm>Nested connections<indexterm>getting</indexterm></indexterm></keywords>
+<indexterm>Database-side JDBC routines<indexterm>using nested connections</indexterm></indexterm>
+</keywords>
 </metadata></prolog>
 <conbody>
 <p>The reasons for this are:</p>
 <ul>
 <li>to avoid blocking and deadlocks</li>
-<li>to ensure that any updates done from within the method are atomic with
+<li>to ensure that any updates done from within the routine are atomic with
 the outer transaction</li>
 </ul>
-<p>In order to use the same transaction, the procedure must use the same connection
-as the parent SQL statement in which the method was executed. Connections
+<p>In order to use the same transaction, the routine must use the same connection
+as the parent SQL statement in which the routine was executed. Connections
 re-used in this way are called <i>nested connections</i>.</p>
-<p>Use the connection URL <i>jdbc:default:connection</i> to re-use the
current <codeph><i>Connection</i></codeph>.</p>
-<p>The Database Connection URL <i>jdbc:default:connection</i> allows a
Java method
+<p>Use the connection URL <i>jdbc:default:connection</i> to re-use the
current <i>Connection</i>.</p>
+<p>The database donnection URL <i>jdbc:default:connection</i> allows a
Java method
 to get the <i>Connection</i> of the SQL statement that called it. This is
-the standard (SQL standard, Part 13 SQL Routines and Java) mechanism to obtain
-the nested connection object. The method would get a <codeph><i>Connection</i></codeph>:</p>
+the standard (SQL standard, Part 13, SQL Routines and Java) mechanism to obtain
+the nested connection object. The method would get a <i>Connection</i>
+as follows:</p>
 <codeblock>Connection conn = DriverManager.getConnection(
     "jdbc:default:connection");</codeblock>
 <p>URL attributes are not supported as part of this connection URL. Any URL

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial41728.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial41728.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial41728.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial41728.dita Thu Jul 31 11:24:02 2008
@@ -19,17 +19,17 @@
 limitations under the License.
 -->
 <concept id="cdevspecial41728" xml:lang="en-us">
-<title>Database-side JDBC procedures and SQLExceptions</title>
-<shortdesc>It is possible to code database-side procedures, like application-side
+<title>Database-side JDBC routines and SQLExceptions</title>
+<shortdesc>It is possible to code database-side routines, like application-side
 methods, to catch <i>SQLExceptions</i>. SQLExceptions that are caught within
-a procedure are hidden from the calling application code.</shortdesc>
+a routine are hidden from the calling application code.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>SQLExceptions<indexterm>importance of not catching
within
-database-side procedures</indexterm></indexterm><indexterm>Database-side
JDBC
-procedures<indexterm>and SQLExceptions</indexterm></indexterm></keywords>
+database-side routines</indexterm></indexterm><indexterm>Database-side
JDBC
+routines<indexterm>and SQLExceptions</indexterm></indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>When such <codeph><i>SQLExceptions</i></codeph> are of transaction
severity
+<p>When such <i>SQLExceptions</i> are of transaction severity
 (such as deadlocks), this "hiding" of the exception causes unexpected problems.</p>
 <p>This is because errors of transaction severity roll back work already done
 by a transaction (not just the piece executed by the called method) and silently
@@ -53,7 +53,7 @@
 <p>Not all database vendors handle nested deadlocks the same way. For this
 and other reasons, it is not possible to write portable SQL-invoking methods.
 However, it is possible to write SQL-invoking methods that behave identically <i>regardless
-of whether you invoke them in the application or as a procedure in the database</i>.</p>
+of whether you invoke them in the application or as a routine in the database</i>.</p>
 <p>In order to ensure identical application- and database-side handling of
 nested errors, code try-catch blocks to check for the severity of exceptions
 as follows:</p>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial42117.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial42117.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial42117.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial42117.dita Thu Jul 31 11:24:02 2008
@@ -18,17 +18,17 @@
 limitations under the License.
 -->
 <concept id="cdevspecial42117" xml:lang="en-us">
-<title>Programming database-side JDBC procedures</title>
+<title>Programming database-side JDBC routines</title>
 <shortdesc>Methods invoked within an application are called application-side
 methods. Methods invoked within <ph conref="../conrefs.dita#prod/productshortname"></ph>
are
-called database-side procedures.</shortdesc>
+called database-side routines.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>Database-side JDBC procedures</indexterm></keywords>
+<keywords><indexterm>Database-side JDBC routines</indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>An application-side method can be exactly the same as a database-side procedure.
+<p>An application-side method can be exactly the same as a database-side routine.
 The only difference is where you invoke them. You write the method only once.
-Where you invoke the method-within the application or within an SQL statement-determines
+Where you invoke the method--within the application or within an SQL statement--determines
 whether it is an "application-side" or a "database-side" method. </p>
 </conbody>
 </concept>

Modified: db/derby/docs/branches/10.4/src/devguide/cdevspecial847513.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/devguide/cdevspecial847513.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/devguide/cdevspecial847513.dita (original)
+++ db/derby/docs/branches/10.4/src/devguide/cdevspecial847513.dita Thu Jul 31 11:24:02 2008
@@ -23,19 +23,16 @@
 <shortdesc>If a procedure uses only IN parameters, <ph conref="../conrefs.dita#prod/productshortname"></ph>
can
 execute the procedure by using the SQL CALL command. A stored procedure with
 IN, OUT, or INOUT parameters can be invoked from a client application by using
-the CallableStatement method.</shortdesc>
+a <i>CallableStatement</i>.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>Database-side JDBC procedures<indexterm>example of
connecting
-to different database</indexterm></indexterm></keywords>
+<keywords><indexterm>Database-side JDBC procedures<indexterm>invoking with
CALL command</indexterm></indexterm></keywords>
 </metadata></prolog>
 <conbody>
 <p>You can invoke the procedure in an SQL statement such as the following:</p>
 <codeblock><b>CALL MYPROC()</b></codeblock>
-<note>You cannot roll back this statement, because commits occur within the
-procedure itself. Procedures that use nested connections, on the other hand,
-are not permitted to commit or roll back and can therefore be rolled back
-after the calling statement.</note>
-<p>You can also use the CALL command to execute a procedure that does return
+<note>You can roll back a CALL statement only if no commits or rollbacks
+occur within the specified procedure.</note>
+<p>You can also use the CALL command to execute a routine that returns
 a value, but you will not be able to access the value.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/branches/10.4/src/ref/crefjavgcasyn.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/crefjavgcasyn.dita?rev=681430&r1=681429&r2=681430&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/crefjavgcasyn.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/crefjavgcasyn.dita Thu Jul 31 11:24:02 2008
@@ -23,7 +23,7 @@
 <conbody>
 <p><ph conref="../conrefs.dita#prod/productshortname"></ph> also supports
 the following SQL standard syntax to obtain a reference to the current connection
-in a database-side JDBC procedure or method:  <codeblock><b>jdbc:default:connection</b></codeblock></p>
+in a database-side JDBC routine:  <codeblock><b>jdbc:default:connection</b></codeblock></p>
 </conbody>
 </concept>
 



Mime
View raw message