com.caucho.sql
Class DBPoolImpl

java.lang.Object
  extended by com.caucho.sql.DBPoolImpl
All Implemented Interfaces:
EnvironmentListener, AlarmListener, java.util.EventListener

public class DBPoolImpl
extends java.lang.Object
implements AlarmListener, EnvironmentListener

Manages a pool of database connections. In addition, DBPool configures the database connection from a configuration file.

Like JDBC 2.0 pooling, DBPool returns a wrapped Connection. Applications can use that connection just like an unpooled connection. It is more important than ever to close() the connection, because the close returns the connection to the connection pool.

Example using DataSource JNDI style (recommended)


 Context env = (Context) new InitialContext().lookup("java:comp/env");
 DataSource pool = (DataSource) env.lookup("jdbc/test");
 Connection conn = pool.getConnection();
 try {
   ... // normal connection stuff
 } finally {
   conn.close();
 }
 

Configuration


 <database name='jdbc/test'>
   <init>
     <driver>postgresql.Driver</driver>
     <url>jdbc:postgresql://localhost/test</url>
     <user>ferg</user>
     <password>foobar</password>
   </init>
 </database>
 

Pool limits and timeouts

The pool will only allow getMaxConnections() connections alive at a time. If getMaxConnection connections are already active, getPooledConnection will block waiting for an available connection. The wait is timed. If connection-wait-time passes and there is still no connection, getPooledConnection create a new connection anyway.

Connections will only stay in the pool for about 5 seconds. After that they will be removed and closed. This reduces the load on the DB and also protects against the database dropping old connections.


Field Summary
protected static java.util.logging.Logger log
           
static java.lang.String PROPERTY_PASSWORD
          The key used to look into the properties passed to the connect method to find the password.
static java.lang.String PROPERTY_USER
          The key used to look into the properties passed to the connect method to find the username.
 
Constructor Summary
DBPoolImpl()
          Null constructor for the Driver interface; called by the JNDI configuration.
 
