org.apache.commons.dbcp.datasources
Class InstanceKeyDataSource

java.lang.Object
  extended by org.apache.commons.dbcp.datasources.InstanceKeyDataSource
All Implemented Interfaces:
Serializable, Wrapper, Referenceable, CommonDataSource, DataSource
Direct Known Subclasses:
PerUserPoolDataSource, SharedPoolDataSource

public abstract class InstanceKeyDataSource
extends Object
implements DataSource, Referenceable, Serializable

The base class for SharedPoolDataSource and PerUserPoolDataSource. Many of the configuration properties are shared and defined here. This class is declared public in order to allow particular usage with commons-beanutils; do not make direct use of it outside of commons-dbcp.

A J2EE container will normally provide some method of initializing the DataSource whose attributes are presented as bean getters/setters and then deploying it via JNDI. It is then available to an application as a source of pooled logical connections to the database. The pool needs a source of physical connections. This source is in the form of a ConnectionPoolDataSource that can be specified via the setDataSourceName(String) used to lookup the source via JNDI.

Although normally used within a JNDI environment, A DataSource can be instantiated and initialized as any bean. In this case the ConnectionPoolDataSource will likely be instantiated in a similar manner. This class allows the physical source of connections to be attached directly to this pool using the setConnectionPoolDataSource(ConnectionPoolDataSource) method.

The dbcp package contains an adapter, DriverAdapterCPDS, that can be used to allow the use of DataSource's based on this class with jdbc driver implementations that do not supply a ConnectionPoolDataSource, but still provide a Driver implementation.

The package documentation contains an example using Apache Tomcat and JNDI and it also contains a non-JNDI example.

Version:
$Revision: 907428 $ $Date: 2010-02-07 09:59:08 -0500 (Sun, 07 Feb 2010) $
Author:
John D. McNally
See Also:
Serialized Form

Field Summary
protected  String instanceKey
          Instance key
protected static int UNKNOWN_TRANSACTIONISOLATION
          Internal constant to indicate the level is not set.
 
Constructor Summary
InstanceKeyDataSource()
          Default no-arg constructor for Serialization
 
Method Summary
protected  void assertInitializationAllowed()
          Throws an IllegalStateException, if a PooledConnection has already been requested.
abstract  void close()
          Close the connection pool being maintained by this datasource.
 Connection getConnection()
          Attempt to establish a database connection.
 Connection getConnection(String username, String password)
          Attempt to retrieve a database connection using getPooledConnectionAndInfo(String, String) with the provided username and password.
protected abstract  org.apache.commons.dbcp.datasources.PooledConnectionManager getConnectionManager(org.apache.commons.dbcp.datasources.UserPassKey upkey)
           
 ConnectionPoolDataSource getConnectionPoolDataSource()
          Get the value of connectionPoolDataSource.
 String getDataSourceName()
          Get the name of the ConnectionPoolDataSource which backs this pool.
 int getDefaultTransactionIsolation()
          Get the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool.
 String getDescription()
          Get the description.
 String getJndiEnvironment(String key)
          Get the value of jndiEnvironment which is used when instantiating a jndi InitialContext.
 int getLoginTimeout()
          Get the value of loginTimeout.
 PrintWriter getLogWriter()
          Get the value of logWriter.
 int getMinEvictableIdleTimeMillis()
          Returns 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).
 int getNumTestsPerEvictionRun()
          Returns the number of objects to examine during each run of the idle object evictor thread (if any).
