com.caucho.sql
Class DBPool

java.lang.Object
  extended by com.caucho.sql.DBPool
All Implemented Interfaces:
HandleAware, java.io.Serializable, java.sql.Wrapper, javax.sql.CommonDataSource, javax.sql.DataSource

public class DBPool
extends java.lang.Object
implements javax.sql.DataSource, java.io.Serializable, HandleAware

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.

See Also:
Serialized Form

Field Summary
protected static java.util.logging.Logger log
           
 
Constructor Summary
DBPool()
          Null constructor for the Driver interface; called by the JNDI configuration.
 
Method Summary
 void add(javax.sql.ConnectionPoolDataSource dataSource)
          Adds a preconfigured driver using Java Injection syntax.
 void add(javax.sql.DataSource dataSource)
          Adds a preconfigured driver using Java Injection syntax.
 void add(javax.sql.XADataSource dataSource)
          Adds a preconfigured driver using Java Injection syntax.
 void addAnnotation(java.lang.annotation.Annotation ann)
          Adds an annotation
 void close()
           
 void closeIdleConnections()
          Clears the pool.
 DriverConfig createBackupDriver()
          Sets a custom driver (or data source)
 ConnectionConfig createConnection()
          Configure the initial connection
 DriverConfig createDriver()
          Sets a custom driver (or data source)
 int getActiveConnections()
          Get the total number of connections in use by the program.
 java.sql.Connection getConnection()
          Returns a new or pooled connection.
 java.sql.Connection getConnection(java.lang.String user, java.lang.String password)
          Return a connection.
 long getConnectionWaitTime()
          Gets the time to wait for a connection when all are used.
 JdbcDriverMXBean[] getDriverAdmin()
          Returns driver admin
 java.lang.String getJndiName()
          Returns the Pool's name
 int getLoginTimeout()
          Returns the login timeout
 java.io.PrintWriter getLogWriter()
          Gets the log writer
 long getMaxActiveTime()
          Get the time in milliseconds a connection can remain active.
 int getMaxConnections()
          Get the maximum number of pooled connections.
 int getMaxIdleCount()
          Get the maximum number of connections in the idle pool.
 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.
 int getMinIdleCount()
          Get the minimum number of connections in the idle pool.
 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 getPingTable()
          Get the table to 'ping' to see if the connection is still live.
 int getPreparedStatementCacheSize()
          Returns the prepared statement cache size.
 int getTotalConnections()
          Get the total number of connections
 java.lang.String getURL()
          Return the url
 java.lang.String getUser()
          Returns the connection's user (compat).
 void init()
          Initialize the pool.
 boolean isSpy()
          Returns true for spy
 boolean isWrapperFor(java.lang.Class<?> iface)
           
 boolean isXA()
          Returns true if this is transactional.
 void markForPoolRemoval(ManagedConnectionImpl mConn)
           
 void setCloseDanglingConnections(boolean isClose)
          Set true if dangling connections should be closed.
 void setConnectionWaitTime(Period waitTime)
          Sets the time to wait for a connection when all are used.
 void setInitParam(InitParam init)
          Sets a driver parameter (compat).
 void setJDBCDriver(java.sql.Driver jdbcDriver)
          Sets the jdbc-driver config.
 void setJndiName(java.lang.String name)
          Sets the Pool's JNDI name.
 void setLoginTimeout(int timeout)
          Sets the login timeout
 void setLogWriter(java.io.PrintWriter log)
          Sets the log writer
 void setMaxActiveTime(Period maxActiveTime)
          Set the time in milliseconds a connection can remain active.
 void setMaxConnections(int maxConnections)
          Sets the maximum number of pooled connections.
 void setMaxCreateConnections(int maxCreateConnections)
          The number of connections to create at any one time.
 void setMaxIdleCount(int count)
          Set the maximum number of connections in the idle pool.
 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 setMinIdleCount(int count)
          Set the minimum number of connections in the idle pool.
 void setName(java.lang.String name)
          Sets the Pool's WebBeans name.
 void setPassword(java.lang.String password)
          Sets the connection's password
 void setPing(boolean ping)
          Set the table to 'ping' to see if the connection is still live.
 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)
          Set the query to 'ping' to see if the connection is still live.
 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 setSaveAllocationStackTrace(boolean save)
          Set true if the stack trace should be saved on allocation.
 void setSerializationHandle(java.lang.Object handle)
          HandleAware callback to set the webbeans handle for serialization
 void setSpy(boolean isSpy)
          Set the output for spying.
 void setTransactionManager(TransactionManagerImpl 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 URL
 void setUser(java.lang.String user)
          Sets the connection's user.
 void setVar(java.lang.String var)
          Sets the Pool's var.
 void setWrapStatements(boolean isWrap)
          Set true if statement 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 this is transactional.
 java.lang.String toString()
          Returns a string description of the pool.
<T> T
unwrap(java.lang.Class<T> iface)
           
 
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
Constructor Detail

DBPool

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

Method Detail

getJndiName

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


setJndiName

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


setName

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


setVar

public void setVar(java.lang.String var)
Sets the Pool's var.


getName

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


addAnnotation

public void addAnnotation(java.lang.annotation.Annotation ann)
Adds an annotation


createDriver

public DriverConfig createDriver()
                          throws ConfigException
Sets a custom driver (or data source)

Throws:
ConfigException

createBackupDriver

public DriverConfig createBackupDriver()
                                throws ConfigException
Sets a custom driver (or data source)

Throws:
ConfigException

add

public void add(javax.sql.DataSource dataSource)
Adds a preconfigured driver using Java Injection syntax.


add

public void add(javax.sql.ConnectionPoolDataSource dataSource)
Adds a preconfigured driver using Java Injection syntax.


add

public void add(javax.sql.XADataSource dataSource)
Adds a preconfigured driver using Java Injection syntax.


setInitParam

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


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 driver admin


createConnection

public ConnectionConfig createConnection()
                                  throws ConfigException
Configure the initial connection

Throws:
ConfigException

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 URL

Throws:
ConfigException

getURL

public java.lang.String getURL()
Return the url


getUser

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


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)
                       throws ConfigException
