commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject svn commit: r896266 - in /commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter: ConnectionImpl.java DriverAdapterCPDS.java PooledConnectionImpl.java
Date Tue, 05 Jan 2010 23:20:19 GMT
Author: sebb
Date: Tue Jan  5 23:20:12 2010
New Revision: 896266

URL: http://svn.apache.org/viewvc?rev=896266&view=rev
Log:
Add some Javadoc

Modified:
    commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/ConnectionImpl.java
    commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/DriverAdapterCPDS.java
    commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/PooledConnectionImpl.java

Modified: commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/ConnectionImpl.java
URL: http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/ConnectionImpl.java?rev=896266&r1=896265&r2=896266&view=diff
==============================================================================
--- commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/ConnectionImpl.java
(original)
+++ commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/ConnectionImpl.java
Tue Jan  5 23:20:12 2010
@@ -51,6 +51,7 @@
      *
      * @param pooledConnection The PooledConnection that is calling the ctor.
      * @param connection The JDBC 1.x Connection to wrap.
+     * @param accessToUnderlyingConnectionAllowed if true, then access is allowed to the
underlying connectiion
      */
     ConnectionImpl(PooledConnectionImpl pooledConnection, 
             Connection connection,
@@ -83,6 +84,8 @@
      * {@link DriverAdapterCPDS}, a pooled object may be returned, otherwise
      * delegate to the wrapped jdbc 1.x {@link java.sql.Connection}.
      *
+     * @param sql SQL statement to be prepared
+     * @return the prepared statement
      * @exception SQLException if this connection is closed or an error occurs
      * in the wrapped connection.
      */
@@ -93,7 +96,7 @@
                 (this, pooledConnection.prepareStatement(sql));
         }
         catch (SQLException e) {
-            handleException(e);
+            handleException(e); // Does not return
             return null;
         }
     }
@@ -182,12 +185,18 @@
 
     /**
      * If false, getDelegate() and getInnermostDelegate() will return null.
-     * @return if false, getDelegate() and getInnermostDelegate() will return null
+     * @return true if access is allowed to the underlying connection
+     * @see ConnectionImpl
      */
     public boolean isAccessToUnderlyingConnectionAllowed() {
         return accessToUnderlyingConnectionAllowed;
     }
 
+    /**
+     * Get the delegated connection, if allowed.
+     * @return the internal connection, or null if access is not allowed.
+     * @see #isAccessToUnderlyingConnectionAllowed()
+     */
     public Connection getDelegate() {
         if (isAccessToUnderlyingConnectionAllowed()) {
             return getDelegateInternal();
@@ -196,6 +205,11 @@
         }
     }
 
