db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1075954 - /db/derby/docs/trunk/src/devguide/cdevdvlp22619.dita
Date Tue, 01 Mar 2011 18:06:55 GMT
Author: chaase3
Date: Tue Mar  1 18:06:54 2011
New Revision: 1075954

URL: http://svn.apache.org/viewvc?rev=1075954&view=rev
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
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>
-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>
+<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>
-<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>
-<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
-<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>
+<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:
+<li>If a query fetches rows from a database table after the interrupt has 
+<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>
+<p>If the connection is terminated, the application thread will experience the
+following consequences:</p>
+<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>
+<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>

View raw message