com.jnetdirect.jsql
Class JSQLPoolingDataSource

java.lang.Object
  extended by com.jnetdirect.datasource.BaseDatasource
      extended by com.jnetdirect.jsql.JSQLDataSource
          extended by com.jnetdirect.jsql.JSQLConnectionPoolDataSource
              extended by com.jnetdirect.jsql.JSQLPoolingDataSource
All Implemented Interfaces:
java.io.Serializable, java.sql.Wrapper, javax.naming.Referenceable, javax.sql.CommonDataSource, javax.sql.ConnectionPoolDataSource, javax.sql.DataSource

public class JSQLPoolingDataSource
extends JSQLConnectionPoolDataSource

PoolingDataSource is a fully JDBC 2.0 compliant connection pool manager for pooling database connections. Please note that PoolingDataSource is not typically used in managed environments (e.g.application servers) that already provide a built-in connection pooling implementation. However, it may be used in any environment if required. For example, if the existing connection pool manager provides less features than PoolingDataSource.

In a basic DataSource implementation, there is a 1:1 correspondence between the client's connection object and the physical database connection. When the connection object is closed, the physical connection is dropped. Thus, the overhead of opening, initializing, and closing the physical connection is incurred for each client connection.

PoolingDataSource solves this problem by maintaining a cache of physical database connections that can be reused across client sessions. Connection pooling greatly improves performance and scalability, particularly in a three-tier environment where multiple clients can share a smaller number of physical database connections.

Your application requires no code changes to take advantage of connection pooling. Simply acquire your database connections from PoolingDataSource and they will be pooled automatically. It is recommended that your application close pooled database connections at the earliest point when they are no longer required so that they may be returned to the pool for use by other processes. PoolingDataSources may be dynamically created by the application or instantiated from JNDI after they are registered with JNDI registration. JNDI usage is recommended to faciliate application portability to other JDBC datasources.

