svn commit: r1399767 - in /db/derby/docs/trunk/src: devguide/cdevconcepts839085.dita ref/rrefjdbc27734.dita

[ch...@apache.org]

Author: chaase3
Date: Thu Oct 18 18:28:24 2012
New Revision: 1399767

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

Modified 1 Developer's Guide and 1 Reference Manual topic.

Patch: DERBY-5910-4.diff

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

Modified: db/derby/docs/trunk/src/devguide/cdevconcepts839085.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts839085.dita?rev=1399767&r1=1399766&r2=1399767&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts839085.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts839085.dita Thu Oct 18 18:28:24 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/trunk/src/ref/rrefjdbc27734.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc27734.dita?rev=1399767&r1=1399766&r2=1399767&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc27734.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc27734.dita Thu Oct 18 18:28:24 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>