org.apache.commons.dbcp

Class BasicDataSource

public class BasicDataSource extends Object implements DataSource

Basic implementation of javax.sql.DataSource that is configured via JavaBeans properties. This is not the only way to combine the commons-dbcp and commons-pool packages, but provides a "one stop shopping" solution for basic requirements.

Version: $Revision: 506087 $ $Date: 2007-02-11 11:37:43 -0700 (Sun, 11 Feb 2007) $

Author: Glenn L. Nielsen Craig R. McClanahan Dirk Verbeeck

Method Summary
voidaddConnectionProperty(String name, String value)
Add a custom connection property to the set that will be passed to our JDBC driver.
voidclose()
Close and release all connections that are currently stored in the connection pool associated with our data source.
ConnectiongetConnection()
Create (if necessary) and return a connection to the database.
ConnectiongetConnection(String username, String password)
BasicDataSource does NOT support this method.
booleangetDefaultAutoCommit()
Returns the default auto-commit property.
StringgetDefaultCatalog()
Returns the default catalog.
booleangetDefaultReadOnly()
Returns the default readOnly property.
intgetDefaultTransactionIsolation()
Returns the default transaction isolation state of returned connections.
StringgetDriverClassName()
Returns the jdbc driver class name.
intgetInitialSize()
Returns the initial size of the connection pool.
booleangetLogAbandoned()

Flag to log stack traces for application code which abandoned a Statement or Connection.

intgetLoginTimeout()

Returns the login timeout (in seconds) for connecting to the database.

PrintWritergetLogWriter()

Returns the log writer being used by this data source.

Calls createDataSource, so has the side effect of initializing the connection pool.

intgetMaxActive()

Returns the maximum number of active connections that can be allocated at the same time.

intgetMaxIdle()

Returns the maximum number of connections that can remain idle in the pool.

intgetMaxOpenPreparedStatements()
Gets the value of the maxOpenPreparedStatements property.
longgetMaxWait()

Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception.

longgetMinEvictableIdleTimeMillis()
Returns the minEvictableIdleTimeMillis property.
intgetMinIdle()
Returns the minimum number of idle connections in the pool
intgetNumActive()
[Read Only] The current number of active connections that have been allocated from this data source.
intgetNumIdle()
[Read Only] The current number of idle connections that are waiting to be allocated from this data source.
intgetNumTestsPerEvictionRun()
Returns the value of the numTestsPerEvictionRun property.
StringgetPassword()
Returns the password passed to the JDBC driver to establish connections.
booleangetRemoveAbandoned()
Flag to remove abandoned connections if they exceed the removeAbandonedTimout.
intgetRemoveAbandonedTimeout()
Timeout in seconds before an abandoned connection can be removed.
booleangetTestOnBorrow()
Returns the testOnBorrow property.
booleangetTestOnReturn()
Returns the value of the testOnReturn property.
booleangetTestWhileIdle()
Returns the value of the testWhileIdle property.
longgetTimeBetweenEvictionRunsMillis()
Returns the value of the timeBetweenEvictionRunsMillis property.
StringgetUrl()
Returns the JDBC connection url property.
StringgetUsername()
Returns the JDBC connection username property.
StringgetValidationQuery()
Returns the validation query used to validate connections before returning them.
booleanisAccessToUnderlyingConnectionAllowed()
Returns the value of the accessToUnderlyingConnectionAllowed property.
booleanisPoolPreparedStatements()
Returns true if we are pooling statements.
voidremoveConnectionProperty(String name)
Remove a custom connection property.
voidsetAccessToUnderlyingConnectionAllowed(boolean allow)

Sets the value of the accessToUnderlyingConnectionAllowed property.

voidsetDefaultAutoCommit(boolean defaultAutoCommit)

Sets default auto-commit state of connections returned by this datasource.

Note: this method currently has no effect once the pool has been initialized.

voidsetDefaultCatalog(String defaultCatalog)

Sets the default catalog.

Note: this method currently has no effect once the pool has been initialized.

voidsetDefaultReadOnly(boolean defaultReadOnly)

Sets defaultReadonly property.

Note: this method currently has no effect once the pool has been initialized.

voidsetDefaultTransactionIsolation(int defaultTransactionIsolation)

Sets the default transaction isolation state for returned connections.

Note: this method currently has no effect once the pool has been initialized.

voidsetDriverClassName(String driverClassName)

Sets the jdbc driver class name.

Note: this method currently has no effect once the pool has been initialized.

voidsetInitialSize(int initialSize)

Sets the initial size of the connection pool.

Note: this method currently has no effect once the pool has been initialized.

voidsetLogAbandoned(boolean logAbandoned)
voidsetLoginTimeout(int loginTimeout)

