snaq.db
Class DBPoolDataSource

java.lang.Object
  snaq.db.DBPoolDataSource

All Implemented Interfaces:

Wrapper, EventListener, CommonDataSource, DataSource, ConnectionPoolListener

public class DBPoolDataSource
extends Object
implements DataSource, ConnectionPoolListener

A DataSource implementation which produces Connection instances. This implementation internally references a ConnectionPool which it uses to provide transparent connection pooling to the client.

Author:

Giles Winstanley

Field Summary

protected Driver	driver Driver to use for database access.
protected static org.apache.commons.logging.Log	logger Apache Commons Logging shared instance for writing log entries.
protected PrintWriter	logWriter PrintWriter instance used for logging.
protected ConnectionPool	pool ConnectionPool instance used to source connections.
protected static String	POOL_NAME_PREFIX Name prefix to use for ConnectionPool instance (JNDI name is appended).

Constructor Summary

DBPoolDataSource()
Creates a new DBPoolDataSource instance.

Method Summary

protected void	createConnectionPool() Creates a new DBPoolDataSource instance.
Connection	getConnection() Attempts to establish a connection with the database.
Connection	getConnection(String username, String password) Attempts to establish a connection with the database.
String	getDescription() Returns the description of this DataSource.
String	getDriverClassName() Returns the fully-qualified class name for the JDBC driver to use.
int	getExpiryTime() Deprecated. Use getIdleTimeout() instead.
int	getIdleTimeout() Returns the idle timeout (seconds) for connections in the underlying ConnectionPool.
int	getLoginTimeout()
PrintWriter	getLogWriter() Retrieves the log writer for this DataSource.
int	getMaxPool() Returns the maximum number of pooled connections in the underlying ConnectionPool.
int	getMaxSize() Returns the maximum number of connections in the underlying ConnectionPool.
int	getMinPool() Returns the minimum number of pooled connections in the underlying ConnectionPool.
String	getName() Returns the JNDI name of the DBPoolDataSource instance.
String	getPassword() Returns the password to use with this DataSource.
String	getPasswordDecoderClassName() Returns the class name of the PasswordDecoder to use with this DataSource.
String	getUrl() Returns the JDBC URL to use with this DataSource.
String	getUser() Returns the username to use with this DataSource.
String	getUsername() Deprecated. Use getUser() method instead.
String	getValidationQuery() Returns the SQL query string to issue for connection validation.
String	getValidatorClassName() Returns the class name of the ConnectionValidator to use with this DataSource.
boolean	isWrapperFor(Class<?> iface)
protected void	log(String message) Writes a message to the log.
protected void	log(String message, Throwable throwable) Writes a message with a Throwable to the log file.
void	maxPoolLimitExceeded(ConnectionPoolEvent evt) Called when a check-out request causes the maxPool limit to be exceeded.
void	maxPoolLimitReached(ConnectionPoolEvent evt) Called when a check-out request causes the maxPool limit to be reached.
void	maxSizeLimitError(ConnectionPoolEvent evt) Called when a check-out request attempts to exceed the maxSize limit.
void	maxSizeLimitReached(ConnectionPoolEvent evt) Called when a check-out request causes the maxSize limit to be reached.
void	poolCheckIn(ConnectionPoolEvent evt) Called when a connection is checked back in to the pool.
void	poolCheckOut(ConnectionPoolEvent evt) Called when a connection is checked out of the pool.
void	poolFlushed(ConnectionPoolEvent evt) Called when the pool is flushed of free/unused connections.
void	poolInitCompleted(ConnectionPoolEvent evt) Called when the pool's ObjectPool.init(int) method has completed.
void	poolParametersChanged(ConnectionPoolEvent evt) Called when the pool's parameters are changed.
void	poolReleased(ConnectionPoolEvent evt) Called when the pool is released (no more events are fired by the pool after this event).
void	registerShutdownHook() Registers a shutdown hook for this ConnectionPoolManager instance to ensure it is released if the JVM exits
void	release() Releases the delegate ConnectionPool instance.
void	releaseAsync() Asynchronously releases the delegate ConnectionPool instance.
void	releaseConnectionPool() Releases (cleans up resources of) the internal ConnectionPool instance.
void	releaseForcibly() Forcibly releases the delegate ConnectionPool instance.
void	removeShutdownHook() Deregisters a registered shutdown hook for this ConnectionPoolManager instance.
void	setDescription(String description) Sets the description of this DataSource.
void	setDriverClassName(String driverClassName) Sets the fully-qualified class name for the JDBC driver to use.
void	setExpiryTime(int idleTimeout) Deprecated. Use setIdleTimeout(int) instead.
void	setIdleTimeout(int idleTimeout) Sets the idle timeout (seconds) for connections in the underlying ConnectionPool.
void	setLoginTimeout(int seconds) Sets the maximum time in seconds that this DataSource will wait while attempting to connect to a database.
void	setLogWriter(PrintWriter out) Sets the log writer for this DataSource to the given PrintWriter.
void	setMaxPool(int maxPool) Sets the maximum number of pooled connections in the underlying ConnectionPool.
void	setMaxSize(int maxSize) Sets the maximum number of connections in the underlying ConnectionPool.
void	setMinPool(int minPool) Sets the minimum number of pooled connections in the underlying ConnectionPool.
void	setName(String name) Sets the JNDI name of the DBPoolDataSource instance.
void	setPassword(String password) Sets the password to use with this DataSource.
void	setPasswordDecoderClassName(String decoderClassName) Sets the class name of the PasswordDecoder to use with this DataSource.
void	setUrl(String url) Sets the JDBC URL to use with this DataSource.
void	setUser(String user) Sets the username to use with this DataSource.
void	setUsername(String username) Deprecated. Use setUser(String) method instead.
void	setValidationQuery(String validationQuery) Sets the SQL query string to issue for connection validation.
void	setValidatorClassName(String validatorClassName) Sets the class name of the ConnectionValidator to use with this DataSource.
String	toString()
<T> T	unwrap(Class<T> iface)
void	validationError(ConnectionPoolEvent evt) Called when a connection is found to be invalid.