protected abstract  org.apache.commons.dbcp.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo(String username, String password)
           
 Reference getReference()
          Retrieves the Reference of this object.
 boolean getTestOnBorrow()
          When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method.
 boolean getTestOnReturn()
          When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}.
 boolean getTestWhileIdle()
          When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any).
 int getTimeBetweenEvictionRunsMillis()
          Returns the number of milliseconds to sleep between runs of the idle object evictor thread.
 String getValidationQuery()
          The SQL query that will be used to validate connections from this pool before returning them to the caller.
 boolean isDefaultAutoCommit()
          Get the value of defaultAutoCommit, which defines the state of connections handed out from this pool.
 boolean isDefaultReadOnly()
          Get the value of defaultReadOnly, which defines the state of connections handed out from this pool.
 boolean isRollbackAfterValidation()
          Whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller.
 boolean isTestOnBorrow()
           
 boolean isTestOnReturn()
           
 boolean isTestWhileIdle()
           
 boolean isWrapperFor(Class<?> iface)
           
 void setConnectionPoolDataSource(ConnectionPoolDataSource v)
          Set the backend ConnectionPoolDataSource.
 void setDataSourceName(String v)
          Set the name of the ConnectionPoolDataSource which backs this pool.
 void setDefaultAutoCommit(boolean v)
          Set the value of defaultAutoCommit, which defines the state of connections handed out from this pool.
 void setDefaultReadOnly(boolean v)
          Set the value of defaultReadOnly, which defines the state of connections handed out from this pool.
 void setDefaultTransactionIsolation(int v)
          Set the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool.
 void setDescription(String v)
          Set the description.
 void setJndiEnvironment(String key, String value)
          Sets the value of the given JNDI environment property to be used when instantiating a JNDI InitialContext.
 void setLoginTimeout(int v)
          Set the value of loginTimeout.
 void setLogWriter(PrintWriter v)
          Set the value of logWriter.
 void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)
          Sets 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).
 void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
          Sets the number of objects to examine during each run of the idle object evictor thread (if any).
 void setRollbackAfterValidation(boolean rollbackAfterValidation)
          Whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller.
 void setTestOnBorrow(boolean testOnBorrow)
          When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method.
 void setTestOnReturn(boolean testOnReturn)
          When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}.
 void setTestWhileIdle(boolean testWhileIdle)
          When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any).
 void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis)
          Sets the number of milliseconds to sleep between runs of the idle object evictor thread.
protected abstract  void setupDefaults(Connection con, String username)
           
 void setValidationQuery(String validationQuery)
          The SQL query that will be used to validate connections from this pool before returning them to the caller.
protected  ConnectionPoolDataSource testCPDS(String username, String password)
           
<T> T
unwrap(Class<T> iface)
           
protected  byte whenExhaustedAction(int maxActive, int maxWait)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNKNOWN_TRANSACTIONISOLATION

protected static final int UNKNOWN_TRANSACTIONISOLATION
Internal constant to indicate the level is not set.

See Also:
Constant Field Values

instanceKey

protected String instanceKey
Instance key

Constructor Detail

InstanceKeyDataSource

public InstanceKeyDataSource()
Default no-arg constructor for Serialization

Method Detail

assertInitializationAllowed

protected void assertInitializationAllowed()
                                    throws IllegalStateException
Throws an IllegalStateException, if a PooledConnection has already been requested.

Throws:
IllegalStateException

close

public abstract void close()
                    throws Exception
Close the connection pool being maintained by this datasource.

Throws:
Exception

getConnectionManager

protected abstract org.apache.commons.dbcp.datasources.PooledConnectionManager getConnectionManager(org.apache.commons.dbcp.datasources.UserPassKey upkey)

isWrapperFor

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

unwrap

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

getConnectionPoolDataSource

public ConnectionPoolDataSource getConnectionPoolDataSource()
Get the value of connectionPoolDataSource. This method will return null, if the backing datasource is being accessed via jndi.

Returns:
value of connectionPoolDataSource.

setConnectionPoolDataSource

public void setConnectionPoolDataSource(ConnectionPoolDataSource v)
Set the backend ConnectionPoolDataSource. This property should not be set if using jndi to access the datasource.

Parameters:
v - Value to assign to connectionPoolDataSource.

getDataSourceName

public String getDataSourceName()
Get the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the datasource from a jndi service provider.

Returns:
value of dataSourceName.

setDataSourceName

public void setDataSourceName(String v)
Set the name of the ConnectionPoolDataSource which backs this pool. This name is used to look up the datasource from a jndi service provider.

Parameters:
v - Value to assign to dataSourceName.

isDefaultAutoCommit

public boolean isDefaultAutoCommit()
Get the value of defaultAutoCommit, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setAutoCommit(boolean). The default is true.

Returns:
value of defaultAutoCommit.

setDefaultAutoCommit

public void setDefaultAutoCommit(boolean v)
Set the value of defaultAutoCommit, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setAutoCommit(boolean). The default is true.

Parameters:
v - Value to assign to defaultAutoCommit.

isDefaultReadOnly

