org.apache.commons.dbcp
Class BasicDataSource

java.lang.Object
  extended by org.apache.commons.dbcp.BasicDataSource
All Implemented Interfaces:
Wrapper, CommonDataSource, DataSource

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: 1.37 $ $Date: 2004/06/09 18:21:23 $

Field Summary
protected  GenericObjectPool connectionPool
          The object pool that internally manages our connections.
protected  Properties connectionProperties
          The connection properties that will be sent to our JDBC driver when establishing new connections.
protected  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  String defaultCatalog
          The default "catalog" of connections created by this pool.
protected  Boolean defaultReadOnly
          The default read-only state of connections created by this pool.
protected  int defaultTransactionIsolation
          The default TransactionIsolation state of connections created by this pool.
protected  String driverClassName
          The fully qualified Java class name of the JDBC driver to be used.
protected  int initialSize
          The initial number of connections that are created when the pool is started.
protected  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  int maxOpenPreparedStatements
          The maximum number of open statements that can be allocated from the statement pool at the same time, 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  long minEvictableIdleTimeMillis
          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).
protected  int minIdle
          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 numTestsPerEvictionRun
          The number of objects to examine during each run of the idle object evictor thread (if any).
protected  String password
          The connection password to be passed to our JDBC driver to establish a connection.
protected  boolean poolPreparedStatements
          Prepared statement pooling for this pool.
protected  boolean testOnBorrow
          The indication of whether objects will be validated before being borrowed from the pool.
protected  boolean testOnReturn
          The indication of whether objects will be validated before being returned to the pool.
protected  boolean testWhileIdle
          The indication of whether objects will be validated by the idle object evictor (if any).
protected  long timeBetweenEvictionRunsMillis
          The number of milliseconds to sleep between runs of the idle object evictor thread.
protected  String url
          The connection URL to be passed to our JDBC driver to establish a connection.
protected  String username
          The connection username to be passed to our JDBC driver to establish a connection.
protected  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(String name, 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  DataSource createDataSource()
          Create (if necessary) and return the internal data source we are using to manage our connections.
 Connection getConnection()
          Create (if necessary) and return a connection to the database.
 Connection getConnection(String username, String password)
          Create (if necessary) and return a connection to the database.
 boolean getDefaultAutoCommit()
           
 String getDefaultCatalog()
           
 boolean getDefaultReadOnly()
           
 int getDefaultTransactionIsolation()
           
 String getDriverClassName()
           
 int getInitialSize()
           
 boolean getLogAbandoned()
          Deprecated.  
 int getLoginTimeout()
          Return the login timeout (in seconds) for connecting to the database.
 PrintWriter getLogWriter()
          Return the log writer being used by this data source.
 int getMaxActive()
           
 int getMaxIdle()
           
 int getMaxOpenPreparedStatements()
           
 long getMaxWait()
           
 long getMinEvictableIdleTimeMillis()
           
 int getMinIdle()
           
 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.
 int getNumTestsPerEvictionRun()
           
 String getPassword()
           
 boolean getRemoveAbandoned()
          Deprecated.  
 int getRemoveAbandonedTimeout()
          Deprecated.  
 boolean getTestOnBorrow()
           
 boolean getTestOnReturn()
           
 boolean getTestWhileIdle()
           
 long getTimeBetweenEvictionRunsMillis()
           
 String getUrl()
           
 String getUsername()
           
 String getValidationQuery()
           
 boolean isAccessToUnderlyingConnectionAllowed()
          Returns the value of the accessToUnderlyingConnectionAllowed property.
 boolean isPoolPreparedStatements()
          Returns true if we are pooling statements.
 boolean isWrapperFor(Class<?> iface)
           
 void removeConnectionProperty(String name)
           
 void setAccessToUnderlyingConnectionAllowed(boolean allow)
          Sets the value of the accessToUnderlyingConnectionAllowed property.
 void setDefaultAutoCommit(boolean defaultAutoCommit)
           
 void setDefaultCatalog(String defaultCatalog)
           
 void setDefaultReadOnly(boolean defaultReadOnly)
           
 void setDefaultTransactionIsolation(int defaultTransactionIsolation)
           
 void setDriverClassName(String driverClassName)
           
 void setInitialSize(int initialSize)
           
 void setLogAbandoned(boolean logAbandoned)
          Deprecated.  
 void setLoginTimeout(int loginTimeout)
          Set the login timeout (in seconds) for connecting to the database.
 void setLogWriter(PrintWriter logWriter)
          Set the log writer being used by this data source.
 void setMaxActive(int maxActive)
           
 void setMaxIdle(int maxIdle)
           
 void setMaxOpenPreparedStatements(int maxOpenStatements)
           
 void setMaxWait(long maxWait)
           
 void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)
           
 void setMinIdle(int minIdle)
           
 void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
           
 void setPassword(String password)
           
 void setPoolPreparedStatements(boolean poolingStatements)
          Sets whether to pool statements or not.
 void setRemoveAbandoned(boolean removeAbandoned)
          Deprecated.  
 void setRemoveAbandonedTimeout(int removeAbandonedTimeout)
          Deprecated.  
 void setTestOnBorrow(boolean testOnBorrow)
           
 void setTestOnReturn(boolean testOnReturn)
           
 void setTestWhileIdle(boolean testWhileIdle)
           
 void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)
           
 void setUrl(String url)
           
 void setUsername(String username)
           
 void setValidationQuery(String validationQuery)
           