Methods inherited from class java.lang.Object

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

Field Detail

POOL_NAME_PREFIX

protected static final String POOL_NAME_PREFIX

Name prefix to use for ConnectionPool instance (JNDI name is appended).

See Also:

Constant Field Values

logger

protected static final org.apache.commons.logging.Log logger

Apache Commons Logging shared instance for writing log entries.

driver

protected transient Driver driver

Driver to use for database access.

pool

protected transient ConnectionPool pool

ConnectionPool instance used to source connections.

logWriter

protected transient PrintWriter logWriter

PrintWriter instance used for logging.

Constructor Detail

DBPoolDataSource

public DBPoolDataSource()

Creates a new DBPoolDataSource instance.

Method Detail

registerShutdownHook

public void registerShutdownHook()

Registers a shutdown hook for this ConnectionPoolManager instance to ensure it is released if the JVM exits

removeShutdownHook

public void removeShutdownHook()

Deregisters a registered shutdown hook for this ConnectionPoolManager instance.

log

protected void log(String message)

Writes a message to the log.

log

protected void log(String message,
                   Throwable throwable)

Writes a message with a Throwable to the log file.

createConnectionPool

protected void createConnectionPool()
                             throws SQLException

Creates a new DBPoolDataSource instance.

Throws:

SQLException - if required resources cannot be located/established

getConnection

public Connection getConnection()
                         throws SQLException

Attempts to establish a connection with the database.

Specified by:

getConnection in interface DataSource

Returns:

a Connection instance, or null if unable to connect

Throws:

SQLException - if a database access error occurs

getConnection

public Connection getConnection(String username,
                                String password)
                         throws SQLException

Attempts to establish a connection with the database.

Specified by:

getConnection in interface DataSource

Parameters:

username - the database user on whose behalf the connection is being made

password - the user's password

Returns:

a Connection instance, or null if unable to connect

Throws:

SQLException - if a database access error occurs

releaseConnectionPool

public void releaseConnectionPool()

Releases (cleans up resources of) the internal ConnectionPool instance. This method should be called to close all the pooled connections.

getDescription

public String getDescription()

Returns the description of this DataSource.

setDescription

public void setDescription(String description)

Sets the description of this DataSource.

getUser

public String getUser()

Returns the username to use with this DataSource.

getUsername

@Deprecated
public String getUsername()

Deprecated. Use getUser() method instead.

Alias for getUser().

setUser

public void setUser(String user)

Sets the username to use with this DataSource.

setUsername

@Deprecated
public void setUsername(String username)

Deprecated. Use setUser(String) method instead.

Alias for setUser(String).

getPassword

public String getPassword()

Returns the password to use with this DataSource.

setPassword

public void setPassword(String password)

Sets the password to use with this DataSource.

getName

public String getName()

Returns the JNDI name of the DBPoolDataSource instance.

setName

public void setName(String name)

Sets the JNDI name of the DBPoolDataSource instance.

getDriverClassName

public String getDriverClassName()

Returns the fully-qualified class name for the JDBC driver to use.

setDriverClassName

public void setDriverClassName(String driverClassName)

Sets the fully-qualified class name for the JDBC driver to use.

getPasswordDecoderClassName

public String getPasswordDecoderClassName()

Returns the class name of the PasswordDecoder to use with this DataSource.

setPasswordDecoderClassName

public void setPasswordDecoderClassName(String decoderClassName)

Sets the class name of the PasswordDecoder to use with this DataSource. The specified class should implement the PasswordDecoder interface, and have a no-argument constructor which can be used to instantiate it for use.

getValidatorClassName

public String getValidatorClassName()

Returns the class name of the ConnectionValidator to use with this DataSource.

setValidatorClassName

public void setValidatorClassName(String validatorClassName)

Sets the class name of the ConnectionValidator to use with this DataSource. The specified class should implement the ConnectionValidator interface, and have a no-argument constructor which can be used to instantiate it for use.

getValidationQuery

public String getValidationQuery()