public boolean isDefaultReadOnly()
Get the value of defaultReadOnly, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setReadOnly(boolean). The default is false.

Returns:
value of defaultReadOnly.

setDefaultReadOnly

public void setDefaultReadOnly(boolean v)
Set the value of defaultReadOnly, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setReadOnly(boolean). The default is false.

Parameters:
v - Value to assign to defaultReadOnly.

getDefaultTransactionIsolation

public int getDefaultTransactionIsolation()
Get the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setTransactionIsolation(int). If this method returns -1, the default is JDBC driver dependent.

Returns:
value of defaultTransactionIsolation.

setDefaultTransactionIsolation

public void setDefaultTransactionIsolation(int v)
Set the value of defaultTransactionIsolation, which defines the state of connections handed out from this pool. The value can be changed on the Connection using Connection.setTransactionIsolation(int). The default is JDBC driver dependent.

Parameters:
v - Value to assign to defaultTransactionIsolation

getDescription

public String getDescription()
Get the description. This property is defined by jdbc as for use with GUI (or other) tools that might deploy the datasource. It serves no internal purpose.

Returns:
value of description.

setDescription

public void setDescription(String v)
Set the description. This property is defined by jdbc as for use with GUI (or other) tools that might deploy the datasource. It serves no internal purpose.

Parameters:
v - Value to assign to description.

getJndiEnvironment

public String getJndiEnvironment(String key)
Get the value of jndiEnvironment which is used when instantiating a jndi InitialContext. This InitialContext is used to locate the backend ConnectionPoolDataSource.

Returns:
value of jndiEnvironment.

setJndiEnvironment

public void setJndiEnvironment(String key,
                               String value)
Sets the value of the given JNDI environment property to be used when instantiating a JNDI InitialContext. This InitialContext is used to locate the backend ConnectionPoolDataSource.

Parameters:
key - the JNDI environment property to set.
value - the value assigned to specified JNDI environment property.

getLoginTimeout

public int getLoginTimeout()
Get the value of loginTimeout.

Specified by:
getLoginTimeout in interface CommonDataSource
Returns:
value of loginTimeout.

setLoginTimeout

public void setLoginTimeout(int v)
Set the value of loginTimeout.

Specified by:
setLoginTimeout in interface CommonDataSource
Parameters:
v - Value to assign to loginTimeout.

getLogWriter

public PrintWriter getLogWriter()
Get the value of logWriter.

Specified by:
getLogWriter in interface CommonDataSource
Returns:
value of logWriter.

setLogWriter

public void setLogWriter(PrintWriter v)
Set the value of logWriter.

Specified by:
setLogWriter in interface CommonDataSource
Parameters:
v - Value to assign to logWriter.

isTestOnBorrow

public final boolean isTestOnBorrow()
See Also:
getTestOnBorrow()

getTestOnBorrow

public boolean getTestOnBorrow()
When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.

See Also:
setTestOnBorrow(boolean)

setTestOnBorrow

public void setTestOnBorrow(boolean testOnBorrow)
When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned by the {*link #borrowObject} method. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. For a true value to have any effect, the validationQuery property must be set to a non-null string.

See Also:
getTestOnBorrow()

isTestOnReturn

public final boolean isTestOnReturn()
See Also:
getTestOnReturn()

getTestOnReturn

public boolean getTestOnReturn()
When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}.

See Also:
setTestOnReturn(boolean)

setTestOnReturn

public void setTestOnReturn(boolean testOnReturn)
When true, objects will be {*link PoolableObjectFactory#validateObject validated} before being returned to the pool within the {*link #returnObject}. For a true value to have any effect, the validationQuery property must be set to a non-null string.

See Also:
getTestOnReturn()

getTimeBetweenEvictionRunsMillis

public int getTimeBetweenEvictionRunsMillis()
Returns 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.

See Also:
setTimeBetweenEvictionRunsMillis(int)

setTimeBetweenEvictionRunsMillis

public void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis)
Sets 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.

See Also:
getTimeBetweenEvictionRunsMillis()

getNumTestsPerEvictionRun

public int getNumTestsPerEvictionRun()
Returns the number of objects to examine during each run of the idle object evictor thread (if any).

See Also:
setNumTestsPerEvictionRun(int), setTimeBetweenEvictionRunsMillis(int)

