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 {