+    /**
+     * Get the innermost connection, if allowed.
+     * @return the innermost internal connection, or null if access is not allowed.
+     * @see #isAccessToUnderlyingConnectionAllowed()
+     */
     public Connection getInnermostDelegate() {
         if (isAccessToUnderlyingConnectionAllowed()) {
             return super.getInnermostDelegateInternal();

Modified: commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/DriverAdapterCPDS.java
URL: http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/DriverAdapterCPDS.java?rev=896266&r1=896265&r2=896266&view=diff
==============================================================================
--- commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/DriverAdapterCPDS.java
(original)
+++ commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/DriverAdapterCPDS.java
Tue Jan  5 23:20:12 2010
@@ -383,6 +383,7 @@
      * 
      * @param props Connection properties to use when creating new connections.
      * @since 1.3
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setConnectionProperties(Properties props) {
         assertInitializationAllowed();
@@ -400,7 +401,8 @@
      * the code which will deploy this datasource.  It is not used
      * internally.
      *
-     * @return value of description.
+     * @return value of description, may be null.
+     * @see #setDescription(String)
      */
     public String getDescription() {
         return description;
@@ -428,6 +430,7 @@
     /**
      * Set the value of password for the default user.
      * @param v  Value to assign to password.
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setPassword(String v) {
         assertInitializationAllowed();
@@ -448,7 +451,8 @@
     /**
      * Set the value of url used to locate the database for this datasource.
      * @param v  Value to assign to url.
-     */
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
+    */
     public void setUrl(String v) {
         assertInitializationAllowed();
         this.url = v;
@@ -465,6 +469,7 @@
     /**
      * Set the value of default user (login or username).
      * @param v  Value to assign to user.
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setUser(String v) {
         assertInitializationAllowed();
@@ -486,6 +491,7 @@
      * Set the driver classname.  Setting the driver classname cause the 
      * driver to be registered with the DriverManager.
      * @param v  Value to assign to driver.
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setDriver(String v) throws ClassNotFoundException {
         assertInitializationAllowed();
@@ -540,6 +546,7 @@
     /**
      * Flag to toggle the pooling of <code>PreparedStatement</code>s
      * @param v  true to pool statements.
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setPoolPreparedStatements(boolean v) {
         assertInitializationAllowed();
@@ -557,6 +564,8 @@
     /**
      * The maximum number of active statements that can be allocated from
      * this pool at the same time, or non-positive for no limit.
+     * @param maxActive the maximum number of concurrent active statements allowed
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setMaxActive(int maxActive) {
         assertInitializationAllowed();
@@ -566,6 +575,7 @@
     /**
      * The maximum number of statements that can remain idle in the
      * pool, without extra ones being released, or negative for no limit.
+     * @return the value of maxIdle
      */
     public int getMaxIdle() {
         return (this.maxIdle);
@@ -574,6 +584,9 @@
     /**
      * The maximum number of statements that can remain idle in the
      * pool, without extra ones being released, or negative for no limit.
+     * 
+     * @param maxIdle The maximum number of statements that can remain idle
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setMaxIdle(int maxIdle) {
         assertInitializationAllowed();
@@ -585,8 +598,8 @@
      * idle object evictor thread.
      * When non-positive, no idle object evictor thread will be
      * run.
-     *
-     * *see #setTimeBetweenEvictionRunsMillis
+     * @return the value of the evictor thread timer
+     * @see #setTimeBetweenEvictionRunsMillis(int)
      */
     public int getTimeBetweenEvictionRunsMillis() {
         return _timeBetweenEvictionRunsMillis;
@@ -597,8 +610,9 @@
      * idle object evictor thread.
      * When non-positive, no idle object evictor thread will be
      * run.
-     *
-     * *see #getTimeBetweenEvictionRunsMillis
+     * @param timeBetweenEvictionRunsMillis
+     * @see #getTimeBetweenEvictionRunsMillis()
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setTimeBetweenEvictionRunsMillis(
             int timeBetweenEvictionRunsMillis) {
@@ -624,9 +638,11 @@
      * When a negative value is supplied, <tt>ceil({*link #numIdle})/abs({*link #getNumTestsPerEvictionRun})</tt>
      * tests will be run.  I.e., when the value is <i>-n</i>, roughly one <i>n</i>th
of the
      * idle objects will be tested per run.
-     *
-     * *see #getNumTestsPerEvictionRun
-     * *see #setTimeBetweenEvictionRunsMillis
+     * 
+     * @param numTestsPerEvictionRun number of statements to examine per run
+     * @see #getNumTestsPerEvictionRun()
+     * @see #setTimeBetweenEvictionRunsMillis(int)
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
         assertInitializationAllowed();
@@ -651,9 +667,10 @@
      * (if any).
      * When non-positive, no objects will be evicted from the pool
      * due to idle time alone.
-     *
-     * *see #getMinEvictableIdleTimeMillis
-     * *see #setTimeBetweenEvictionRunsMillis
+     * @param minEvictableIdleTimeMillis minimum time to set (in ms)
+     * @see #getMinEvictableIdleTimeMillis()
+     * @see #setTimeBetweenEvictionRunsMillis(int)
+     * @throws IllegalStateException if {@link #getPooledConnection()} has been called
      */
     public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis) {
         assertInitializationAllowed();

Modified: commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/PooledConnectionImpl.java
URL: http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/PooledConnectionImpl.java?rev=896266&r1=896265&r2=896266&view=diff
==============================================================================
--- commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/PooledConnectionImpl.java
(original)
+++ commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/cpdsadapter/PooledConnectionImpl.java
Tue Jan  5 23:20:12 2010
@@ -88,6 +88,8 @@
 
     /**
      * Wrap the real connection.
+     * @param connection the connection to be wrapped
+     * @param pool the pool to use
      */
     PooledConnectionImpl(Connection connection, KeyedObjectPool pool) {
         this.connection = connection;
@@ -105,7 +107,7 @@
     }
 
     /**
-     * Add an event listener.
+     * {@inheritDoc}
      */
     public void addConnectionEventListener(ConnectionEventListener listener) {
         if (!eventListeners.contains(listener)) {
@@ -126,7 +128,7 @@
      * <code>PooledConnection</code> so that it may not be used 
      * to generate any more logical <code>Connection</code>s.
      *
-     * @exception SQLException if an error occurs
+     * @exception SQLException if an error occurs or the connection is already closed
      */
     public void close() throws SQLException {        
         assertOpen();
@@ -153,7 +155,7 @@
     }
 
     /**
-     * Throws an SQLException, if isClosed() is true
+     * Throws an SQLException, if isClosed is true
      */
     private void assertOpen() throws SQLException {
         if (isClosed) {
@@ -165,6 +167,7 @@
      * Returns a JDBC connection.
      *
      * @return The database connection.
+     * @throws SQLException if the connection is not open or the previous logical connection
is still open
      */
     public Connection getConnection() throws SQLException {
         assertOpen();
@@ -183,7 +186,7 @@
     }
 
     /**
-     * Remove an event listener.
+     * {@inheritDoc}
      */
     public void removeConnectionEventListener(
             ConnectionEventListener listener) {
@@ -230,8 +233,9 @@
     // The following code implements a PreparedStatement pool
 
     /**
-     * Create or obtain a {*link PreparedStatement} from my pool.
-     * @return a {*link PoolablePreparedStatement}
+     * Create or obtain a {@link PreparedStatement} from my pool.
+     * @param sql the SQL statement
+     * @return a {@link PoolablePreparedStatement}
      */
     PreparedStatement prepareStatement(String sql) throws SQLException {
         if (pstmtPool == null) {
@@ -249,8 +253,20 @@
     }
 
     /**
-     * Create or obtain a {*link PreparedStatement} from my pool.
-     * @return a {*link PoolablePreparedStatement}
+     * Create or obtain a {@link PreparedStatement} from my pool.
+     * @param sql a <code>String</code> object that is the SQL statement to
+     *            be sent to the database; may contain one or more '?' IN
+     *            parameters
+     * @param resultSetType a result set type; one of 
+     *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
+     *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
+     *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
+     * @param resultSetConcurrency a concurrency type; one of
+     *         <code>ResultSet.CONCUR_READ_ONLY</code> or
+     *         <code>ResultSet.CONCUR_UPDATABLE</code>
+     * 
+     * @return a {@link PoolablePreparedStatement}
+     * @see Connection#prepareStatement(String, int, int)
      */
     PreparedStatement prepareStatement(String sql, int resultSetType, 
                                        int resultSetConcurrency) 
@@ -270,8 +286,15 @@
     }
 
     /**
-     * Create or obtain a {*link PreparedStatement} from my pool.
-     * @return a {*link PoolablePreparedStatement}
+     * Create or obtain a {@link PreparedStatement} from my pool.
+     * @param sql an SQL statement that may contain one or more '?' IN
+     *        parameter placeholders
+     * @param autoGeneratedKeys a flag indicating whether auto-generated keys 
+     *        should be returned; one of
+     *        <code>Statement.RETURN_GENERATED_KEYS</code> or
+     *        <code>Statement.NO_GENERATED_KEYS</code>  
+     * @return a {@link PoolablePreparedStatement}
+     * @see Connection#prepareStatement(String, int)
      */
     PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) 
             throws SQLException {



Mime
View raw message