Set the login timeout (in seconds) for connecting to the database.

Calls createDataSource, so has the side effect of initializing the connection pool.

voidsetLogWriter(PrintWriter logWriter)

Sets the log writer being used by this data source.

Calls createDataSource, so has the side effect of initializing the connection pool.

voidsetMaxActive(int maxActive)
Sets the maximum number of active connections that can be allocated at the same time.
voidsetMaxIdle(int maxIdle)
Sets the maximum number of connections that can remail idle in the pool.
voidsetMaxOpenPreparedStatements(int maxOpenStatements)

Sets the value of the maxOpenPreparedStatements property.

Note: this method currently has no effect once the pool has been initialized.

voidsetMaxWait(long maxWait)
Sets the maxWait property.
voidsetMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
Sets the minEvictableIdleTimeMillis property.
voidsetMinIdle(int minIdle)
Sets the minimum number of idle connections in the pool.
voidsetNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the value of the numTestsPerEvictionRun property.
voidsetPassword(String password)

Sets the password.

Note: this method currently has no effect once the pool has been initialized.

voidsetPoolPreparedStatements(boolean poolingStatements)

Sets whether to pool statements or not.

Note: this method currently has no effect once the pool has been initialized.

voidsetRemoveAbandoned(boolean removeAbandoned)
voidsetRemoveAbandonedTimeout(int removeAbandonedTimeout)
voidsetTestOnBorrow(boolean testOnBorrow)
Sets the testOnBorrow property.
voidsetTestOnReturn(boolean testOnReturn)
Sets the testOnReturn property.
voidsetTestWhileIdle(boolean testWhileIdle)
Sets the testWhileIdle property.
voidsetTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
Sets the timeBetweenEvictionRunsMillis property.
voidsetUrl(String url)

Sets the url.

Note: this method currently has no effect once the pool has been initialized.

voidsetUsername(String username)

Sets the username.

Note: this method currently has no effect once the pool has been initialized.

voidsetValidationQuery(String validationQuery)

Sets the validationQuery.

Note: this method currently has no effect once the pool has been initialized.

Method Detail

addConnectionProperty

public void addConnectionProperty(String name, String value)
Add a custom connection property to the set that will be passed to our JDBC driver. This MUST be called before the first connection is retrieved (along with all the other configuration property setters). Calls to this method after the connection pool has been initialized have no effect.

Parameters: name Name of the custom connection property value Value of the custom connection property

close

public void close()
Close and release all connections that are currently stored in the connection pool associated with our data source.

Throws: SQLException if a database error occurs

getConnection

public Connection getConnection()
Create (if necessary) and return a connection to the database.

Returns: a database connection

Throws: SQLException if a database access error occurs

getConnection

public Connection getConnection(String username, String password)
BasicDataSource does NOT support this method.

Parameters: username Database user on whose behalf the Connection is being made password The database user's password

Returns: nothing - always throws UnsupportedOperationException

Throws: UnsupportedOperationException SQLException if a database access error occurs

getDefaultAutoCommit

public boolean getDefaultAutoCommit()
Returns the default auto-commit property.

Returns: true if default auto-commit is enabled

getDefaultCatalog

public String getDefaultCatalog()
Returns the default catalog.

Returns: the default catalog

getDefaultReadOnly

public boolean getDefaultReadOnly()
Returns the default readOnly property.

Returns: true if connections are readOnly by default

getDefaultTransactionIsolation

public int getDefaultTransactionIsolation()
Returns the default transaction isolation state of returned connections.

Returns: the default value for transaction isolation state

See Also: Connection#getTransactionIsolation

getDriverClassName

public String getDriverClassName()
Returns the jdbc driver class name.

Returns: the jdbc driver class name

getInitialSize

public int getInitialSize()
Returns the initial size of the connection pool.

Returns: the number of connections created when the pool is initialized

getLogAbandoned

public boolean getLogAbandoned()

Deprecated:

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 for every Connection open or new Statement because a stack trace has to be generated.

getLoginTimeout

public int getLoginTimeout()

Returns the login timeout (in seconds) for connecting to the database.

Calls createDataSource, so has the side effect of initializing the connection pool.

Returns: login timeout in seconds

Throws: SQLException if a database access error occurs UnsupportedOperationException If the DataSource implementation does not support the login timeout feature.

getLogWriter

public PrintWriter getLogWriter()

Returns the log writer being used by this data source.

Calls createDataSource, so has the side effect of initializing the connection pool.

Returns: log writer in use

Throws: SQLException if a database access error occurs

getMaxActive

public int getMaxActive()

Returns the maximum number of active connections that can be allocated at the same time.