Method Summary
 void close()
          Close the pool, closing the connections.
 void closeIdleConnections()
          Closes the idle connections in the pool.
 DriverConfig createBackupDriver()
          Returns the driver config.
 ConnectionConfig createConnection()
          Creates the connection config.
 DriverConfig createDriver()
          Returns the driver config.
 void environmentBind(EnvironmentClassLoader loader)
          Callback when the environment binds.
 void environmentConfigure(EnvironmentClassLoader loader)
          Callback when the environment configures.
 void environmentStart(EnvironmentClassLoader loader)
          Callback when the environment starts.
 void environmentStop(EnvironmentClassLoader loader)
          Callback when the class loader dies.
 void forceClose()
          Close all the connections in the pool.
 ConnectionConfig getConnectionConfig()
          Returns the connection config.
 long getConnectionWaitTime()
          Gets the time to wait for a connection when all are used.
 JdbcDriverMXBean[] getDriverAdmin()
          Returns the driver admin
 int getLoginTimeout()
          Gets the timeout for a database login.
 java.io.PrintWriter getLogWriter()
          Sets the debugging log for the connection.
 long getMaxActiveTime()
          Get the time in milliseconds a connection can remain active.
 int getMaxCloseStatements()
          Gets the max statement.
 int getMaxConnections()
          Get the maximum number of pooled connections.
 long getMaxIdleTime()
          Get the time in milliseconds a connection will remain in the pool before being closed.
 int getMaxOverflowConnections()
          The number of connections to overflow if the connection pool fills and there's a timeout.
 long getMaxPoolTime()
          Get the time in milliseconds a connection will remain in the pool before being closed.
 java.lang.String getName()
          Returns the Pool's name
 java.lang.String getPassword()
          Returns the connection's password
 long getPingInterval()
          Gets how often the ping for ping-on-idle
 boolean getPingOnIdle()
          If true, the pool will ping in the idle pool.
 boolean getPingOnReuse()
          If true, the pool will ping when attempting to reuse a connection.
 java.lang.String getPingQuery()
          Returns the ping query.
 java.lang.String getPingTable()
          Get the table to 'ping' to see if the connection is still live.
 int getPreparedStatementCacheSize()
          Returns the prepared statement cache size.
 SpyDataSource getSpyDataSource()
          Returns the next spy id.
 int getTotalConnections()
          Get the total number of connections
 long getTransactionTimeout()
          Gets the transaction timeout.
 java.lang.String getURL()
           
 java.lang.String getUser()
          Returns the connection's user.
 void handleAlarm(Alarm alarm)
          At the alarm, close all connections which have been sitting in the pool for too long.
 void init()
          Initialize the pool.
 boolean isClosed()
          Returns true if the pool is closed.
 boolean isLocalTransaction()
          Returns true if there is a valid local transactino associated with the database.
 boolean isPing()
          Returns true if pinging is enabled.
 boolean isSpy()
          Return true for a spy.
 boolean isTransactional()
          Returns true if the pool supports transactions.
 boolean isWrapStatements()
          Sets true if statements should be wrapped.
 boolean isXA()
          Returns true if this is transactional.
 boolean isXAForbidSameRM()
          Returns true if transactions should force isSameRM to be false.
 boolean isXATransaction()
          Returns true if there is a valid XAResource associated with the database.
 java.lang.String newSpyId(DriverConfig driver)
          Returns the next spy id.
 void setConnectionWaitTime(Period waitTime)
          Sets the time to wait for a connection when all are used.
 void setInitParam(InitParam init)
          Sets a driver parameter.
 void setJDBCDriver(java.sql.Driver jdbcDriver)
          Sets the jdbc-driver config.
 void setLoginTimeout(int seconds)
          Sets the timeout for a database login.
 void setLogWriter(java.io.PrintWriter out)
          Sets the debugging log for the connection.
 void setMaxActiveTime(Period maxActiveTime)
          Set the time in milliseconds a connection can remain active.
 void setMaxCloseStatements(int max)
          Sets the max statement.
 void setMaxConnections(int maxConnections)
          Sets the maximum number of pooled connections.
 void setMaxIdleTime(Period idleTime)
          Set the time in milliseconds a connection will remain in the pool before being closed.
 void setMaxOverflowConnections(int maxOverflowConnections)
          The number of connections to overflow if the connection pool fills and there's a timeout.
 void setMaxPoolTime(Period maxPoolTime)
          Set the time in milliseconds a connection will remain in the pool before being closed.
 void setName(java.lang.String name)
          Sets the Pool's name.
 void setPassword(java.lang.String password)
          Sets the connection's password
 void setPing(boolean ping)
          Set true if pinging is enabled.
 void setPingInterval(Period interval)
          Sets the time to ping for ping-on-idle
 void setPingOnIdle(boolean pingOnIdle)
          Set the table to 'ping' to see if the connection is still live.
 void setPingOnReuse(boolean pingOnReuse)
          Set the table to 'ping' to see if the connection is still live.
 void setPingQuery(java.lang.String pingQuery)
          Sets the ping query.
 void setPingTable(java.lang.String pingTable)
          Set the table to 'ping' to see if the connection is still live.
 void setPoolDataSource(javax.sql.ConnectionPoolDataSource poolDataSource)
          Sets the jdbc-driver config.
 void setPreparedStatementCacheSize(int size)
          Sets the prepared statement cache size.
 void setSpy(boolean isSpy)
          Set the output for spying.
 void setTransactionManager(TransactionManager tm)
          Set the transaction manager for this pool.
 void setTransactionTimeout(Period period)
          Sets the transaction timeout.
 void setURL(java.lang.String url)
          Sets the jdbc-driver config.
 void setUser(java.lang.String user)
          Sets the connection's user.
 void setWrapStatements(boolean isWrap)
          Sets true if statements should be wrapped.
 void setXA(boolean isTransactional)
          Returns true if this is transactional.
 void setXADataSource(javax.sql.XADataSource xaDataSource)
          Sets the jdbc-driver config.
 void setXAForbidSameRM(boolean isXAForbidSameRM)
          Returns true if transactions should force isSameRM to be false.
 java.lang.String toString()
          Returns a string description of the pool.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

log

protected static final java.util.logging.Logger log

PROPERTY_USER

public static final java.lang.String PROPERTY_USER
The key used to look into the properties passed to the connect method to find the username.

See Also:
Constant Field Values

PROPERTY_PASSWORD

public static final java.lang.String PROPERTY_PASSWORD
The key used to look into the properties passed to the connect method to find the password.

See Also:
Constant Field Values
Constructor Detail

DBPoolImpl

