Thanks for tacking this one, Kim! Some suggestions below inlined:
> WORKING WITH DATABASE THREADS IN AN EMBEDDED ENVIRONMENT
> Do not use interrupt calls to notify java.lang.Thread objects that
> are accessing a database, because Derby may catch the interrupt call
> and close the connection to the database. Use wait and notify calls
Suggest improvement of this sentence:
"Do not normally use Thread#interrupt to signal possibly waiting
threads that are also accessing a database because Derby may catch the
interrupt and close the connection to the database. Use wait and
notify calls instead."
> 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.
<... removed paragraph, see below>
> There are also special considerations when working with more than
> one database thread in an application, as described in Working with
> multiple threads sharing a single connection.
Move next paragraph to #4:
> 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
"Connection" -> "connection" throughout, unless referring to the
actual class java.sql.Connection
> If you design an application that experiences Thread interrupts, you
"If you design an application whose database threads may see
> should plan for the following behavior:
> * If a Thread is interrupted and the interrupt status flag is
"Thread" -> "thread" throughout, unless referring to the actual class java.lang.Thread.
> not cleared before entering a Derby JDBC call, or if the
> Thread is interrupted while inside a Derby JDBC call, the
> Connection that is experiencing the interrupt will be
> terminated in the following situations:
> o If a query fetches rows from a database table after the interrupt has occurred
> o If the execution of a new element in a batched statement is attempted after the interrupt has occurred
> o If an interrupt is received while a transaction is waiting for a lock
> If the Connection is terminated, the application will experience the following consequences:
"application" -> "application thread"
> o The JDBC call will raise an 08000 exception
> ("Connection closed by unknown interrupt").
"an 08000 exception" -> an SQLException with state "08000"
> o Outstanding transactional work on that Connection will be rolled back, and all of its locks will be released.
> o The Connection will not execute any further JDBC calls.
"will not" -> "can not be used to"
> On return from the interrupted JDBC call, the isInterrupted() method of the Thread will return true, whether the Connection has been terminated or not.
"On return from the JDBC call, Thread#isInterrupted will return
true, whether an exception was thrown terminating the connection, or
not. That is, even if Derby doesn't heed an interrupt, the flag will
remain set on exit from the JDBC call."
> All other Connections will remain active. This includes other
"active" -> "open" above and below.
> Connections which the interrupted Thread may be using.
> These Connections will remain active at least until the Thread,
> still with its interrupted status set, tries to use another
> connection, in which case this Connection is also subject to
These connections will remain open at least until the thread tries to
use another of its other connections. If the thead has neglected to
clear its interrupted flag, this connection is also subject to
termination as described above.
> The application should catch the 08000 exceptions, discard the
> dead Connection, clear the interrupted status of the Thread, and
> then restart the transaction in a new Connection.
"should" -> "should normally be prepared to"