DBPoolDataSource (DBPool 7.0.1 API)

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

Fields
Modifier and Type	Field and Description
`protected Driver`	`driver` `Driver` to use for database access.
`protected static org.slf4j.Logger`	`logger` SLF4J 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

Constructors
Constructor and Description

DBPoolDataSource()
Creates a new DBPoolDataSource instance.

Constructors
Constructor and Description
`DBPoolDataSource()` Creates a new `DBPoolDataSource` instance.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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`	`getConnectionProperty(String key)` Returns the driver property for the specified key.
`String`	`getDescription()` Returns the description of this DataSource.
`String`	`getDriverClassName()` Returns the fully-qualified class name for the JDBC driver to use.
`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.
`Logger`	`getParentLogger()`
`String`	`getPassword()` Returns the password to use with this DataSource.
`String`	`getPasswordDecoderClassName()` Returns the fully-qualified class name of the `PasswordDecoder`.
`String`	`getSelectionStrategy()` Returns a string denoting the pool selection strategy to use (one of LIFO/FIFO/RANDOM).
`String`	`getUrl()` Returns the JDBC URL to use with this DataSource.
`String`	`getUser()` Returns the username to use with this DataSource.
`String`	`getValidationQuery()` Returns the SQL query string to issue for connection validation.
`String`	`getValidatorClassName()` Returns the fully-qualified class name of the `ConnectionValidator`.
`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`	`release(long timeout)` Releases the delegate `ConnectionPool` instance allowing the specified timeout before forcibly destroying connections.
`void`	`releaseAsync()` Asynchronously releases the delegate `ConnectionPool` instance.
`void`	`releaseAsync(long timeout)` Asynchronously releases the delegate `ConnectionPool` instance.
`void`	`releaseConnectionPool()` Deprecated. Use `releaseImmediately()` instead
`void`	`releaseForcibly()` Deprecated. Use `releaseImmediately()` instead
`void`	`releaseImmediately()` Immediately releases the delegate `ConnectionPool` instance.
`void`	`removeShutdownHook()` Unregisters a registered shutdown hook for this ConnectionPoolManager instance.
`void`	`setConnectionProperty(String key, String value)` Sets the driver property for the specified key.
`void`	`setDescription(String description)` Sets the description of this DataSource.
`void`	`setDriverClassName(String driverClassName)` Sets the class name for the JDBC driver to use.
`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.
`void`	`setSelectionStrategy(String selection)` Sets the class name for the JDBC driver to use.
`void`	`setUrl(String url)` Sets the JDBC URL to use with this DataSource.
`void`	`setUser(String username)` Sets the username to use with this DataSource.
`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.
`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.slf4j.Logger logger
```
    SLF4J 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()
```
    Unregisters a registered shutdown hook for this ConnectionPoolManager instance.
  - log
```
protected void log(String message)
```
    Writes a message to the log.
    
    Parameters:
    
    message - message to write
  - log
```
protected void log(String message,
                   Throwable throwable)
```
    Writes a message with a Throwable to the log file.
    
    Parameters:
    
    message - message to write
    
    throwable - Throwable instance to log
  - 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
```
@Deprecated
public void releaseConnectionPool()
```
    Deprecated. Use releaseImmediately() instead
    
    Synonym for releaseImmediately() retained for backward compatibility; will be removed.
  - getDescription
```
public String getDescription()
```
    Returns the description of this DataSource.
    
    Returns:
    
    The description of this DataSource
  - setDescription
```
public void setDescription(String description)
```
    Sets the description of this DataSource.
    
    Parameters:
    
    description - description
  - getUser
```
public String getUser()
```
    Returns the username to use with this DataSource.
    
    Returns:
    
    The username to use with this DataSource
  - setUser
```
public void setUser(String username)
```
    Sets the username to use with this DataSource.
    
    Parameters:
    
    username - username
  - getPassword
```
public String getPassword()
```
    Returns the password to use with this DataSource.
    
    Returns:
    
    The password to use with this DataSource
  - setPassword
```
public void setPassword(String password)
```
    Sets the password to use with this DataSource.
    
    Parameters:
    
    password - password
  - getName
```
public String getName()
```
    Returns the JNDI name of the DBPoolDataSource instance.
    
    Returns:
    
    The JNDI name of the DBPoolDataSource instance
  - setName
```
public void setName(String name)
```
    Sets the JNDI name of the DBPoolDataSource instance.
    
    Parameters:
    
    name - JNDI name
  - getDriverClassName
```
public String getDriverClassName()
```
    Returns the fully-qualified class name for the JDBC driver to use.
    
    Returns:
    
    The fully-qualified class name for the JDBC driver to use
  - setDriverClassName
```
public void setDriverClassName(String driverClassName)
```
    Sets the class name for the JDBC driver to use.
    
    Parameters:
    
    driverClassName - fully-qualified driver class name to use
  - getPasswordDecoderClassName
```
public String getPasswordDecoderClassName()
```
    Returns the fully-qualified class name of the PasswordDecoder.
    
    Returns:
    
    The fully-qualified class name of the PasswordDecoder
  - setPasswordDecoderClassName
```
public void setPasswordDecoderClassName(String decoderClassName)
```
    Sets the class name of the PasswordDecoder to use. The specified class should implement the PasswordDecoder interface, and have a no-argument constructor which can be used to instantiate it for use.
    
    Parameters:
    
    decoderClassName - fully-qualified class name of password decoder to use
  - getValidatorClassName
```
public String getValidatorClassName()
```
    Returns the fully-qualified class name of the ConnectionValidator.
    
    Returns:
    
    The fully-qualified class name of the ConnectionValidator
  - setValidatorClassName
```
public void setValidatorClassName(String validatorClassName)
```
    Sets the class name of the ConnectionValidator to use. The specified class should implement the ConnectionValidator interface, and have a no-argument constructor which can be used to instantiate it for use.
    
    Parameters:
    
    validatorClassName - fully-qualified class name of validator to 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.
    
    Returns:
    
    SQL query string used for validation
  - 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.
    
    Parameters:
    
    validationQuery - SQL query to use for validation
  - getUrl
```
public String getUrl()
```
    Returns the JDBC URL to use with this DataSource.
    
    Returns:
    
    The JDBC URL to use with this DataSource
  - setUrl
```
public void setUrl(String url)
```
    Sets the JDBC URL to use with this DataSource.
    
    Parameters:
    
    url - JDBC URL to use
  - getMinPool
```
public int getMinPool()
```
    Returns the minimum number of pooled connections in the underlying ConnectionPool.
    
    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.
    
    Parameters:
    
    minPool - minimum number of pooled connections
  - getMaxPool
```
public int getMaxPool()
```
    Returns the maximum number of pooled connections in the underlying ConnectionPool.
    
    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.
    
    Parameters:
    
    maxPool - maximum number of pooled connections
  - getMaxSize
```
public int getMaxSize()
```
    Returns the maximum number of connections in the underlying ConnectionPool.
    
    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.
    
    Parameters:
    
    maxSize - maximum number of connections
  - getIdleTimeout
```
public int getIdleTimeout()
```
    Returns the idle timeout (seconds) for connections in the underlying ConnectionPool.
    
    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.
    
    Parameters:
    
    idleTimeout - idle timeout (seconds)
  - getConnectionProperty
```
public String getConnectionProperty(String key)
```
    Returns the driver property for the specified key.
    
    Parameters:
    
    key - property key
    
    Returns:
    
    the driver property for the specified key
  - setConnectionProperty
```
public void setConnectionProperty(String key,
                                  String value)