public DBPoolImpl()
Null constructor for the Driver interface; called by the JNDI configuration. Applications should not call this directly.

Method Detail

getName

public java.lang.String getName()
Returns the Pool's name


setName

public void setName(java.lang.String name)
Sets the Pool's name. Also puts the pool in the classloader's list of pools.


getURL

public java.lang.String getURL()

createDriver

public DriverConfig createDriver()
Returns the driver config.


createBackupDriver

public DriverConfig createBackupDriver()
Returns the driver config.


setInitParam

public void setInitParam(InitParam init)
Sets a driver parameter.


setJDBCDriver

public void setJDBCDriver(java.sql.Driver jdbcDriver)
                   throws java.sql.SQLException
Sets the jdbc-driver config.

Throws:
java.sql.SQLException

getDriverAdmin

public JdbcDriverMXBean[] getDriverAdmin()
Returns the driver admin


createConnection

public ConnectionConfig createConnection()
Creates the connection config.


getConnectionConfig

public ConnectionConfig getConnectionConfig()
Returns the connection config.


setPoolDataSource

public void setPoolDataSource(javax.sql.ConnectionPoolDataSource poolDataSource)
                       throws java.sql.SQLException
Sets the jdbc-driver config.

Throws:
java.sql.SQLException

setXADataSource

public void setXADataSource(javax.sql.XADataSource xaDataSource)
                     throws java.sql.SQLException
Sets the jdbc-driver config.

Throws:
java.sql.SQLException

setURL

public void setURL(java.lang.String url)
            throws ConfigException
Sets the jdbc-driver config.

Throws:
ConfigException

getUser

public java.lang.String getUser()
Returns the connection's user.


setUser

public void setUser(java.lang.String user)
Sets the connection's user.


getPassword

public java.lang.String getPassword()
Returns the connection's password


setPassword

public void setPassword(java.lang.String password)
Sets the connection's password


getMaxConnections

public int getMaxConnections()
Get the maximum number of pooled connections.


setMaxConnections

public void setMaxConnections(int maxConnections)
Sets the maximum number of pooled connections.


getTotalConnections

public int getTotalConnections()
Get the total number of connections


setConnectionWaitTime

public void setConnectionWaitTime(Period waitTime)
Sets the time to wait for a connection when all are used.


getConnectionWaitTime

public long getConnectionWaitTime()
Gets the time to wait for a connection when all are used.


setMaxOverflowConnections

public void setMaxOverflowConnections(int maxOverflowConnections)
The number of connections to overflow if the connection pool fills and there's a timeout.


getMaxOverflowConnections

public int getMaxOverflowConnections()
The number of connections to overflow if the connection pool fills and there's a timeout.


setTransactionTimeout

public void setTransactionTimeout(Period period)
Sets the transaction timeout.


getTransactionTimeout

public long getTransactionTimeout()
Gets the transaction timeout.


setMaxCloseStatements

public void setMaxCloseStatements(int max)
Sets the max statement.


getMaxCloseStatements

public int getMaxCloseStatements()
Gets the max statement.


setWrapStatements

public void setWrapStatements(boolean isWrap)
Sets true if statements should be wrapped.


isWrapStatements

public boolean isWrapStatements()
Sets true if statements should be wrapped.


getPreparedStatementCacheSize

public int getPreparedStatementCacheSize()
Returns the prepared statement cache size.


setPreparedStatementCacheSize

public void setPreparedStatementCacheSize(int size)
Sets the prepared statement cache size.


getMaxIdleTime

public long getMaxIdleTime()
Get the time in milliseconds a connection will remain in the pool before being closed.


setMaxIdleTime

public void setMaxIdleTime(Period idleTime)
Set the time in milliseconds a connection will remain in the pool before being closed.


getMaxPoolTime

public long getMaxPoolTime()
Get the time in milliseconds a connection will remain in the pool before being closed.


setMaxPoolTime

public void setMaxPoolTime(Period maxPoolTime)
Set the time in milliseconds a connection will remain in the pool before being closed.


getMaxActiveTime

public long getMaxActiveTime()
Get the time in milliseconds a connection can remain active.


setMaxActiveTime

public void setMaxActiveTime(Period maxActiveTime)
Set the time in milliseconds a connection can remain active.


getPingTable

public java.lang.String getPingTable()
Get the table to 'ping' to see if the connection is still live.


setPingTable

