org.apache.commons.dbcp
Class BasicDataSource

java.lang.Object
  |
  +--org.apache.commons.dbcp.BasicDataSource

All Implemented Interfaces:

javax.sql.DataSource

public class BasicDataSource

extends java.lang.Object

implements javax.sql.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: 1.11 $ $Date: 2002/07/21 00:38:35 $

Author:

Glenn L. Nielsen

, Craig R. McClanahan

Field Summary

protected org.apache.commons.pool.impl.GenericObjectPool	connectionPool The object pool that internally manages our connections.
protected java.util.Properties	connectionProperties The connection properties that will be sent to our JDBC driver when establishing new connections.
protected javax.sql.DataSource	dataSource The data source we will use to manage connections.
protected boolean	defaultAutoCommit The default auto-commit state of connections created by this pool.
protected boolean	defaultReadOnly The default read-only state of connections created by this pool.
protected java.lang.String	driverClassName The fully qualified Java class name of the JDBC driver to be used.
protected java.io.PrintWriter	logWriter The PrintWriter to which log messages should be directed.
protected int	maxActive The maximum number of active connections that can be allocated from this pool at the same time, or zero for no limit.
protected int	maxIdle The maximum number of active connections that can remain idle in the pool, without extra ones being released, or zero for no limit.
protected long	maxWait The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
protected java.lang.String	password The connection password to be passed to our JDBC driver to establish a connection.
protected java.lang.String	url The connection URL to be passed to our JDBC driver to establish a connection.
protected java.lang.String	username The connection username to be passed to our JDBC driver to establish a connection.
protected java.lang.String	validationQuery The SQL query that will be used to validate connections from this pool before returning them to the caller.

Constructor Summary

BasicDataSource()

Method Summary

void	addConnectionProperty(java.lang.String name, java.lang.String value) Add a custom connection property to the set that will be passed to our JDBC driver.
void	close() Close and release all connections that are currently stored in the connection pool associated with our data source.
protected javax.sql.DataSource	createDataSource() Create (if necessary) and return the internal data source we are using to manage our connections.
java.sql.Connection	getConnection() Create (if necessary) and return a connection to the database.
java.sql.Connection	getConnection(java.lang.String username, java.lang.String password) Create (if necessary) and return a connection to the database.
boolean	getDefaultAutoCommit()
boolean	getDefaultReadOnly()
java.lang.String	getDriverClassName()
boolean	getLogAbandoned() Flag to log stack traces for application code which abandoned a Statement or Connection.
int	getLoginTimeout() Return the login timeout (in seconds) for connecting to the database.
java.io.PrintWriter	getLogWriter() Return the log writer being used by this data source.
int	getMaxActive()
int	getMaxIdle()
long	getMaxWait()
int	getNumActive() [Read Only] The current number of active connections that have been allocated from this data source.
int	getNumIdle() [Read Only] The current number of idle connections that are waiting to be allocated from this data source.
java.lang.String	getPassword()
boolean	getRemoveAbandoned() Flag to remove abandoned connections if they exceed the removeAbandonedTimout.
int	getRemoveAbandonedTimeout() Timeout in seconds before an abandoned connection can be removed.
java.lang.String	getUrl()
java.lang.String	getUsername()
java.lang.String	getValidationQuery()
void	setDefaultAutoCommit(boolean defaultAutoCommit)
void	setDefaultReadOnly(boolean defaultReadOnly)
void	setDriverClassName(java.lang.String driverClassName)
void	setLogAbandoned(boolean logAbandoned)
void	setLoginTimeout(int loginTimeout) Set the login timeout (in seconds) for connecting to the database.
void	setLogWriter(java.io.PrintWriter logWriter) Set the log writer being used by this data source.
void	setMaxActive(int maxActive)
void	setMaxIdle(int maxIdle)
void	setMaxWait(long maxWait)
void	setPassword(java.lang.String password)
void	setRemoveAbandoned(boolean removeAbandoned)
void	setRemoveAbandonedTimeout(int removeAbandonedTimeout)
void	setUrl(java.lang.String url)
void	setUsername(java.lang.String username)
void	setValidationQuery(java.lang.String validationQuery)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

connectionPool

protected org.apache.commons.pool.impl.GenericObjectPool connectionPool

The object pool that internally manages our connections.

connectionProperties

protected java.util.Properties connectionProperties

The connection properties that will be sent to our JDBC driver when establishing new connections. NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.

dataSource

protected javax.sql.DataSource dataSource

The data source we will use to manage connections. This object should be acquired ONLY by calls to the createDataSource() method.

defaultAutoCommit

protected boolean defaultAutoCommit

The default auto-commit state of connections created by this pool.

defaultReadOnly

protected boolean defaultReadOnly

The default read-only state of connections created by this pool.

driverClassName

protected java.lang.String driverClassName

The fully qualified Java class name of the JDBC driver to be used.

logWriter

protected java.io.PrintWriter logWriter

