db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1399778 - in /db/derby/docs/branches/10.9/src: devguide/cdevconcepts839085.dita ref/rrefjdbc27734.dita
Date Thu, 18 Oct 2012 18:50:39 GMT
Author: chaase3
Date: Thu Oct 18 18:50:39 2012
New Revision: 1399778

URL: http://svn.apache.org/viewvc?rev=1399778&view=rev
Log:
DERBY-5910  Document use of Connection.close() with try-with-resources

Merged patch DERBY-5910-4.diff to 10.9 doc branch from trunk revision 1399767.

Modified:
    db/derby/docs/branches/10.9/src/devguide/cdevconcepts839085.dita
    db/derby/docs/branches/10.9/src/ref/rrefjdbc27734.dita

Modified: db/derby/docs/branches/10.9/src/devguide/cdevconcepts839085.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.9/src/devguide/cdevconcepts839085.dita?rev=1399778&r1=1399777&r2=1399778&view=diff
==============================================================================
--- db/derby/docs/branches/10.9/src/devguide/cdevconcepts839085.dita (original)
+++ db/derby/docs/branches/10.9/src/devguide/cdevconcepts839085.dita Thu Oct 18 18:50:39 2012
@@ -20,8 +20,11 @@ limitations under the License.
 -->
 <concept id="cdevconcepts839085" xml:lang="en-us">
 <title>Explicitly closing Statements, ResultSets, and Connections</title>
-<shortdesc>You should explicitly close <i>Statements</i>, <codeph><i>ResultSets,</i></codeph>
and <codeph><i>Connections</i></codeph> when
-you no longer need them.</shortdesc>
+<shortdesc>You should explicitly close <codeph><i>Statements</i></codeph>,
+<codeph><i>ResultSets</i></codeph>, and <codeph><i>Connections</i></codeph>
when
+you no longer need them, unless you declare them in a
+<codeph><i>try</i></codeph>-with-resources statement (available in
JDK 7 and
+after).</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Explicit close of JDBC objects</indexterm></keywords>
 </metadata></prolog>
@@ -29,9 +32,37 @@ you no longer need them.</shortdesc>
 <p>Connections to <ph conref="../conrefs.dita#prod/productshortname"></ph>
are
 resources external to an application, and the garbage collector will not close
 them automatically. </p>
-<p>For example, close a <i>Statement</i> object using its <codeph><i>close</i></codeph>
method;
-close a <codeph><i>Connection</i></codeph> object using its <codeph><i>close</i></codeph>
method.
-If auto-commit is disabled, active transactions need to be explicitly committed
-or rolled back before closing the connection</p>
+<p>To close a <codeph><i>Statement</i></codeph>,
+<codeph><i>ResultSet</i></codeph>, or <codeph><i>Connection</i></codeph>
object
+that is not declared in a <codeph><i>try</i></codeph>-with-resources
statement,
+use its <codeph><i>close</i></codeph> method. If auto-commit is disabled,
you
+must explicitly commit or roll back active transactions before you close the
+connection.</p>
+<p>Statements, result sets, and connections extend
+<codeph><i>AutoCloseable</i></codeph> in JDK 7 and after. If you
declare a
+connection in a <codeph><i>try</i></codeph>-with-resources statement
and there
+is an error that the code does not catch, the JRE will attempt to close the
+connection automatically.</p>
+<p>Note that a transaction-severity or higher exception causes
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to abort an in-flight
+transaction. But a statement-severity exception does NOT roll back the
+transaction. Also note that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> throws an exception
if
+an attempt is made to close a connection with an in-flight transaction. Suppose
+now that a <codeph><i>Connection</i></codeph> is declared in a 
+<codeph><i>try</i></codeph>-with-resources statement, a transaction
is
+in-flight, and an unhandled statement-severity error occurs inside the
+<codeph><i>try</i></codeph>-with-resources block. In this situation,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> will raise a follow-on
+exception as the JRE exits the <i>try</i>-with-resources block. (For details
on
+error severity levels, see the documentation of the
+<codeph><i>derby.stream.error.logSeverityLevel</i></codeph> property
in the
+<ph conref="../conrefs.dita#pub/citref"></ph>.)</p>
+<p>It is therefore always best to catch errors inside the
+<codeph><i>try</i></codeph>-with-resources block and to either roll
back or
+commit, as appropriate, to ensure that there is no pending transaction when
+leaving the <codeph><i>try</i></codeph>-with-resources block. This
action also
+improves application portability, since DBMSs differ in their semantics when
+trying to close a connection with a pending transaction.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/branches/10.9/src/ref/rrefjdbc27734.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.9/src/ref/rrefjdbc27734.dita?rev=1399778&r1=1399777&r2=1399778&view=diff
==============================================================================
--- db/derby/docs/branches/10.9/src/ref/rrefjdbc27734.dita (original)
+++ db/derby/docs/branches/10.9/src/ref/rrefjdbc27734.dita Thu Oct 18 18:50:39 2012
@@ -28,16 +28,36 @@ exceptions closing</indexterm><indexterm
 <refbody>
 <section><p>A <ph conref="../conrefs.dita#prod/productshortname"></ph>&nbsp;<i>Connection</i>
object
 is not garbage-collected until all other JDBC objects created from that connection
-are explicitly closed or are themselves garbage-collected. Once the connection
+are closed or are themselves garbage-collected. Once the connection
 is closed, no further JDBC requests can be made against objects created from
 the connection. Do not explicitly close the <i>Connection</i> object until
 you no longer need it for executing statements.<indexterm>Connections<indexterm>garbage
 collection of</indexterm></indexterm></p></section>
-<section><p>A session-severity or higher exception causes the connection to
-close and all other JDBC objects against it to be closed. System-severity
-exceptions cause the <ph conref="../conrefs.dita#prod/productshortname"></ph>
system
-to shut down, which not only closes the connection but means that no new connections
-should be created in the current JVM.</p></section>
+<section>
+<p>The <i>Connection</i> interface extends <i>AutoCloseable</i>
in JDK 7 and
+after. If you declare a connection in a <i>try</i>-with-resources statement and
+there is an error that the code does not catch, the JRE will attempt to close
+the connection automatically.</p>
+<p>Note that a transaction-severity or higher exception causes
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to abort an in-flight
+transaction. But a statement-severity exception does NOT roll back the
+transaction. Also note that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> throws an exception
if
+an attempt is made to close a connection with an in-flight transaction. Suppose
+now that a <i>Connection</i> is declared in a <i>try</i>-with-resources
+statement, a transaction is in-flight, and an unhandled statement-severity error
+occurs inside the <i>try</i>-with-resources block. In this situation,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> will raise a follow-on
+exception as the JRE exits the <i>try</i>-with-resources block. (For details
on
+error severity levels, see
+<i><xref href="rrefproper26985.dita#rrefproper26985"></xref></i>.)</p>
+<p>It is therefore always best to catch errors inside the
+<i>try</i>-with-resources block and to either roll back or commit, as
+appropriate, to ensure that there is no pending transaction when leaving the
+<i>try</i>-with-resources block. This action also improves application
+portability, since DBMSs differ in their semantics when trying to close a
+connection with a pending transaction.</p>
+</section>
 <section>
 <p>The following table describes features of <i>Connection</i> methods
that are
 specific to <ph conref="../conrefs.dita#prod/productshortname"></ph>.</p>



Mime
View raw message