setNumTestsPerEvictionRun

public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun)
Sets the number of objects to examine during each run of the idle object evictor thread (if any).

When a negative value is supplied, ceil({*link #numIdle})/abs({*link #getNumTestsPerEvictionRun}) tests will be run. I.e., when the value is -n, roughly one nth of the idle objects will be tested per run.

See Also:
getNumTestsPerEvictionRun(), setTimeBetweenEvictionRunsMillis(int)

getMinEvictableIdleTimeMillis

public int getMinEvictableIdleTimeMillis()
Returns 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).

See Also:
setMinEvictableIdleTimeMillis(int), setTimeBetweenEvictionRunsMillis(int)

setMinEvictableIdleTimeMillis

public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis)
Sets 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). When non-positive, no objects will be evicted from the pool due to idle time alone.

See Also:
getMinEvictableIdleTimeMillis(), setTimeBetweenEvictionRunsMillis(int)

isTestWhileIdle

public final boolean isTestWhileIdle()
See Also:
getTestWhileIdle()

getTestWhileIdle

public boolean getTestWhileIdle()
When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.

See Also:
setTestWhileIdle(boolean), setTimeBetweenEvictionRunsMillis(int)

setTestWhileIdle

public void setTestWhileIdle(boolean testWhileIdle)
When true, objects will be {*link PoolableObjectFactory#validateObject validated} by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.

See Also:
getTestWhileIdle(), setTimeBetweenEvictionRunsMillis(int)

getValidationQuery

public String getValidationQuery()
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.


setValidationQuery

public void setValidationQuery(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. If none of the properties, testOnBorow, testOnReturn, testWhileIdle have been previously set, calling this method sets testOnBorrow to true.


isRollbackAfterValidation

public boolean isRollbackAfterValidation()
Whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller.

Returns:
true if a rollback will be issued after executing the validation query
Since:
1.2.2

setRollbackAfterValidation

public void setRollbackAfterValidation(boolean rollbackAfterValidation)
Whether a rollback will be issued after executing the SQL query that will be used to validate connections from this pool before returning them to the caller. Default behavior is NOT to issue a rollback. The setting will only have an effect if a validation query is set

Parameters:
rollbackAfterValidation - new property value
Since:
1.2.2

getConnection

public Connection getConnection()
                         throws SQLException
Attempt to establish a database connection.

Specified by:
getConnection in interface DataSource
Throws:
SQLException

getConnection

public Connection getConnection(String username,
                                String password)
                         throws SQLException
Attempt to retrieve a database connection using getPooledConnectionAndInfo(String, String) with the provided username and password. The password on the PooledConnectionAndInfo instance returned by getPooledConnectionAndInfo is compared to the password parameter. If the comparison fails, a database connection using the supplied username and password is attempted. If the connection attempt fails, an SQLException is thrown, indicating that the given password did not match the password used to create the pooled connection. If the connection attempt succeeds, this means that the database password has been changed. In this case, the PooledConnectionAndInfo instance retrieved with the old password is destroyed and the getPooledConnectionAndInfo is repeatedly invoked until a PooledConnectionAndInfo instance with the new password is returned.

Specified by:
getConnection in interface DataSource
Throws:
SQLException

getPooledConnectionAndInfo

protected abstract org.apache.commons.dbcp.datasources.PooledConnectionAndInfo getPooledConnectionAndInfo(String username,
                                                                                                          String password)
                                                                                                   throws SQLException
Throws:
SQLException

setupDefaults

protected abstract void setupDefaults(Connection con,
                                      String username)
                               throws SQLException
Throws:
SQLException

testCPDS

protected ConnectionPoolDataSource testCPDS(String username,
                                            String password)
                                     throws NamingException,
                                            SQLException
Throws:
NamingException
SQLException

whenExhaustedAction

protected byte whenExhaustedAction(int maxActive,
                                   int maxWait)

getReference

public Reference getReference()
                       throws NamingException
Retrieves the Reference of this object. Note: InstanceKeyDataSource subclasses should override this method. The implementaion included below is not robust and will be removed at the next major version DBCP release.

Specified by:
getReference in interface Referenceable
Returns:
The non-null Reference of this object.
Throws:
NamingException - If a naming exception was encountered while retrieving the reference.


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