<T> T
unwrap(Class<T> iface)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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.


defaultTransactionIsolation

protected int defaultTransactionIsolation
The default TransactionIsolation state of connections created by this pool.


defaultCatalog

protected String defaultCatalog
The default "catalog" of connections created by this pool.


driverClassName

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


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.


minIdle

protected int minIdle
The minimum number of active connections that can remain idle in the pool, without extra ones being created, or 0 to create none.


initialSize

protected int initialSize
The initial number of connections that are created when the pool is started.

Since:
1.2

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.


poolPreparedStatements

protected boolean poolPreparedStatements
Prepared statement pooling for this pool.


maxOpenPreparedStatements

protected int maxOpenPreparedStatements
The maximum number of open statements that can be allocated from the statement pool at the same time, or zero for no limit. Since a connection usually only uses one or two statements at a time, this is mostly used to help detect resource leaks.


testOnBorrow

protected boolean testOnBorrow
The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.


testOnReturn

protected boolean testOnReturn
The indication of whether objects will be validated before being returned to the pool.


timeBetweenEvictionRunsMillis

protected long timeBetweenEvictionRunsMillis
The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.


numTestsPerEvictionRun

protected int numTestsPerEvictionRun
The number of objects to examine during each run of the idle object evictor thread (if any).


minEvictableIdleTimeMillis

protected long minEvictableIdleTimeMillis
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).


testWhileIdle

protected boolean testWhileIdle
The indication of whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.


password

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


url

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


username

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


validationQuery

protected 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.


connectionPool

protected GenericObjectPool connectionPool
The object pool that internally manages our connections.


connectionProperties

protected 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 DataSource dataSource
The data source we will use to manage connections. This object should be acquired ONLY by calls to the createDataSource() method.


logWriter

protected PrintWriter logWriter
The PrintWriter to which log messages should be directed.

Constructor Detail

BasicDataSource

public BasicDataSource()
Method Detail

getDefaultAutoCommit

public boolean getDefaultAutoCommit()

setDefaultAutoCommit

public void setDefaultAutoCommit(boolean defaultAutoCommit)

getDefaultReadOnly

public boolean getDefaultReadOnly()

setDefaultReadOnly

public void setDefaultReadOnly(boolean defaultReadOnly)

getDefaultTransactionIsolation

public int getDefaultTransactionIsolation()

setDefaultTransactionIsolation

public void setDefaultTransactionIsolation(int defaultTransactionIsolation)

getDefaultCatalog

public String getDefaultCatalog()

setDefaultCatalog

public void setDefaultCatalog(String defaultCatalog)

getDriverClassName

public String getDriverClassName()

setDriverClassName

public void setDriverClassName(String driverClassName)

getMaxActive

public int getMaxActive()

setMaxActive

public void setMaxActive(int maxActive)

getMaxIdle

public int getMaxIdle()

setMaxIdle

public void setMaxIdle(int maxIdle)

getMinIdle

