svn commit: r1075954 - /db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita

[ch...@apache.org]

Author: chaase3
Date: Tue Mar  1 18:06:54 2011
New Revision: 1075954

URL: http://svn.apache.org/viewvc?rev=1075954&view=rev
Log:
DERBY-5024 Document the behavior of interrupt handling

Modified one Dev Guide topic.

Patches: DERBY-5024-2.diff

Modified:
    db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita

Modified: db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita?rev=1075954&r1=1075953&r2=1075954&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita Tue Mar  1 18:06:54 2011
@@ -20,21 +20,63 @@ limitations under the License.
 -->
 <concept id="cdevdvlp22619" xml:lang="en-us">
 <title>Working with database threads in an embedded environment</title>
-<shortdesc>Do not use <codeph><i>interrupt</i></codeph> calls to notify threads
-that are accessing a database, because <ph conref="../conrefs.dita#prod/productshortname"></ph> will
-catch the <codeph><i>interrupt</i></codeph> call and close the connection
-to the database. Use <codeph><i>wait</i></codeph> and <codeph><i>notify</i></codeph> calls
-instead.</shortdesc>
+<shortdesc>As a rule, do not use <i>Thread.interrupt()</i> calls to signal
+possibly waiting threads that are also accessing a database, because
+<ph conref="../conrefs.dita#prod/productshortname"></ph> may catch the
+interrupt and close the connection to the database. Use <i>wait</i>
+and <i>notify</i> calls instead.</shortdesc>
 <prolog><metadata>
-<keywords><indexterm>Threads<indexterm>sleep and interrupt calls</indexterm><indexterm>notifying</indexterm></indexterm>
+<keywords><indexterm>threads<indexterm>interrupt calls</indexterm><indexterm>notifying</indexterm></indexterm>
 <indexterm>interrupt calls<indexterm>caught by Derby</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <conbody>
-<p>This will not happen in a client/server environment, but if you want your
-application to work in either environment it is good practice to follow this
-rule.</p>
-<p>There are also special considerations when working with more than one database
-thread in an application.</p>
+<p>There are also special considerations when working with more than one
+database thread in an application, as described in
+<xref href="cdevconcepts23499.dita#cdevconcepts23499"></xref>.</p>
+<p>When queries, batches, and statements that wait for database locks run longer
+than expected, you can use interrupts to stop them. If you do, the
+connection will be closed and an exception will be thrown.</p>
+<p>If you design an application whose database threads may see interrupts, you
+should plan for the following behavior:</p>
+<ul>
+<li>If a thread is interrupted and the interrupt status flag is not
+cleared before entering a
+<ph conref="../conrefs.dita#prod/productshortname"></ph> JDBC call, or if the
+thread is interrupted while inside a
+<ph conref="../conrefs.dita#prod/productshortname"></ph> JDBC call, the
+connection that is experiencing the interrupt will be terminated in the
+following situations:
+<ul>
+<li>If a query fetches rows from a database table after the interrupt has 
+occurred</li>
+<li>If the execution of a new element in a batched statement is attempted
+after the interrupt has occurred</li>
+<li>If an interrupt is received while a transaction is waiting for a lock</li>
+</ul>
+<p>If the connection is terminated, the application thread will experience the
+following consequences:</p>
+<ul>
+<li>The JDBC call will raise an <i>SQLException</i> with state "08000"
+("Connection closed by unknown interrupt").</li>
+<li>Outstanding transactional work on that connection will be rolled
+back, and all of its locks will be released.</li>
+<li>The connection cannot be used to execute any further JDBC calls.</li>
+</ul>
+<p>On return from the JDBC call, the <i>Thread.isInterrupted()</i> method
+of the thread will return <i>true</i>, whether or not an exception terminating
+the connection was thrown. That is, even if
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not heed an
+interrupt, the flag will remain set on exit from the JDBC call.</p></li>
+<li>All other connections will remain open. This includes other
+connections which the interrupted thread may be using. These
+connections will remain open at least until the thread tries to
+use one of its other connections. If the thead has neglected to
+clear its interrupted status flag, this connection is also subject to
+termination as described above.</li>
+<li>The application should normally be prepared to catch the 08000 exceptions,
+discard the dead connection, clear the interrupted status of the thread, and
+then restart the transaction in a new connection.</li>
+</ul>
 </conbody>
 </concept>