A non-positive number means that there is no limit.

Returns: the maximum number of active connections

getMaxIdle

public int getMaxIdle()

Returns the maximum number of connections that can remain idle in the pool.

A negative value indicates that there is no limit

Returns: the maximum number of idle connections

getMaxOpenPreparedStatements

public int getMaxOpenPreparedStatements()
Gets the value of the maxOpenPreparedStatements property.

Returns: the maximum number of open statements

See Also: maxOpenPreparedStatements

getMaxWait

public long getMaxWait()

Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception.

Returns -1 if the pool is set to wait indefinitely.

Returns: the maxWait property value

getMinEvictableIdleTimeMillis

public long getMinEvictableIdleTimeMillis()
Returns the minEvictableIdleTimeMillis property.

Returns: the value of the minEvictableIdleTimeMillis property

See Also: minEvictableIdleTimeMillis

getMinIdle

public int getMinIdle()
Returns the minimum number of idle connections in the pool

Returns: the minimum number of idle connections

See Also: GenericObjectPool#getMinIdle()

getNumActive

public int getNumActive()
[Read Only] The current number of active connections that have been allocated from this data source.

Returns: the current number of active connections

getNumIdle

public int getNumIdle()
[Read Only] The current number of idle connections that are waiting to be allocated from this data source.

Returns: the current number of idle connections

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()
Returns the value of the numTestsPerEvictionRun property.

Returns: the number of objects to examine during idle object evictor runs

See Also: numTestsPerEvictionRun

getPassword

public String getPassword()
Returns the password passed to the JDBC driver to establish connections.

Returns: the connection password

getRemoveAbandoned

public boolean getRemoveAbandoned()

Deprecated:

Flag to remove abandoned connections if they exceed the removeAbandonedTimout. Set to true or false, default false. If set to true a connection is considered abandoned and eligible for removal if it has been idle longer than the removeAbandonedTimeout. Setting this to true can recover db connections from poorly written applications which fail to close a connection.

getRemoveAbandonedTimeout

public int getRemoveAbandonedTimeout()

Deprecated:

Timeout in seconds before an abandoned connection can be removed. Defaults to 300 seconds.

Returns: abandoned connection timeout

getTestOnBorrow

public boolean getTestOnBorrow()
Returns the testOnBorrow property.

Returns: true if objects are validated before being borrowed from the pool

See Also: testOnBorrow

getTestOnReturn

public boolean getTestOnReturn()
Returns the value of the testOnReturn property.

Returns: true if objects are validated before being returned to the pool

See Also: testOnReturn

getTestWhileIdle

public boolean getTestWhileIdle()
Returns the value of the testWhileIdle property.

Returns: true if objects examined by the idle object evictor are validated

See Also: testWhileIdle

getTimeBetweenEvictionRunsMillis

public long getTimeBetweenEvictionRunsMillis()
Returns the value of the timeBetweenEvictionRunsMillis property.

Returns: the time (in miliseconds) between evictor runs

See Also: timeBetweenEvictionRunsMillis

getUrl

public String getUrl()
Returns the JDBC connection url property.

Returns: the url passed to the JDBC driver to establish connections

getUsername

public String getUsername()
Returns the JDBC connection username property.

Returns: the username passed to the JDBC driver to establish connections

getValidationQuery

public String getValidationQuery()
Returns the validation query used to validate connections before returning them.

Returns: the SQL validation query

See Also: validationQuery

isAccessToUnderlyingConnectionAllowed

public boolean isAccessToUnderlyingConnectionAllowed()
Returns the value of the accessToUnderlyingConnectionAllowed property.

Returns: true if access to the underlying connection is allowed, false otherwise.

isPoolPreparedStatements

public boolean isPoolPreparedStatements()
Returns true if we are pooling statements.

Returns: true if prepared statements are pooled

removeConnectionProperty

public void removeConnectionProperty(String name)
Remove a custom connection property.

Parameters: name Name of the custom connection property to remove

See Also: BasicDataSource

setAccessToUnderlyingConnectionAllowed

public void setAccessToUnderlyingConnectionAllowed(boolean allow)

Sets the value of the accessToUnderlyingConnectionAllowed property. It controls if the PoolGuard allows access to the underlying connection. (Default: false)

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: allow Access to the underlying connection is granted when true.

setDefaultAutoCommit

public void setDefaultAutoCommit(boolean defaultAutoCommit)

Sets default auto-commit state of connections returned by this datasource.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: defaultAutoCommit default auto-commit value

setDefaultCatalog

public void setDefaultCatalog(String defaultCatalog)

Sets the default catalog.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: defaultCatalog the default catalog

setDefaultReadOnly

public void setDefaultReadOnly(boolean defaultReadOnly)

