snaq.db
Class DBPoolDataSource

java.lang.Object
  extended by 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

Constructor Summary
DBPoolDataSource()
          Creates a new DBPoolDataSource instance.
 
Method Summary
 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)
           
 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
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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.


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