Sets the maximum number of pooled connections.

Throws:
ConfigException

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.


setMaxCreateConnections

public void setMaxCreateConnections(int maxCreateConnections)
                             throws ConfigException
The number of connections to create at any one time.

Throws:
ConfigException

setSaveAllocationStackTrace

public void setSaveAllocationStackTrace(boolean save)
Set true if the stack trace should be saved on allocation.


setCloseDanglingConnections

public void setCloseDanglingConnections(boolean isClose)
Set true if dangling connections should be closed.


getMaxOverflowConnections

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


getActiveConnections

public int getActiveConnections()
Get the total number of connections in use by the program.


getMaxIdleCount

public int getMaxIdleCount()
Get the maximum number of connections in the idle pool.


setMaxIdleCount

public void setMaxIdleCount(int count)
Set the maximum number of connections in the idle pool. being closed.


getMinIdleCount

public int getMinIdleCount()
Get the minimum number of connections in the idle pool.


setMinIdleCount

public void setMinIdleCount(int count)
Set the minimum number of connections in the idle pool. being closed.


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.

setPingQuery

public void setPingQuery(java.lang.String pingQuery)
Set the query to 'ping' to see if the connection is still live.

Parameters:
pingQuery - SQL to use for ping.

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 the table to 'ping' to see if the connection is still live.


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


getPreparedStatementCacheSize

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


setPreparedStatementCacheSize

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


setTransactionManager

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


setWrapStatements

public void setWrapStatements(boolean isWrap)
Set true if statement should be wrapped.


setTransactionTimeout

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


isXA

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


setXA

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


setXAForbidSameRM

public void setXAForbidSameRM(boolean isXAForbidSameRM)
Returns true if this is transactional.


setSpy

public void setSpy(boolean isSpy)
            throws java.io.IOException
Set the output for spying.

Throws:
java.io.IOException

isSpy

public boolean isSpy()
Returns true for spy


setSerializationHandle

public void setSerializationHandle(java.lang.Object handle)
HandleAware callback to set the webbeans handle for serialization

Specified by:
setSerializationHandle in interface HandleAware

init

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

Throws:
java.lang.Exception

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
Returns a new or pooled connection.

Specified by:
getConnection in interface javax.sql.DataSource
Throws:
java.sql.SQLException

getConnection

public java.sql.Connection getConnection(java.lang.String user,
                                         java.lang.String password)
                                  throws java.sql.SQLException
Return a connection. The connection will only be pooled if user and password match the configuration. In general, applications should use the null-argument getConnection().

Specified by:
getConnection in interface javax.sql.DataSource
Parameters:
user - database user
password - database password
Returns:
a database connection
Throws:
java.sql.SQLException

closeIdleConnections

public void closeIdleConnections()
Clears the pool.


markForPoolRemoval

public void markForPoolRemoval(ManagedConnectionImpl mConn)

getLoginTimeout

public int getLoginTimeout()
                    throws java.sql.SQLException
Returns the login timeout

Specified by:
getLoginTimeout in interface javax.sql.CommonDataSource
Throws:
java.sql.SQLException

setLoginTimeout

public void setLoginTimeout(int timeout)
                     throws java.sql.SQLException
Sets the login timeout

Specified by:
setLoginTimeout in interface javax.sql.CommonDataSource
Throws:
java.sql.SQLException

getLogWriter

public java.io.PrintWriter getLogWriter()
                                 throws java.sql.SQLException
Gets the log writer

Specified by:
getLogWriter in interface javax.sql.CommonDataSource
Throws:
java.sql.SQLException

setLogWriter

public void setLogWriter(java.io.PrintWriter log)
                  throws java.sql.SQLException
Sets the log writer

Specified by:
setLogWriter in interface javax.sql.CommonDataSource
Throws:
java.sql.SQLException

unwrap

public <T> T unwrap(java.lang.Class<T> iface)
         throws java.sql.SQLException
Specified by:
unwrap in interface java.sql.Wrapper
Throws:
java.sql.SQLException

isWrapperFor

public boolean isWrapperFor(java.lang.Class<?> iface)
                     throws java.sql.SQLException
Specified by:
isWrapperFor in interface java.sql.Wrapper
Throws:
java.sql.SQLException

close

public void close()

toString

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

Overrides:
toString in class java.lang.Object