public void setPingTable(java.lang.String pingTable)
Set the table to 'ping' to see if the connection is still live.

Parameters:
pingTable - name of the SQL table to ping.

getPingQuery

public java.lang.String getPingQuery()
Returns the ping query.


setPingQuery

public void setPingQuery(java.lang.String pingQuery)
Sets the ping query.


getPingOnReuse

public boolean getPingOnReuse()
If true, the pool will ping when attempting to reuse a connection.


setPingOnReuse

public void setPingOnReuse(boolean pingOnReuse)
Set the table to 'ping' to see if the connection is still live.


getPingOnIdle

public boolean getPingOnIdle()
If true, the pool will ping in the idle pool.


setPingOnIdle

public void setPingOnIdle(boolean pingOnIdle)
Set the table to 'ping' to see if the connection is still live.


setPing

public void setPing(boolean ping)
Set true if pinging is enabled.


isPing

public boolean isPing()
Returns true if pinging is enabled.


setPingInterval

public void setPingInterval(Period interval)
Sets the time to ping for ping-on-idle


getPingInterval

public long getPingInterval()
Gets how often the ping for ping-on-idle


setTransactionManager

public void setTransactionManager(TransactionManager tm)
Set the transaction manager for this pool.


isXA

public boolean isXA()
Returns true if this is transactional.


setXA

public void setXA(boolean isTransactional)
Returns true if this is transactional.


isXAForbidSameRM

public boolean isXAForbidSameRM()
Returns true if transactions should force isSameRM to be false.


setXAForbidSameRM

public void setXAForbidSameRM(boolean isXAForbidSameRM)
Returns true if transactions should force isSameRM to be false.


setSpy

public void setSpy(boolean isSpy)
Set the output for spying.


isSpy

public boolean isSpy()
Return true for a spy.


getSpyDataSource

public SpyDataSource getSpyDataSource()
Returns the next spy id.


newSpyId

public java.lang.String newSpyId(DriverConfig driver)
Returns the next spy id.


isTransactional

public boolean isTransactional()
Returns true if the pool supports transactions.


isXATransaction

public boolean isXATransaction()
Returns true if there is a valid XAResource associated with the database.


isLocalTransaction

public boolean isLocalTransaction()
Returns true if there is a valid local transactino associated with the database.


setLoginTimeout

public void setLoginTimeout(int seconds)
                     throws java.sql.SQLException
Sets the timeout for a database login.

Throws:
java.sql.SQLException

getLoginTimeout

public int getLoginTimeout()
                    throws java.sql.SQLException
Gets the timeout for a database login.

Throws:
java.sql.SQLException

setLogWriter

public void setLogWriter(java.io.PrintWriter out)
                  throws java.sql.SQLException
Sets the debugging log for the connection.

Throws:
java.sql.SQLException

getLogWriter

public java.io.PrintWriter getLogWriter()
                                 throws java.sql.SQLException
Sets the debugging log for the connection.

Throws:
java.sql.SQLException

init

public void init()
          throws java.lang.Exception
Initialize the pool.

Throws:
java.lang.Exception

closeIdleConnections

public void closeIdleConnections()
Closes the idle connections in the pool.


handleAlarm

public void handleAlarm(Alarm alarm)
At the alarm, close all connections which have been sitting in the pool for too long.

Specified by:
handleAlarm in interface AlarmListener
Parameters:
alarm - the alarm event.

environmentConfigure

public void environmentConfigure(EnvironmentClassLoader loader)
Callback when the environment configures.

Specified by:
environmentConfigure in interface EnvironmentListener

environmentBind

public void environmentBind(EnvironmentClassLoader loader)
Callback when the environment binds.

Specified by:
environmentBind in interface EnvironmentListener

environmentStart

public void environmentStart(EnvironmentClassLoader loader)
Callback when the environment starts.

Specified by:
environmentStart in interface EnvironmentListener

environmentStop

public void environmentStop(EnvironmentClassLoader loader)
Callback when the class loader dies.

Specified by:
environmentStop in interface EnvironmentListener

isClosed

public boolean isClosed()
Returns true if the pool is closed.


close

public void close()
Close the pool, closing the connections.


forceClose

public void forceClose()
Close all the connections in the pool.


toString

public java.lang.String toString()
Returns a string description of the pool.

Overrides:
toString in class java.lang.Object