Returns the SQL query string to issue for connection validation. This query is only used if the validationClassName has not been explicitly set, in which case this query string is used with an instance of SimpleQueryValidator.

setValidationQuery

public void setValidationQuery(String validationQuery)

Sets the SQL query string to issue for connection validation. This query is only used if the validationClassName has not been explicitly set, in which case this query string is used with an instance of SimpleQueryValidator.

getUrl

public String getUrl()

Returns the JDBC URL to use with this DataSource.

setUrl

public void setUrl(String url)

Sets the JDBC URL to use with this DataSource.

getMinPool

public int getMinPool()

Returns the minimum number of pooled connections in the underlying ConnectionPool.

setMinPool

public void setMinPool(int minPool)

Sets the minimum number of pooled connections in the underlying ConnectionPool.

getMaxPool

public int getMaxPool()

Returns the maximum number of pooled connections in the underlying ConnectionPool.

setMaxPool

public void setMaxPool(int maxPool)

Sets the maximum number of pooled connections in the underlying ConnectionPool.

getMaxSize

public int getMaxSize()

Returns the maximum number of connections in the underlying ConnectionPool.

setMaxSize

public void setMaxSize(int maxSize)

Sets the maximum number of connections in the underlying ConnectionPool.

getIdleTimeout

public int getIdleTimeout()

Returns the idle timeout (seconds) for connections in the underlying ConnectionPool.

setIdleTimeout

public void setIdleTimeout(int idleTimeout)

Sets the idle timeout (seconds) for connections in the underlying ConnectionPool.

getExpiryTime

@Deprecated
public int getExpiryTime()

Deprecated. Use getIdleTimeout() instead.

Returns the idle timeout (seconds) for connections in the underlying ConnectionPool.

setExpiryTime

@Deprecated
public void setExpiryTime(int idleTimeout)

Deprecated. Use setIdleTimeout(int) instead.

Sets the idle timeout (seconds) for connections in the underlying ConnectionPool.

getLogWriter

public PrintWriter getLogWriter()

Retrieves the log writer for this DataSource.

Specified by:

getLogWriter in interface CommonDataSource

setLogWriter

public void setLogWriter(PrintWriter out)

Sets the log writer for this DataSource to the given PrintWriter.

Specified by:

setLogWriter in interface CommonDataSource

Parameters:

out - the new log writer; to disable logging, set to null

setLoginTimeout

public void setLoginTimeout(int seconds)

Sets the maximum time in seconds that this DataSource will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout. When a DataSource object is created, the login timeout is initially zero.

Specified by:

setLoginTimeout in interface CommonDataSource

Parameters:

seconds - the DataSource login time limit

getLoginTimeout

public int getLoginTimeout()

Specified by:

getLoginTimeout in interface CommonDataSource

release

public void release()

Releases the delegate ConnectionPool instance.

releaseAsync

public void releaseAsync()

Asynchronously releases the delegate ConnectionPool instance.

releaseForcibly

public void releaseForcibly()

Forcibly releases the delegate ConnectionPool instance.

toString

public String toString()

Overrides:

toString in class Object

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

poolInitCompleted

public void poolInitCompleted(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when the pool's ObjectPool.init(int) method has completed.

Specified by:

poolInitCompleted in interface ConnectionPoolListener

poolCheckOut

public void poolCheckOut(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a connection is checked out of the pool.

Specified by:

poolCheckOut in interface ConnectionPoolListener

poolCheckIn

public void poolCheckIn(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a connection is checked back in to the pool.

Specified by:

poolCheckIn in interface ConnectionPoolListener

validationError

public void validationError(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a connection is found to be invalid.

Specified by:

validationError in interface ConnectionPoolListener

maxPoolLimitReached

public void maxPoolLimitReached(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a check-out request causes the maxPool limit to be reached.

Specified by:

maxPoolLimitReached in interface ConnectionPoolListener

maxPoolLimitExceeded

public void maxPoolLimitExceeded(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a check-out request causes the maxPool limit to be exceeded.

Specified by:

maxPoolLimitExceeded in interface ConnectionPoolListener

maxSizeLimitReached

public void maxSizeLimitReached(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a check-out request causes the maxSize limit to be reached. (maxSize is equivalent to maxConn)

Specified by:

maxSizeLimitReached in interface ConnectionPoolListener

maxSizeLimitError

public void maxSizeLimitError(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when a check-out request attempts to exceed the maxSize limit. (maxSize is equivalent to maxConn)

Specified by:

maxSizeLimitError in interface ConnectionPoolListener

poolFlushed

public void poolFlushed(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when the pool is flushed of free/unused connections.

Specified by:

poolFlushed in interface ConnectionPoolListener

poolParametersChanged

public void poolParametersChanged(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when the pool's parameters are changed.

Specified by:

poolParametersChanged in interface ConnectionPoolListener

poolReleased

public void poolReleased(ConnectionPoolEvent evt)

Description copied from interface: ConnectionPoolListener

Called when the pool is released (no more events are fired by the pool after this event).

Specified by:

poolReleased in interface ConnectionPoolListener