```
    Sets the driver property for the specified key.
    
    Parameters:
    
    key - property key
    
    value - value of property
  - getSelectionStrategy
```
public String getSelectionStrategy()
```
    Returns a string denoting the pool selection strategy to use (one of LIFO/FIFO/RANDOM).
    
    Returns:
    
    A string denoting the pool selection strategy to use (one of LIFO/FIFO/RANDOM)
  - setSelectionStrategy
```
public void setSelectionStrategy(String selection)
```
    Sets the class name for the JDBC driver to use.
    
    Parameters:
    
    selection - string representing pool selection strategy to use (one of LIFO/FIFO/RANDOM)
  - 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.
  - release
```
public void release(long timeout)
```
    Releases the delegate ConnectionPool instance allowing the specified timeout before forcibly destroying connections. A negative timeout is equivalent to no timeout, and the method will wait for items to be checked in before destruction. If timeout >= 0 then items will be forcibly destroyed after the specified time has elapsed.
    
    Parameters:
    
    timeout - timeout after which to forcibly destroy items (-1 for no timeout)
  - releaseAsync
```
public void releaseAsync()
```
    Asynchronously releases the delegate ConnectionPool instance.
  - releaseAsync
```
public void releaseAsync(long timeout)
```
    Asynchronously releases the delegate ConnectionPool instance.
    
    Parameters:
    
    timeout - timeout after which to forcibly destroy items (-1 for no timeout)
  - releaseForcibly
```
@Deprecated
public void releaseForcibly()
```
    Deprecated. Use releaseImmediately() instead
    
    Synonym for releaseImmediately() retained for backward compatibility; will be removed.
  - releaseImmediately
```
public void releaseImmediately()
```
    Immediately 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - 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
    
    Parameters:
    
    evt - event instance
  - getParentLogger
```
public Logger getParentLogger()
                       throws SQLFeatureNotSupportedException
```
    Specified by:
    
    getParentLogger in interface CommonDataSource
    
    Throws:
    
    SQLFeatureNotSupportedException

Class DBPoolDataSource

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

POOL_NAME_PREFIX

logger

driver

pool

logWriter

Constructor Detail

DBPoolDataSource

Method Detail

registerShutdownHook

removeShutdownHook

log

log

createConnectionPool

getConnection

getConnection

releaseConnectionPool

getDescription

setDescription

getUser

setUser

getPassword

setPassword

getName

setName

getDriverClassName

setDriverClassName

getPasswordDecoderClassName

setPasswordDecoderClassName

getValidatorClassName

setValidatorClassName

getValidationQuery

setValidationQuery

getUrl

setUrl

getMinPool

setMinPool

getMaxPool

setMaxPool

getMaxSize

setMaxSize

getIdleTimeout

setIdleTimeout

getConnectionProperty

setConnectionProperty

getSelectionStrategy

setSelectionStrategy

getLogWriter

setLogWriter

setLoginTimeout

getLoginTimeout

release

release

releaseAsync

releaseAsync

releaseForcibly

releaseImmediately

toString

isWrapperFor

unwrap

poolInitCompleted

poolCheckOut

poolCheckIn

validationError

maxPoolLimitReached

maxPoolLimitExceeded

maxSizeLimitReached

maxSizeLimitError

poolFlushed

poolParametersChanged

poolReleased

getParentLogger