Return-Path: 
 <commits-return-10014-apmail-commons-commits-archive=commons.apache.org@commons.apache.org>
Delivered-To: apmail-commons-commits-archive@minotaur.apache.org
Received: (qmail 66703 invoked from network); 23 Dec 2009 00:08:22 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 23 Dec 2009 00:08:22 -0000
Received: (qmail 39673 invoked by uid 500); 23 Dec 2009 00:08:22 -0000
Delivered-To: apmail-commons-commits-archive@commons.apache.org
Received: (qmail 39580 invoked by uid 500); 23 Dec 2009 00:08:21 -0000
Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@commons.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@commons.apache.org>
List-Post: <mailto:commits@commons.apache.org>
List-Id: <commits.commons.apache.org>
Reply-To: dev@commons.apache.org
Delivered-To: mailing list commits@commons.apache.org
Received: (qmail 39571 invoked by uid 99); 23 Dec 2009 00:08:21 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 23 Dec 2009 00:08:21 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 23 Dec 2009 00:08:19 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 9E330238898B; Wed, 23 Dec 2009 00:07:58 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r893360 - in /commons/proper/dbcp/trunk:
 src/java/org/apache/commons/dbcp/BasicDataSource.java
 src/test/org/apache/commons/dbcp/TestBasicDataSource.java xdocs/changes.xml
Date: Wed, 23 Dec 2009 00:07:58 -0000
To: commits@commons.apache.org
From: psteitz@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20091223000758.9E330238898B@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: psteitz
Date: Wed Dec 23 00:07:57 2009
New Revision: 893360

URL: http://svn.apache.org/viewvc?rev=893360&view=rev
Log:
Clarified javadoc for BasicDataSource close() method.  JIRA:DBCP-312.

Modified:
    commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java
    commons/proper/dbcp/trunk/src/test/org/apache/commons/dbcp/TestBasicDataSource.java
    commons/proper/dbcp/trunk/xdocs/changes.xml

Modified: commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java
URL: http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java?rev=893360&r1=893359&r2=893360&view=diff
==============================================================================
--- commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java (original)
+++ commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java Wed Dec 23 00:07:57 2009
@@ -1289,12 +1289,20 @@
     protected boolean closed;
 
     /**
-     * Close and release all connections that are currently stored in the
-     * connection pool associated with our data source.  All open (active)
-     * connection remain open until closed.  Once the data source has
-     * been closed, no more connections can be obtained.
+     * <p>Closes and releases all idle connections that are currently stored in the connection pool
+     * associated with this data source.</p>
      *
-     * @throws SQLException if a database error occurs
+     * <p>Connections that are checked out to clients when this method is invoked are not affected.  
+     * When client applications subsequently invoke {@link Connection#close()} to return
+     * these connections to the pool, the underlying JDBC connections are closed.</p>
+     * 
+     * <p>Attempts to acquire connections using {@link #getConnection()} after this method has been
+     * invoked result in SQLExceptions.<p>
+     * 
+     * <p>This method is idempotent - i.e., closing an already closed BasicDataSource has no effect
+     * and does not generate exceptions.</p>
+     * 
+     * @throws SQLException if an error occurs closing idle connections
      */
     public synchronized void close() throws SQLException {
         closed = true;

Modified: commons/proper/dbcp/trunk/src/test/org/apache/commons/dbcp/TestBasicDataSource.java
URL: http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/src/test/org/apache/commons/dbcp/TestBasicDataSource.java?rev=893360&r1=893359&r2=893360&view=diff
==============================================================================
--- commons/proper/dbcp/trunk/src/test/org/apache/commons/dbcp/TestBasicDataSource.java (original)
+++ commons/proper/dbcp/trunk/src/test/org/apache/commons/dbcp/TestBasicDataSource.java Wed Dec 23 00:07:57 2009
@@ -109,6 +109,18 @@
         // both wrapper and raw active connection should be closed
         assertTrue(activeConnection.isClosed());
         assertTrue(rawActiveConnection.isClosed());
+        
+        // Verify SQLException on getConnection after close
+        try {
+            activeConnection = getConnection();
+            fail("Expecting SQLException");
+        } catch (SQLException ex) {
+            // Expected
+        }
+        
+        // Redundant close is OK
+        ds.close();
+        
     }
 
     public void testSetProperties() throws Exception {

Modified: commons/proper/dbcp/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/xdocs/changes.xml?rev=893360&r1=893359&r2=893360&view=diff
==============================================================================
--- commons/proper/dbcp/trunk/xdocs/changes.xml (original)
+++ commons/proper/dbcp/trunk/xdocs/changes.xml Wed Dec 23 00:07:57 2009
@@ -38,6 +38,11 @@
     <title>Commons DBCP Release Notes</title>
   </properties>
   <body>
+    <release version="1.4.1" date="TBD">
+      <action dev="psteitz" type="update" issue="DBCP-312" due-to="Glen Mazza">
+        Clarified javadoc for BasicDataSource close() method.
+      </action>
+    </release>
     <release version="1.4" date="TBD" description="This release includes
      new features as well as bug fixes and enhancements.  Some bug fixes
      change semantics (e.g. connection close is now idempotent).  The 1.3
@@ -233,6 +238,8 @@
         both getter and setter for _pool synchronized.
       </action> 
     </release>
+    <release version="1.3.1" date="TBD" description="Compatability release"
+     for JDBC 3. See version 1.4.1 description."/>
     <release version="1.3" date="TBD" description="Compatability release
      for JDBC 3.  See version 1.4 description."/>
     <release version="1.2.2" date="2007-04-04"