org.apache.commons.dbcp.datasources

Class InstanceKeyDataSource

Implemented Interfaces:
DataSource, Referenceable, Serializable
Known Direct 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 catalina and JNDI and it also contains a non-JNDI example.

Version:
$Revision: 1.11 $ $Date: 2004/02/28 12:18:17 $
Author:
John D. McNally

Constructor Summary

InstanceKeyDataSource()
Default no-arg constructor for Serialization

Method Summary

abstract void
close()
Close pool being maintained by this datasource.
Connection
getConnection()
Attempt to establish a database connection.
Connection
getConnection(String username, String password)
Attempt to establish a database connection.
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.
PrintWriter
getLogWriter()
Get the value of logWriter.
int
getLoginTimeout()
Get the value of loginTimeout.
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).
Reference
getReference()
Referenceable implementation prepares object for binding in jndi.
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
isTestOnBorrow()
boolean
isTestOnReturn()
boolean
isTestWhileIdle()
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)
Set the value of jndiEnvironment which is used when instantiating a jndi InitialContext.
void
setLogWriter(PrintWriter v)
Set the value of logWriter.
void
setLoginTimeout(int v)
Set the value of loginTimeout.
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
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.
void
setValidationQuery(String validationQuery)
The SQL query that will be used to validate connections from this pool before returning them to the caller.

Constructor Details

InstanceKeyDataSource

public InstanceKeyDataSource()
Default no-arg constructor for Serialization

Method Details

close

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

getConnection

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

getConnection

public Connection getConnection(String username,
                                String password)
            throws SQLException
Attempt to establish a database connection.

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.

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.

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.

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.

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.

getLogWriter

public PrintWriter getLogWriter()
Get the value of logWriter.
Returns:
value of logWriter.

getLoginTimeout

public int getLoginTimeout()
Get the value of loginTimeout.
Returns:
value of loginTimeout.

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

getNumTestsPerEvictionRun

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

getReference

public Reference getReference()
            throws NamingException
Referenceable implementation prepares object for binding in jndi.

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.

getTestOnReturn

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

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.

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.

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.

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.

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.

isTestOnBorrow

public final boolean isTestOnBorrow()

isTestOnReturn

public final boolean isTestOnReturn()

isTestWhileIdle

public final boolean isTestWhileIdle()

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.

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.

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.

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.

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

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.

setJndiEnvironment

public void setJndiEnvironment(String key,
                               String value)
Set the value of jndiEnvironment which is used when instantiating a jndi InitialContext. This InitialContext is used to locate the backend ConnectionPoolDataSource.
Parameters:

setLogWriter

public void setLogWriter(PrintWriter v)
Set the value of logWriter.
Parameters:
v - Value to assign to logWriter.

setLoginTimeout

public void setLoginTimeout(int v)
Set the value of loginTimeout.
Parameters:
v - Value to assign to loginTimeout.

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.

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.


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.

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

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.

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.

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. Default behavior is to test the connection when it is borrowed.

Copyright © 2001-2003 Apache Software Foundation. Documenation generated December 22 2005.