PoolingDataSource provides a wide range of paramters to control the management and behavior of connections pools. For example, PoolingDataSource properties may be configured to specify :-

  • The initial number of connections in the pool or no initial size.
  • The maximum number of connections in the pool or no maximum.
  • The minimum number of connections in the pool or no minimum.
  • The maximum time after which connections should be removed from the pool.
  • The number of seconds interval to be used for the management thread to manage to manage the connection and idle time characteristics of the pool
  • The number of seconds interval to be used for the propagation of specified characteristics to the connection pool.

    The properties for the connection pool can be set using the properties documented for JSQLDataSource and BaseDataSource.

    If the connection pool detects that a physical connection encountered a network error while communicating with the database that connection will be removed from the pool. Property connectionVerifyTable may be used to validate that existing connections in the pool are still valid.

    See Also:
    Serialized Form

    Field Summary
     
    Fields inherited from class com.jnetdirect.datasource.BaseDatasource
    debugLog
     
    Constructor Summary
    JSQLPoolingDataSource()
               
     
    Method Summary
     void closeAllConnections()
              Close all connections in the connection pool.
     int getAvailableConnectionCount()
              Return the total number of physical connections currently available.
     java.sql.Connection getConnection()
              Obtain a database connection using the datasource user and password properties.
     java.sql.Connection getConnection(java.lang.String user, java.lang.String password)
              Obtain a database connection using the supplied user and password properties.
     int getConnectionCount()
              Return the total number of physical connections open in the pool.
     int getErroredConnectionCount()
              Return the total number of physical connections that were removed from the pool due to errors in their connections.
     java.lang.Exception getLastPhysicalException()
              Return the most recent physical connectivity exception, if any.
     java.util.Date getLastPhysicalExceptionDate()
              Return the most recent physical connectivity exception date(time), if any.
     int getLogicalOpennedCount()
              Return the total number of logical connections issued.
     java.lang.String getStatus()
              Get the pool status.
     int getTimeOutConnectionCount()
              Return the total number of physical connections that were closed because they exceeded the idle time for timeout setting.
     int getUsedConnectionCount()
              Return the total number of physical connections currently in use.
     boolean isWrapperFor(java.lang.Class iface)
               
     java.lang.Object unwrap(java.lang.Class iface)
               
     
    Methods inherited from class com.jnetdirect.jsql.JSQLConnectionPoolDataSource
    getPooledConnection, getPooledConnection
     
    Methods inherited from class com.jnetdirect.jsql.JSQLDataSource
    getApplicationName, getAsciiStringParameters, getBooleanLiterals, getCodepage, getConnectionRetryCount, getConnectionRetryWait, getDisableStatementPooling, getDomain, getEnableFailover, getInstanceName, getIterativeBatching, getLastUpdateCount, getLockTimeout, getNetLibType, getPacketSize, getPreExecuteMetaData, getSelectMethod, getSqlVersion, getSsl, getSslTrusted, getTrustedAuthentication, getTrustedAuthenticationPort, getXopenStates, setApplicationName, setAsciiStringParameters, setBooleanLiterals, setCodepage, setConnectionRetryCount, setConnectionRetryWait, setDisableStatementPooling, setDomain, setEnableFailover, setInstanceName, setIterativeBatching, setLastUpdateCount, setLockTimeout, setNetLibType, setPacketSize, setPreExecuteMetaData, setSelectMethod, setSqlVersion, setSsl, setSslTrusted, setTrustedAuthentication, setTrustedAuthenticationPort, setXopenStates
     
    Methods inherited from class com.jnetdirect.datasource.BaseDatasource
    getConnectionVerifyTable, getDatabase, getDatabaseName, getDescription, getInitialPoolSize, getLogfile, getLoginTimeout, getLogWriter, getManagementCycleTime, getMaxConnectionBacklog, getMaxIdleTime, getMaxPoolSize, getMinPoolSize, getPassword, getPortNumber, getProperties, getPropertyCycle, getReference, getServerName, getUrl, getURL, getUser, setConnectionVerifyTable, setDatabase, setDatabaseName, setDescription, setInitialPoolSize, setLogfile, setLoginTimeout, setLogWriter, setManagementCycleTime, setMaxConnectionBacklog, setMaxIdleTime, setMaxPoolSize, setMinPoolSize, setPassword, setPortNumber, setProperties, setProperty, setPropertyCycle, setServerName, setUrl, setURL, setUser
     
    Methods inherited from class java.lang.Object
    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     
    Methods inherited from interface javax.sql.CommonDataSource
    getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter
     

    Constructor Detail

    JSQLPoolingDataSource

    public JSQLPoolingDataSource()
    Method Detail

    getConnection

    public java.sql.Connection getConnection()
                                      throws java.sql.SQLException
    Description copied from class: BaseDatasource
    Obtain a database connection using the datasource user and password properties.

    Specified by:
    getConnection in interface javax.sql.DataSource
    Overrides:
    getConnection in class JSQLDataSource
    Returns:
    A new JDBC connection
    Throws:
    java.sql.SQLException - The database connection failed.

    getConnection

    public java.sql.Connection getConnection(java.lang.String user,
                                             java.lang.String password)
                                      throws java.sql.SQLException
    Description copied from class: BaseDatasource
    Obtain a database connection using the supplied user and password properties. The supplied username and password will override any username or password set as datasource properties.

    Specified by:
    getConnection in interface javax.sql.DataSource
    Overrides:
    getConnection in class JSQLDataSource
    Parameters:
    user - The user name for the connection
    password - The password for the connection
    Returns:
    A new JDBC Connection
    Throws:
    java.sql.SQLException - The database connection failed.

    getStatus

    public java.lang.String getStatus()
    Get the pool status.

    Returns:
    A string summarizing the pool's current operating status.

    closeAllConnections

    public void closeAllConnections()
                             throws java.sql.SQLException
    Close all connections in the connection pool.

    Throws:
    java.sql.SQLException

    getConnectionCount

    public int getConnectionCount()
    Return the total number of physical connections open in the pool.


    getUsedConnectionCount

    public int getUsedConnectionCount()
    Return the total number of physical connections currently in use.


    getAvailableConnectionCount

    public int getAvailableConnectionCount()
    Return the total number of physical connections currently available.


    getErroredConnectionCount

    public int getErroredConnectionCount()
    Return the total number of physical connections that were removed from the pool due to errors in their connections.


    getTimeOutConnectionCount

    public int getTimeOutConnectionCount()
    Return the total number of physical connections that were closed because they exceeded the idle time for timeout setting.


    getLogicalOpennedCount

    public int getLogicalOpennedCount()
    Return the total number of logical connections issued.


    getLastPhysicalException

    public java.lang.Exception getLastPhysicalException()
    Return the most recent physical connectivity exception, if any. *

    Returns:
    The exception or null if no physical exception has been generated in the pool.

    getLastPhysicalExceptionDate

    public java.util.Date getLastPhysicalExceptionDate()
    Return the most recent physical connectivity exception date(time), if any. *

    Returns:
    The date(time) or null if no physical exception has been generated in the pool.

    isWrapperFor

    public boolean isWrapperFor(java.lang.Class iface)
                         throws java.sql.SQLException
    Specified by:
    isWrapperFor in interface java.sql.Wrapper
    Overrides:
    isWrapperFor in class JSQLConnectionPoolDataSource
    Throws:
    java.sql.SQLException

    unwrap

    public java.lang.Object unwrap(java.lang.Class iface)
                            throws java.sql.SQLException
    Specified by:
    unwrap in interface java.sql.Wrapper
    Overrides:
    unwrap in class JSQLConnectionPoolDataSource
    Throws:
    java.sql.SQLException