The PrintWriter to which log messages should be directed.

maxActive

protected int maxActive

The maximum number of active connections that can be allocated from this pool at the same time, or zero for no limit.

maxIdle

protected int maxIdle

The maximum number of active connections that can remain idle in the pool, without extra ones being released, or zero for no limit.

maxWait

protected long maxWait

The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.

password

protected java.lang.String password

The connection password to be passed to our JDBC driver to establish a connection.

url

protected java.lang.String url

The connection URL to be passed to our JDBC driver to establish a connection.

username

protected java.lang.String username

The connection username to be passed to our JDBC driver to establish a connection.

validationQuery

protected java.lang.String validationQuery

The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query MUST be an SQL SELECT statement that returns at least one row.

Constructor Detail

BasicDataSource

public BasicDataSource()

Method Detail

addConnectionProperty

public void addConnectionProperty(java.lang.String name,
                                  java.lang.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).

Parameters:

name - Name of the custom connection property

value - Value of the custom connection property

close

public void close()
           throws java.sql.SQLException

Close and release all connections that are currently stored in the connection pool associated with our data source.

Throws:

java.sql.SQLException - if a database error occurs

createDataSource

protected javax.sql.DataSource createDataSource()
                                         throws java.sql.SQLException

Create (if necessary) and return the internal data source we are using to manage our connections.

IMPLEMENTATION NOTE - It is tempting to use the "double checked locking" idiom in an attempt to avoid synchronizing on every single call to this method. However, this idiom fails to work correctly in the face of some optimizations that are legal for a JVM to perform.

Throws:

java.sql.SQLException - if the object pool cannot be created.

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException

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

Specified by:

getConnection in interface javax.sql.DataSource

Throws:

java.sql.SQLException - if a database access error occurs

getConnection

public java.sql.Connection getConnection(java.lang.String username,
                                         java.lang.String password)
                                  throws java.sql.SQLException

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

Specified by:

getConnection in interface javax.sql.DataSource

Parameters:

username - Database user on whose behalf the Connection is being made

password - The database user's password

Throws:

java.sql.SQLException - if a database access error occurs

getDefaultAutoCommit

public boolean getDefaultAutoCommit()

getDefaultReadOnly

public boolean getDefaultReadOnly()

getDriverClassName

public java.lang.String getDriverClassName()

getLogAbandoned

public boolean getLogAbandoned()

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()
                    throws java.sql.SQLException

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

Specified by:

getLoginTimeout in interface javax.sql.DataSource

Throws:

java.sql.SQLException - if a database access error occurs

getLogWriter

public java.io.PrintWriter getLogWriter()
                                 throws java.sql.SQLException

Return the log writer being used by this data source.

Specified by:

getLogWriter in interface javax.sql.DataSource

Throws:

java.sql.SQLException - if a database access error occurs

getMaxActive

public int getMaxActive()

getMaxIdle

public int getMaxIdle()

getMaxWait

public long getMaxWait()

getNumActive

public int getNumActive()

[Read Only] The current number of active connections that have been allocated from this data source.

getNumIdle

public int getNumIdle()

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

getPassword

public java.lang.String getPassword()

getRemoveAbandoned

public boolean getRemoveAbandoned()

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()

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

getUrl

public java.lang.String getUrl()

getUsername

public java.lang.String getUsername()

getValidationQuery

public java.lang.String getValidationQuery()

setDefaultAutoCommit

public void setDefaultAutoCommit(boolean defaultAutoCommit)

setDefaultReadOnly

public void setDefaultReadOnly(boolean defaultReadOnly)

setDriverClassName

public void setDriverClassName(java.lang.String driverClassName)

setLogAbandoned

public void setLogAbandoned(boolean logAbandoned)

setLoginTimeout

public void setLoginTimeout(int loginTimeout)
                     throws java.sql.SQLException

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

Specified by:

setLoginTimeout in interface javax.sql.DataSource

Parameters:

loginTimeout - The new login timeout, or zero for no timeout

Throws:

java.sql.SQLException - if a database access error occurs

setLogWriter

public void setLogWriter(java.io.PrintWriter logWriter)
                  throws java.sql.SQLException

Set the log writer being used by this data source.

Specified by:

setLogWriter in interface javax.sql.DataSource

Parameters:

logWriter - The new log writer

Throws:

java.sql.SQLException - if a database access error occurs

setMaxActive

public void setMaxActive(int maxActive)

setMaxIdle

public void setMaxIdle(int maxIdle)

setMaxWait

public void setMaxWait(long maxWait)

setPassword

public void setPassword(java.lang.String password)

setRemoveAbandoned

public void setRemoveAbandoned(boolean removeAbandoned)

setRemoveAbandonedTimeout

public void setRemoveAbandonedTimeout(int removeAbandonedTimeout)

setUrl

public void setUrl(java.lang.String url)

setUsername

public void setUsername(java.lang.String username)

setValidationQuery

public void setValidationQuery(java.lang.String validationQuery)