public int getMinIdle()

setMinIdle

public void setMinIdle(int minIdle)

getInitialSize

public int getInitialSize()

setInitialSize

public void setInitialSize(int initialSize)

getMaxWait

public long getMaxWait()

setMaxWait

public void setMaxWait(long maxWait)

isPoolPreparedStatements

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

Returns:
boolean

setPoolPreparedStatements

public void setPoolPreparedStatements(boolean poolingStatements)
Sets whether to pool statements or not.

Parameters:
poolPreparedStatements - pooling on or off

getMaxOpenPreparedStatements

public int getMaxOpenPreparedStatements()

setMaxOpenPreparedStatements

public void setMaxOpenPreparedStatements(int maxOpenStatements)

getTestOnBorrow

public boolean getTestOnBorrow()

setTestOnBorrow

public void setTestOnBorrow(boolean testOnBorrow)

getTestOnReturn

public boolean getTestOnReturn()

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)

getTimeBetweenEvictionRunsMillis

public long getTimeBetweenEvictionRunsMillis()

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis)

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)

getMinEvictableIdleTimeMillis

public long getMinEvictableIdleTimeMillis()

setMinEvictableIdleTimeMillis

public void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis)

getTestWhileIdle

public boolean getTestWhileIdle()

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)

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

setPassword

public void setPassword(String password)

getUrl

public String getUrl()

setUrl

public void setUrl(String url)

getUsername

public String getUsername()

setUsername

public void setUsername(String username)

getValidationQuery

public String getValidationQuery()

setValidationQuery

public void setValidationQuery(String validationQuery)

isAccessToUnderlyingConnectionAllowed

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

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

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)

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

getConnection

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

Specified by:
getConnection in interface DataSource
Throws:
SQLException - if a database access error occurs

getConnection

public Connection getConnection(String username,
                                String password)
                         throws SQLException
Create (if necessary) and return a connection to the database.

Specified by:
getConnection in interface DataSource
Parameters:
username - Database user on whose behalf the Connection is being made
password - The database user's password
Throws:
SQLException - if a database access error occurs

getLoginTimeout

public int getLoginTimeout()
                    throws SQLException
Return the login timeout (in seconds) for connecting to the database.

Specified by:
getLoginTimeout in interface CommonDataSource
Throws:
SQLException - if a database access error occurs

getLogWriter

public PrintWriter getLogWriter()
                         throws SQLException
Return the log writer being used by this data source.

Specified by:
getLogWriter in interface CommonDataSource
Throws:
SQLException - if a database access error occurs

setLoginTimeout

public void setLoginTimeout(int loginTimeout)
                     throws SQLException
Set the login timeout (in seconds) for connecting to the database.

Specified by:
setLoginTimeout in interface CommonDataSource
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)
                  throws SQLException
Set the log writer being used by this data source.

Specified by:
setLogWriter in interface CommonDataSource
Parameters:
logWriter - The new log writer
Throws:
SQLException - if a database access error occurs

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.


setRemoveAbandoned

public void setRemoveAbandoned(boolean removeAbandoned)
Deprecated. 

Parameters:
removeAbandoned -

getRemoveAbandonedTimeout

public int getRemoveAbandonedTimeout()
Deprecated. 

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


setRemoveAbandonedTimeout

public void setRemoveAbandonedTimeout(int removeAbandonedTimeout)
Deprecated. 

Parameters:
removeAbandonedTimeout -

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.


setLogAbandoned

public void setLogAbandoned(boolean logAbandoned)
Deprecated. 

Parameters:
logAbandoned -

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

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

removeConnectionProperty

public void removeConnectionProperty(String name)

close

public void close()
           throws SQLException
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

createDataSource

protected DataSource createDataSource()
                               throws 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:
SQLException - if the object pool cannot be created.

unwrap

public <T> T unwrap(Class<T> iface)
         throws SQLException
Specified by:
unwrap in interface Wrapper
Throws:
SQLException

isWrapperFor

public boolean isWrapperFor(Class<?> iface)
                     throws SQLException
Specified by:
isWrapperFor in interface Wrapper
Throws:
SQLException


Copyright © 2001-2009 The Apache Software Foundation. All Rights Reserved.