You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ps...@apache.org on 2007/01/01 23:05:31 UTC
svn commit: r491655 - in
/jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons:
dbcp/BasicDataSource.java dbcp/BasicDataSourceFactory.java
dbcp/ConnectionFactory.java dbcp/DelegatingCallableStatement.java
jocl/JOCLContentHandler.java
Author: psteitz
Date: Mon Jan 1 14:05:30 2007
New Revision: 491655
URL: http://svn.apache.org/viewvc?view=rev&rev=491655
Log:
Javadoc fixes.
Modified:
jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java
jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSourceFactory.java
jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/ConnectionFactory.java
jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/DelegatingCallableStatement.java
jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/jocl/JOCLContentHandler.java
Modified: jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java?view=diff&rev=491655&r1=491654&r2=491655
==============================================================================
--- jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java (original)
+++ jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSource.java Mon Jan 1 14:05:30 2007
@@ -50,10 +50,26 @@
*/
protected boolean defaultAutoCommit = true;
+ /**
+ * Returns the default auto-commit property.
+ *
+ * @return true if default auto-commit is enabled
+ */
public synchronized boolean getDefaultAutoCommit() {
return this.defaultAutoCommit;
}
+ /**
+ * <p>Sets default auto-commit state of connections returned by this
+ * datasource.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param defaultAutoCommit default auto-commit value
+ */
public synchronized void setDefaultAutoCommit(boolean defaultAutoCommit) {
this.defaultAutoCommit = defaultAutoCommit;
this.restartNeeded = true;
@@ -65,6 +81,11 @@
*/
protected Boolean defaultReadOnly = null;
+ /**
+ * Returns the default readOnly property.
+ *
+ * @return true if connections are readOnly by default
+ */
public synchronized boolean getDefaultReadOnly() {
if (this.defaultReadOnly != null) {
return this.defaultReadOnly.booleanValue();
@@ -72,6 +93,16 @@
return false;
}
+ /**
+ * <p>Sets defaultReadonly property.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param defaultReadOnly default read-only value
+ */
public synchronized void setDefaultReadOnly(boolean defaultReadOnly) {
this.defaultReadOnly = defaultReadOnly ? Boolean.TRUE : Boolean.FALSE;
this.restartNeeded = true;
@@ -82,10 +113,29 @@
*/
protected int defaultTransactionIsolation = PoolableConnectionFactory.UNKNOWN_TRANSACTIONISOLATION;
+ /**
+ * Returns the default transaction isolation state of returned connections.
+ *
+ * @return the default value for transaction isolation state
+ * @see Connection#getTransactionIsolation
+ */
public synchronized int getDefaultTransactionIsolation() {
return this.defaultTransactionIsolation;
}
+ /**
+ * <p>Sets the default transaction isolation state for returned
+ * connections.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param defaultTransactionIsolation the default transaction isolation
+ * state
+ * @see Connection#getTransactionIsolation
+ */
public synchronized void setDefaultTransactionIsolation(int defaultTransactionIsolation) {
this.defaultTransactionIsolation = defaultTransactionIsolation;
this.restartNeeded = true;
@@ -97,10 +147,25 @@
*/
protected String defaultCatalog = null;
+ /**
+ * Returns the default catalog.
+ *
+ * @return the default catalog
+ */
public synchronized String getDefaultCatalog() {
return this.defaultCatalog;
}
+ /**
+ * <p>Sets the default catalog.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param defaultCatalog the default catalog
+ */
public synchronized void setDefaultCatalog(String defaultCatalog) {
if ((defaultCatalog != null) && (defaultCatalog.trim().length() > 0)) {
this.defaultCatalog = defaultCatalog;
@@ -117,10 +182,25 @@
*/
protected String driverClassName = null;
+ /**
+ * Returns the jdbc driver class name.
+ *
+ * @return the jdbc driver class name
+ */
public synchronized String getDriverClassName() {
return this.driverClassName;
}
+ /**
+ * <p>Sets the jdbc driver class name.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param driverClassName the class name of the jdbc driver
+ */
public synchronized void setDriverClassName(String driverClassName) {
if ((driverClassName != null) && (driverClassName.trim().length() > 0)) {
this.driverClassName = driverClassName;
@@ -138,10 +218,25 @@
*/
protected int maxActive = GenericObjectPool.DEFAULT_MAX_ACTIVE;
+ /**
+ * <p>Returns the maximum number of active connections that can be
+ * allocated at the same time.
+ * </p>
+ * <p>A non-positive number means that there is no limit.</p>
+ *
+ * @return the maximum number of active connections
+ */
public synchronized int getMaxActive() {
return this.maxActive;
}
+ /**
+ * Sets the maximum number of active connections that can be
+ * allocated at the same time.
+ *
+ * @param maxActive the new value for maxActive
+ * @see #getMaxActive()
+ */
public synchronized void setMaxActive(int maxActive) {
this.maxActive = maxActive;
if (connectionPool != null) {
@@ -149,17 +244,31 @@
}
}
-
/**
- * The maximum number of active connections that can remain idle in the
+ * The maximum number of connections that can remain idle in the
* pool, without extra ones being released, or negative for no limit.
*/
- protected int maxIdle = GenericObjectPool.DEFAULT_MAX_IDLE;;
+ protected int maxIdle = GenericObjectPool.DEFAULT_MAX_IDLE;
+ /**
+ * <p>Returns the maximum number of connections that can remain idle in the
+ * pool.
+ * </p>
+ * <p>A negative value indicates that there is no limit</p>
+ *
+ * @return the maximum number of idle connections
+ */
public synchronized int getMaxIdle() {
return this.maxIdle;
}
+ /**
+ * Sets the maximum number of connections that can remail idle in the
+ * pool.
+ *
+ * @see #getMaxIdle()
+ * @param maxIdle the new value for maxIdle
+ */
public synchronized void setMaxIdle(int maxIdle) {
this.maxIdle = maxIdle;
if (connectionPool != null) {
@@ -171,12 +280,24 @@
* The minimum number of active connections that can remain idle in the
* pool, without extra ones being created, or 0 to create none.
*/
- protected int minIdle = GenericObjectPool.DEFAULT_MIN_IDLE;;
+ protected int minIdle = GenericObjectPool.DEFAULT_MIN_IDLE;
+ /**
+ * Returns the minimum number of idle connections in the pool
+ *
+ * @return the minimum number of idle connections
+ * @see GenericObjectPool#getMinIdle()
+ */
public synchronized int getMinIdle() {
return this.minIdle;
}
+ /**
+ * Sets the minimum number of idle connections in the pool.
+ *
+ * @param minIdle the new value for minIdle
+ * @see GenericObjectPool#setMinIdle(int)
+ */
public synchronized void setMinIdle(int minIdle) {
this.minIdle = minIdle;
if (connectionPool != null) {
@@ -187,14 +308,31 @@
/**
* The initial number of connections that are created when the pool
* is started.
+ *
* @since 1.2
*/
protected int initialSize = 0;
+ /**
+ * Returns the initial size of the connection pool.
+ *
+ * @return the number of connections created when the pool is initialized
+ */
public synchronized int getInitialSize() {
return this.initialSize;
}
+ /**
+ * <p>Sets the initial size of the connection pool.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param initialSize the number of connections created when the pool
+ * is initialized
+ */
public synchronized void setInitialSize(int initialSize) {
this.initialSize = initialSize;
this.restartNeeded = true;
@@ -207,10 +345,24 @@
*/
protected long maxWait = GenericObjectPool.DEFAULT_MAX_WAIT;
+ /**
+ * <p>Returns the maximum number of milliseconds that the pool will wait
+ * for a connection to be returned before throwing an exception.
+ * </p>
+ * <p>Returns -1 if the pool is set to wait indefinitely.</p>
+ *
+ * @return the maxWait property value
+ */
public synchronized long getMaxWait() {
return this.maxWait;
}
+ /**
+ * Sets the maxWait property.
+ *
+ * @param maxWait the new value for maxWait
+ * @see #getMaxWait()
+ */
public synchronized void setMaxWait(long maxWait) {
this.maxWait = maxWait;
if (connectionPool != null) {
@@ -225,14 +377,21 @@
/**
* Returns true if we are pooling statements.
- * @return boolean
+ *
+ * @return true if prepared statements are pooled
*/
public synchronized boolean isPoolPreparedStatements() {
return this.poolPreparedStatements;
}
/**
- * Sets whether to pool statements or not.
+ * <p>Sets whether to pool statements or not.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
* @param poolingStatements pooling on or off
*/
public synchronized void setPoolPreparedStatements(boolean poolingStatements) {
@@ -248,10 +407,28 @@
*/
protected int maxOpenPreparedStatements = GenericKeyedObjectPool.DEFAULT_MAX_TOTAL;
+ /**
+ * Gets the value of the {@link #maxOpenPreparedStatements} property.
+ *
+ * @return the maximum number of open statements
+ * @see #maxOpenPreparedStatements
+ */
public synchronized int getMaxOpenPreparedStatements() {
return this.maxOpenPreparedStatements;
}
+ /**
+ * <p>Sets the value of the {@link #maxOpenPreparedStatements}
+ * property.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param maxOpenStatements the new maximum number of prepared statements
+ * @see #maxOpenPreparedStatements
+ */
public synchronized void setMaxOpenPreparedStatements(int maxOpenStatements) {
this.maxOpenPreparedStatements = maxOpenStatements;
this.restartNeeded = true;
@@ -264,12 +441,20 @@
*/
protected boolean testOnBorrow = true;
+ /**
+ * Returns the {@link #testOnBorrow} property.
+ *
+ * @return true if objects are validated before being borrowed from the
+ * pool
+ *
+ * @see #testOnBorrow
+ */
public synchronized boolean getTestOnBorrow() {
return this.testOnBorrow;
}
/**
- * Sets the <code>testOnBorrow</code> property. This property determines
+ * Sets the {@link #testOnBorrow} property. This property determines
* whether or not the pool will validate objects before they are borrowed
* from the pool. For a <code>true</code> value to have any effect, the
* <code>validationQuery</code> property must be set to a non-null string.
@@ -289,6 +474,13 @@
*/
protected boolean testOnReturn = false;
+ /**
+ * Returns the value of the {@link #testOnReturn} property.
+ *
+ * @return true if objects are validated before being returned to the
+ * pool
+ * @see #testOnReturn
+ */
public synchronized boolean getTestOnReturn() {
return this.testOnReturn;
}
@@ -308,7 +500,6 @@
}
}
-
/**
* The number of milliseconds to sleep between runs of the idle object
* evictor thread. When non-positive, no idle object evictor thread will
@@ -317,10 +508,23 @@
protected long timeBetweenEvictionRunsMillis =
GenericObjectPool.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS;
+ /**
+ * Returns the value of the {@link #timeBetweenEvictionRunsMillis}
+ * property.
+ *
+ * @return the time (in miliseconds) between evictor runs
+ * @see #timeBetweenEvictionRunsMillis
+ */
public synchronized long getTimeBetweenEvictionRunsMillis() {
return this.timeBetweenEvictionRunsMillis;
}
+ /**
+ * Sets the {@link #timeBetweenEvictionRunsMillis} property.
+ *
+ * @param timeBetweenEvictionRunsMillis the new time between evictor runs
+ * @see #timeBetweenEvictionRunsMillis
+ */
public synchronized void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) {
this.timeBetweenEvictionRunsMillis = timeBetweenEvictionRunsMillis;
if (connectionPool != null) {
@@ -328,7 +532,6 @@
}
}
-
/**
* The number of objects to examine during each run of the idle object
* evictor thread (if any).
@@ -336,10 +539,24 @@
protected int numTestsPerEvictionRun =
GenericObjectPool.DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
+ /**
+ * Returns the value of the {@link #numTestsPerEvictionRun} property.
+ *
+ * @return the number of objects to examine during idle object evictor
+ * runs
+ * @see #numTestsPerEvictionRun
+ */
public synchronized int getNumTestsPerEvictionRun() {
return this.numTestsPerEvictionRun;
}
+ /**
+ * Sets the value of the {@link #numTestsPerEvictionRun} property.
+ *
+ * @param numTestsPerEvictionRun the new {@link #numTestsPerEvictionRun}
+ * value
+ * @see #numTestsPerEvictionRun
+ */
public synchronized void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) {
this.numTestsPerEvictionRun = numTestsPerEvictionRun;
if (connectionPool != null) {
@@ -347,7 +564,6 @@
}
}
-
/**
* The minimum amount of time an object may sit idle in the pool before it
* is eligable for eviction by the idle object evictor (if any).
@@ -355,10 +571,23 @@
protected long minEvictableIdleTimeMillis =
GenericObjectPool.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS;
+ /**
+ * Returns the {@link #minEvictableIdleTimeMillis} property.
+ *
+ * @return the value of the {@link #minEvictableIdleTimeMillis} property
+ * @see #minEvictableIdleTimeMillis
+ */
public synchronized long getMinEvictableIdleTimeMillis() {
return this.minEvictableIdleTimeMillis;
}
+ /**
+ * Sets the {@link #minEvictableIdleTimeMillis} property.
+ *
+ * @param minEvictableIdleTimeMillis the minimum amount of time an object
+ * may sit idle in the pool
+ * @see #minEvictableIdleTimeMillis
+ */
public synchronized void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) {
this.minEvictableIdleTimeMillis = minEvictableIdleTimeMillis;
if (connectionPool != null) {
@@ -373,6 +602,13 @@
*/
protected boolean testWhileIdle = false;
+ /**
+ * Returns the value of the {@link #testWhileIdle} property.
+ *
+ * @return true if objects examined by the idle object evictor are
+ * validated
+ * @see #testWhileIdle
+ */
public synchronized boolean getTestWhileIdle() {
return this.testWhileIdle;
}
@@ -395,6 +631,8 @@
/**
* [Read Only] The current number of active connections that have been
* allocated from this data source.
+ *
+ * @return the current number of active connections
*/
public synchronized int getNumActive() {
if (connectionPool != null) {
@@ -408,6 +646,8 @@
/**
* [Read Only] The current number of idle connections that are waiting
* to be allocated from this data source.
+ *
+ * @return the current number of idle connections
*/
public synchronized int getNumIdle() {
if (connectionPool != null) {
@@ -417,55 +657,98 @@
}
}
-
/**
* The connection password to be passed to our JDBC driver to establish
* a connection.
*/
protected String password = null;
+ /**
+ * Returns the password passed to the JDBC driver to establish connections.
+ *
+ * @return the connection password
+ */
public synchronized String getPassword() {
return this.password;
}
+ /**
+ * <p>Sets the {@link #password}.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param password new value for the password
+ */
public synchronized void setPassword(String password) {
this.password = password;
this.restartNeeded = true;
}
-
/**
* The connection URL to be passed to our JDBC driver to establish
* a connection.
*/
protected String url = null;
+ /**
+ * Returns the JDBC connection {@link #url} property.
+ *
+ * @return the {@link #url} passed to the JDBC driver to establish
+ * connections
+ */
public synchronized String getUrl() {
return this.url;
}
+ /**
+ * <p>Sets the {@link #url}.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param url the new value for the JDBC connection url
+ */
public synchronized void setUrl(String url) {
this.url = url;
this.restartNeeded = true;
}
-
/**
* The connection username to be passed to our JDBC driver to
* establish a connection.
*/
protected String username = null;
+ /**
+ * Returns the JDBC connection {@link #username} property.
+ *
+ * @return the {@link #username} passed to the JDBC driver to establish
+ * connections
+ */
public synchronized String getUsername() {
return this.username;
}
+ /**
+ * <p>Sets the {@link #username}.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param username the new value for the JDBC connection username
+ */
public synchronized void setUsername(String username) {
this.username = username;
this.restartNeeded = true;
}
-
/**
* The SQL query that will be used to validate connections from this pool
* before returning them to the caller. If specified, this query
@@ -474,10 +757,27 @@
*/
protected String validationQuery = null;
+ /**
+ * Returns the validation query used to validate connections before
+ * returning them.
+ *
+ * @return the SQL validation query
+ * @see #validationQuery
+ */
public synchronized String getValidationQuery() {
return this.validationQuery;
}
+ /**
+ * <p>Sets the {@link #validationQuery}.</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
+ *
+ * @param validationQuery the new value for the validation query
+ */
public synchronized void setValidationQuery(String validationQuery) {
if ((validationQuery != null) && (validationQuery.trim().length() > 0)) {
this.validationQuery = validationQuery;
@@ -488,23 +788,29 @@
}
/**
- * Controls access to the underlying connection
+ * Controls access to the underlying connection.
*/
private boolean accessToUnderlyingConnectionAllowed = false;
/**
* Returns the value of the accessToUnderlyingConnectionAllowed property.
*
- * @return true if access to the underlying is allowed, false otherwise.
+ * @return true if access to the underlying connection is allowed, false
+ * otherwise.
*/
public synchronized boolean isAccessToUnderlyingConnectionAllowed() {
return this.accessToUnderlyingConnectionAllowed;
}
/**
- * Sets the value of the accessToUnderlyingConnectionAllowed property.
+ * <p>Sets the value of the accessToUnderlyingConnectionAllowed property.
* It controls if the PoolGuard allows access to the underlying connection.
- * (Default: false)
+ * (Default: false)</p>
+ * <p>
+ * Note: this method currently has no effect once the pool has been
+ * initialized. The pool is initialized the first time one of the
+ * following methods is invoked: <code>getConnection, setLogwriter,
+ * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p>
*
* @param allow Access to the underlying connection is granted when true.
*/
@@ -517,10 +823,18 @@
// TODO: review & make isRestartNeeded() public, restartNeeded protected
+ /**
+ * A property setter has been invoked that will require the connection
+ * pool to be re-initialized. Currently, restart is not triggered, so
+ * this property has no effect.
+ */
private boolean restartNeeded = false;
/**
- * Returns whether or not a restart is needed.
+ * Returns whether or not a restart is needed.
+ *
+ * Note: restart is not currently triggered by property changes.
+ *
* @return true if a restart is needed
*/
private synchronized boolean isRestartNeeded() {
@@ -559,7 +873,8 @@
/**
* Create (if necessary) and return a connection to the database.
*
- * @exception SQLException if a database access error occurs
+ * @throws SQLException if a database access error occurs
+ * @return a database connection
*/
public Connection getConnection() throws SQLException {
return createDataSource().getConnection();
@@ -567,15 +882,15 @@
/**
- * Create (if necessary) and return a connection to the database.
- *
* <p><strong>BasicDataSource does NOT support this method.</strong></p>
*
* @param username Database user on whose behalf the Connection
* is being made
* @param password The database user's password
*
- * @exception SQLException if a database access error occurs
+ * @throws UnsupportedOperationException
+ * @throws SQLException if a database access error occurs
+ * @return nothing - always throws UnsupportedOperationException
*/
public Connection getConnection(String username, String password) throws SQLException {
// This method isn't supported by the PoolingDataSource returned by
@@ -586,11 +901,15 @@
/**
- * Return the login timeout (in seconds) for connecting to the database.
+ * <p>Returns the login timeout (in seconds) for connecting to the database.
+ * </p>
+ * <p>Calls {@link #createDataSource()}, so has the side effect
+ * of initializing the connection pool.</p>
*
- * @exception SQLException if a database access error occurs
- * @exception UnsupportedOperationException If the DataSource implementation
+ * @throws SQLException if a database access error occurs
+ * @throws UnsupportedOperationException If the DataSource implementation
* does not support the login timeout feature.
+ * @return login timeout in seconds
*/
public int getLoginTimeout() throws SQLException {
return createDataSource().getLoginTimeout();
@@ -598,9 +917,13 @@
/**
- * Return the log writer being used by this data source.
+ * <p>Returns the log writer being used by this data source.</p>
+ * <p>
+ * Calls {@link #createDataSource()}, so has the side effect
+ * of initializing the connection pool.</p>
*
- * @exception SQLException if a database access error occurs
+ * @throws SQLException if a database access error occurs
+ * @return log writer in use
*/
public PrintWriter getLogWriter() throws SQLException {
return createDataSource().getLogWriter();
@@ -608,11 +931,14 @@
/**
- * Set the login timeout (in seconds) for connecting to the database.
+ * <p>Set the login timeout (in seconds) for connecting to the
+ * database.</p>
+ * <p>
+ * Calls {@link #createDataSource()}, so has the side effect
+ * of initializing the connection pool.</p>
*
* @param loginTimeout The new login timeout, or zero for no timeout
- *
- * @exception SQLException if a database access error occurs
+ * @throws SQLException if a database access error occurs
*/
public void setLoginTimeout(int loginTimeout) throws SQLException {
createDataSource().setLoginTimeout(loginTimeout);
@@ -620,11 +946,13 @@
/**
- * Set the log writer being used by this data source.
+ * <p>Sets the log writer being used by this data source.</p>
+ * <p>
+ * Calls {@link #createDataSource()}, so has the side effect
+ * of initializing the connection pool.</p>
*
* @param logWriter The new log writer
- *
- * @exception SQLException if a database access error occurs
+ * @throws SQLException if a database access error occurs
*/
public void setLogWriter(PrintWriter logWriter) throws SQLException {
createDataSource().setLogWriter(logWriter);
@@ -653,7 +981,7 @@
/**
* @deprecated
- * @param removeAbandoned
+ * @param removeAbandoned new removeAbandoned property value
*/
public void setRemoveAbandoned(boolean removeAbandoned) {
if (abandonedConfig == null) {
@@ -666,7 +994,8 @@
/**
* Timeout in seconds before an abandoned connection can be removed.
*
- * Defaults to 300 seconds.
+ * Defaults to 300 seconds.
+ * @return abandoned connection timeout
* @deprecated
*/
public int getRemoveAbandonedTimeout() {
@@ -678,7 +1007,7 @@
/**
* @deprecated
- * @param removeAbandonedTimeout
+ * @param removeAbandonedTimeout new removeAbandonedTimeout value
*/
public void setRemoveAbandonedTimeout(int removeAbandonedTimeout) {
if (abandonedConfig == null) {
@@ -689,14 +1018,15 @@
}
/**
- * Flag to log stack traces for application code which abandoned
+ * <p>Flag to log stack traces for application code which abandoned
* a Statement or Connection.
- *
- * Defaults to false.
- *
- * Logging of abandoned Statements and Connections adds overhead
+ * </p>
+ * <p>Defaults to false.
+ * </p>
+ * <p>Logging of abandoned Statements and Connections adds overhead
* for every Connection open or new Statement because a stack
- * trace has to be generated.
+ * trace has to be generated. </p>
+ *
* @deprecated
*/
public boolean getLogAbandoned() {
@@ -708,7 +1038,7 @@
/**
* @deprecated
- * @param logAbandoned
+ * @param logAbandoned new logAbandoned property value
*/
public void setLogAbandoned(boolean logAbandoned) {
if (abandonedConfig == null) {
@@ -722,9 +1052,10 @@
/**
* Add a custom connection property to the set that will be passed to our
- * JDBC driver. This <strong>MUST</strong> be called before the first
+ * JDBC driver. This <strong>MUST</strong> be called before the first
* connection is retrieved (along with all the other configuration
- * property setters).
+ * property setters). Calls to this method after the connection pool
+ * has been initialized have no effect.
*
* @param name Name of the custom connection property
* @param value Value of the custom connection property
@@ -734,6 +1065,12 @@
this.restartNeeded = true;
}
+ /**
+ * Remove a custom connection property.
+ *
+ * @param name Name of the custom connection property to remove
+ * @see #addConnectionProperty(String, String)
+ */
public void removeConnectionProperty(String name) {
connectionProperties.remove(name);
this.restartNeeded = true;
@@ -743,7 +1080,7 @@
* Close and release all connections that are currently stored in the
* connection pool associated with our data source.
*
- * @exception SQLException if a database error occurs
+ * @throws SQLException if a database error occurs
*/
public synchronized void close() throws SQLException {
GenericObjectPool oldpool = connectionPool;
@@ -776,7 +1113,7 @@
* work correctly in the face of some optimizations that are legal for
* a JVM to perform.</p>
*
- * @exception SQLException if the object pool cannot be created.
+ * @throws SQLException if the object pool cannot be created.
*/
protected synchronized DataSource createDataSource()
throws SQLException {
@@ -916,6 +1253,9 @@
}
}
+ /**
+ * Not used currently
+ */
private void restart() {
try {
close();
Modified: jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSourceFactory.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSourceFactory.java?view=diff&rev=491655&r1=491654&r2=491655
==============================================================================
--- jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSourceFactory.java (original)
+++ jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/BasicDataSourceFactory.java Mon Jan 1 14:05:30 2007
@@ -146,8 +146,11 @@
}
/**
- * Creates and configures a BasicDataSource instance based on the
+ * Creates and configures a {@link BasicDataSource} instance based on the
* given properties.
+ *
+ * @param properties the datasource configuration properties
+ * @throws Exception if an error occurs creating the data source
*/
public static DataSource createDataSource(Properties properties) throws Exception {
BasicDataSource dataSource = new BasicDataSource();
Modified: jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/ConnectionFactory.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/ConnectionFactory.java?view=diff&rev=491655&r1=491654&r2=491655
==============================================================================
--- jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/ConnectionFactory.java (original)
+++ jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/ConnectionFactory.java Mon Jan 1 14:05:30 2007
@@ -31,6 +31,7 @@
* implementation specific fashion.
*
* @return a new {@link java.sql.Connection}
+ * @throws SQLException if a database error occurs creating the connection
*/
public abstract Connection createConnection() throws SQLException;
}
Modified: jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/DelegatingCallableStatement.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/DelegatingCallableStatement.java?view=diff&rev=491655&r1=491654&r2=491655
==============================================================================
--- jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/DelegatingCallableStatement.java (original)
+++ jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/dbcp/DelegatingCallableStatement.java Mon Jan 1 14:05:30 2007
@@ -334,4 +334,4 @@
{ checkOpen(); try { return _stmt.getURL(parameterName); } catch (SQLException e) { handleException(e); return null; } }
/* JDBC_3_ANT_KEY_END */
-}
\ No newline at end of file
+}
Modified: jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/jocl/JOCLContentHandler.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/jocl/JOCLContentHandler.java?view=diff&rev=491655&r1=491654&r2=491655
==============================================================================
--- jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/jocl/JOCLContentHandler.java (original)
+++ jakarta/commons/proper/dbcp/trunk/src/java/org/apache/commons/jocl/JOCLContentHandler.java Mon Jan 1 14:05:30 2007
@@ -353,7 +353,7 @@
/**
* Construct a JOCLContentHandler.
- * @param emtpyEltNs when <tt>true</tt> I should assume any element with an empty namespace is within the JOCL namespace
+ * @param emptyEltNS when <tt>true</tt> I should assume any element with an empty namespace is within the JOCL namespace
* @param joclEltPrefix when <tt>true</tt> I should assume any element who's prefix is <tt>jocl:</tt> and who's namespace is empty is within the JOCL namespace
* @param emptyAttrNS when <tt>true</tt> I should assume any attribute with an empty namespace is within the JOCL namespace
* @param joclAttrPrefix when <tt>true</tt> I should assume any attribute who's prefix is <tt>jocl:</tt> and who's namespace is empty is within the JOCL namespace
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org