Sets defaultReadonly property.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: defaultReadOnly default read-only value

setDefaultTransactionIsolation

public void setDefaultTransactionIsolation(int defaultTransactionIsolation)

Sets the default transaction isolation state for returned connections.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: defaultTransactionIsolation the default transaction isolation state

See Also: Connection#getTransactionIsolation

setDriverClassName

public void setDriverClassName(String driverClassName)

Sets the jdbc driver class name.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: driverClassName the class name of the jdbc driver

setInitialSize

public void setInitialSize(int initialSize)

Sets the initial size of the connection pool.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: initialSize the number of connections created when the pool is initialized

setLogAbandoned

public void setLogAbandoned(boolean logAbandoned)

Deprecated:

Parameters: logAbandoned new logAbandoned property value

setLoginTimeout

public void setLoginTimeout(int loginTimeout)

Set the login timeout (in seconds) for connecting to the database.

Calls createDataSource, so has the side effect of initializing the connection pool.

Parameters: loginTimeout The new login timeout, or zero for no timeout

Throws: SQLException if a database access error occurs

setLogWriter

public void setLogWriter(PrintWriter logWriter)

Sets the log writer being used by this data source.

Calls createDataSource, so has the side effect of initializing the connection pool.

Parameters: logWriter The new log writer

Throws: SQLException if a database access error occurs

setMaxActive

public void setMaxActive(int maxActive)
Sets the maximum number of active connections that can be allocated at the same time.

Parameters: maxActive the new value for maxActive

See Also: getMaxActive

setMaxIdle

public void setMaxIdle(int maxIdle)
Sets the maximum number of connections that can remail idle in the pool.

Parameters: maxIdle the new value for maxIdle

See Also: getMaxIdle

setMaxOpenPreparedStatements

public void setMaxOpenPreparedStatements(int maxOpenStatements)

Sets the value of the maxOpenPreparedStatements property.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: maxOpenStatements the new maximum number of prepared statements

See Also: maxOpenPreparedStatements

setMaxWait

public void setMaxWait(long maxWait)
Sets the maxWait property.

Parameters: maxWait the new value for maxWait

See Also: getMaxWait

setMinEvictableIdleTimeMillis

public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
Sets the minEvictableIdleTimeMillis property.

Parameters: minEvictableIdleTimeMillis the minimum amount of time an object may sit idle in the pool

See Also: minEvictableIdleTimeMillis

setMinIdle

public void setMinIdle(int minIdle)
Sets the minimum number of idle connections in the pool.

Parameters: minIdle the new value for minIdle

See Also: GenericObjectPool#setMinIdle(int)

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the value of the numTestsPerEvictionRun property.

Parameters: numTestsPerEvictionRun the new numTestsPerEvictionRun value

See Also: numTestsPerEvictionRun

setPassword

public void setPassword(String password)

Sets the password.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: password new value for the password

setPoolPreparedStatements

public void setPoolPreparedStatements(boolean poolingStatements)

Sets whether to pool statements or not.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: poolingStatements pooling on or off

setRemoveAbandoned

public void setRemoveAbandoned(boolean removeAbandoned)

Deprecated:

Parameters: removeAbandoned new removeAbandoned property value

setRemoveAbandonedTimeout

public void setRemoveAbandonedTimeout(int removeAbandonedTimeout)

Deprecated:

Parameters: removeAbandonedTimeout new removeAbandonedTimeout value

setTestOnBorrow

public void setTestOnBorrow(boolean testOnBorrow)
Sets the testOnBorrow property. This property determines whether or not the pool will validate objects before they are borrowed from the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.

Parameters: testOnBorrow new value for testOnBorrow property

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)
Sets the testOnReturn property. This property determines whether or not the pool will validate objects before they are returned to the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.

Parameters: testOnReturn new value for testOnReturn property

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)
Sets the testWhileIdle property. This property determines whether or not the idle object evictor will validate connections. For a true value to have any effect, the validationQuery property must be set to a non-null string.

Parameters: testWhileIdle new value for testWhileIdle property

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
Sets the timeBetweenEvictionRunsMillis property.

Parameters: timeBetweenEvictionRunsMillis the new time between evictor runs

See Also: timeBetweenEvictionRunsMillis

setUrl

public void setUrl(String url)

Sets the url.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: url the new value for the JDBC connection url

setUsername

public void setUsername(String username)

Sets the username.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: username the new value for the JDBC connection username

setValidationQuery

public void setValidationQuery(String validationQuery)

Sets the validationQuery.

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: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

Parameters: validationQuery the new value for the validation query

Copyright © 2001-2004 Apache Software Foundation. Documenation generated December 10 2007.