Skip navigation links

Oracle® Universal Connection Pool for JDBC Java API Reference
12c Release 1 (12.1)

E17662-07


oracle.ucp
Interface UniversalConnectionPool


public interface UniversalConnectionPool

A connection pool that pools any type of connection (called a physical connection).

There are several key objects that make up the connection pool:

Physical Pool The physical pool maintains pooled connections that can be borrowed from the pool, returned to the pool, or closed and not returned to the pool. The pool keeps track of the connections that are available (so that they can be borrowed) and connections that are in use (so they can be reaped if it is determined that they are no longer valid).

Connection Factory Adapter The connection pool must rely on another entity to create and close connections because connection pools can pool any type of connection. This is the responsibility of the connection factory adapter. A connection factory adapter is tied to a specific resource (JDBC, JCA, LDAP, and so forth). When the connection pool needs to create a new connection, it asks the connection factory adapter to do so. The returned connection is placed inside a UniversalPooledConnection object that is then placed into the connection pool. When the connection pool closes a connection, it hands the connection to the connection factory adapter which then closes the connection.

Pooled Connections Each pooled connection in the connection pool is an instance of UniversalPooledConnection. The pooled connection decorates a physical connection (created by the connection factory adapter) which can be borrowed.

Connection Retrieval Info The connection retrieval info object is used by the connection factory adapter to create connections. It contains resource-specific information that the connection factory adapter uses to create connections. For example, the JDBC connection retrieval info object maintains the user and password that are used to create a connection from a JDBC resource. The JCA connection retrieval info object maintains the Subject and JCA ConnectionRequestInfo object.

Pool Properties The pool provides some properties for users to customize the pool's behavior, such as:

Statistics The pool maintains some statistics such as:

Lifecycle A connection pool has a lifecycle. See UniversalConnectionPoolLifeCycleState for details. A connection pool is started by calling the start() method and stopped by calling the stop() method. Connections may not be borrowed until the connection pool has been started or after the pool has been stopped (unless the pool has been started again).

See Also:
UniversalPooledConnection, ConnectionFactoryAdapter, ConnectionRetrievalInfo, UniversalConnectionPoolStatistics, UniversalConnectionPoolLifeCycleState

Method Summary
 UniversalPooledConnection borrowConnection(ConnectionRetrievalInfo connectionRetrievalInfo)
          Gets a connection from the connection pool.
 void closeConnection(UniversalPooledConnection pooledConnection)
          Closes the pooled connection.
 int getAbandonedConnectionTimeout()
          Gets the abandoned connection timeout value.
 int getAvailableConnectionsCount()
          Gets the number of connections that are available in the connection pool (that is, connections in the pool that are not currently in use by clients).
 int getBorrowedConnectionsCount()
          Gets the number of connections that are actively in use by clients.
 int getConnectionHarvestMaxCount()
          Gets the maximum number of connections that may be harvested when the connection harvesting occurs.
 int getConnectionHarvestTriggerCount()
          Gets the number of available connections below which the connection pool's connection harvesting occurs.
 ConnectionRetrievalInfo getConnectionRetrievalInfo()
          Gets the ConnectionRetrievalInfo object which contains user and password information to create the connections.
 int getConnectionWaitTimeout()
          Gets the amount of time to wait (in seconds) for a used connection to be released by a client.
 int getInactiveConnectionTimeout()
          Gets the inactive connection timeout value.
 int getInitialPoolSize()
          Gets the initial pool size.
 UniversalConnectionPoolLifeCycleState getLifeCycleState()
          Gets the life cycle state of the connection pool.
 int getMaxConnectionReuseCount()
          Gets the maximum connection reuse count property value.
 long getMaxConnectionReuseTime()
          Gets the maximum connection reuse time property value.
 int getMaxPoolSize()
          Gets the maximum number of connections that the connection pool maintains.
 int getMinPoolSize()
          Gets the minimum number of connections that the connection pool maintains.
 java.lang.String getName()
          Gets the name of the connection pool.
 UniversalConnectionPoolStatistics getStatistics()
          Gets the statistics of the connection pool.
 int getTimeoutCheckInterval()
          Gets the frequency (in seconds) to enforce the timeout properties.
 int getTimeToLiveConnectionTimeout()
          Gets the maximum time (in seconds) a connection may remain in-use.
 boolean getValidateConnectionOnBorrow()
          Returns whether or not a connection being borrowed should first be validated.
 void purge()
          Removes all connections from the connection pool.
 void reconfigure(java.util.Properties props)
          Allows a connection pool to be reconfigured gracefully with a different set of properties that specify the behavior of the connection pool at runtime.
 void recycle()
          Allows only invalid available connections in the pool to be replaced with new/fresh connections.
 void refresh()
          Allows connections in the pool, both borrowed and available ones, to be replaced with new/fresh connections.
 void registerConnectionAffinityCallback(ConnectionAffinityCallback cbk)
          Registers a ConnectionAffinityCallback objet on the connection pool.
 void registerConnectionLabelingCallback(ConnectionLabelingCallback cbk)
          Registers a ConnectionLabelingCallback object with this connection pool.
 void removeConnectionAffinityCallback()
          Removes the ConnectionAffinityCallback object registered on the connection pool.
 void removeConnectionLabelingCallback()
          Removes the ConnectionLabelingCallback object registered with this connection pool, if any.
 void returnConnection(UniversalPooledConnection pooledConnection)
          Returns a connection back into the connection pool.
 void setAbandonedConnectionTimeout(int abandonedConnectionTimeout)
          Sets the abandoned connection timeout.
 void setConnectionHarvestMaxCount(int connectionHarvestMaxCount)
          Sets the maximum number of connections that may be harvested when the connection harvesting occurs.
 void setConnectionHarvestTriggerCount(int connectionHarvestTriggerCount)
          Sets the number of available connections below which the connection pool's connection harvesting occurs.
 void setConnectionRetrievalInfo(ConnectionRetrievalInfo cri)
          Sets the ConnectionRetrievalInfo for creating the initial connections (physical connections) in the pool based on the initialPoolSize property.
 void setConnectionWaitTimeout(int waitTimeout)
          Sets the amount of time to wait (in seconds) for a used connection to be released by a client.
 void setInactiveConnectionTimeout(int inactiveConnectionTimeout)
          Sets the inactive connection timeout.
 void setInitialPoolSize(int initialPoolSize)
          Sets the initial pool size.
 void setMaxConnectionReuseCount(int maxConnectionReuseCount)
          Sets the maximum connection reuse count property.
 void setMaxConnectionReuseTime(long maxConnectionReuseTime)
          Sets the maximum connection reuse time property.
 void setMaxPoolSize(int maxPoolSize)
          Sets the maximum number of connections.
 void setMinPoolSize(int minPoolSize)
          Sets the minimum number of connections.
 void setName(java.lang.String name)
          Sets the name of the connection pool.
 void setTimeoutCheckInterval(int timeoutCheckInterval)
          Sets the frequency (in seconds) to enforce the timeout properties.
 void setTimeToLiveConnectionTimeout(int timeToLiveConnectionTimeout)
          Sets the maximum time (in seconds) a connection may remain in-use.
 void setValidateConnectionOnBorrow(boolean validateConnectionOnBorrow)
          Sets whether or not a connection being borrowed should first be validated.
 void start()
          Starts the connection pool.
 void stop()
          Stops the connection pool.

 

Method Detail

borrowConnection

UniversalPooledConnection borrowConnection(ConnectionRetrievalInfo connectionRetrievalInfo)
                                           throws UniversalConnectionPoolException
Gets a connection from the connection pool.
Parameters:
connectionRetrievalInfo - Info to use to get the connection.
Returns:
A UniversalPooledConnection for the specified connection retrieval info.
Throws:
UniversalConnectionPoolException - if an error occurs getting a connection.
NoAvailableConnectionsException - if all of the connections are in use.

returnConnection

void returnConnection(UniversalPooledConnection pooledConnection)
                      throws UniversalConnectionPoolException
Returns a connection back into the connection pool. The pool can decide to close the underlying physical connection when necessary.
Parameters:
pooledConnection - The connection to return back into the pool.
Throws:
UniversalConnectionPoolException

closeConnection

void closeConnection(UniversalPooledConnection pooledConnection)
                     throws UniversalConnectionPoolException
Closes the pooled connection. Do not put it back into the pool.
Parameters:
pooledConnection - The pooled connection to close.
Throws:
UniversalConnectionPoolException - if an error occurs closing the connection.

refresh

void refresh()
             throws UniversalConnectionPoolException
Allows connections in the pool, both borrowed and available ones, to be replaced with new/fresh connections. All of the available connections are removed before replacing them with new connections. However, a borrowed connection is marked for removal. When such a borrowed connection is returned to the pool, it is closed and replaced with a new connection with the same user credentials.
Throws:
UniversalConnectionPoolException

recycle

void recycle()
             throws UniversalConnectionPoolException
Allows only invalid available connections in the pool to be replaced with new/fresh connections.
Throws:
UniversalConnectionPoolException

purge

void purge()
           throws UniversalConnectionPoolException
Removes all connections from the connection pool. The primary difference in behavior between this and refresh() is that the connection pool is left empty with no connections available after calling purge(). Some of the connection pool properties such as minPoolSize or initialPoolSize may not be honored when purging connections from the pool.

Note that both borrowed and available connections are removed when this API is called. Any borrowed connections incur an exception after this API is called. The user is expected to retry and obtain a new connection from the pool.

Throws:
UniversalConnectionPoolException

reconfigure

void reconfigure(java.util.Properties props)
                 throws UniversalConnectionPoolException
Allows a connection pool to be reconfigured gracefully with a different set of properties that specify the behavior of the connection pool at runtime. Reconfiguration of connection pool properties is always non-disruptive. If this operation cannot be completed right away, then the call returns and the enforcement of the properties continue to occur asynchronously.
Parameters:
props - Containing new set of pool properties for reconfiguration.
Throws:
UniversalConnectionPoolException

start

void start()
           throws UniversalConnectionPoolException
Starts the connection pool.
Throws:
UniversalConnectionPoolException - If an error occurs during start.

stop

void stop()
          throws UniversalConnectionPoolException
Stops the connection pool.
Throws:
UniversalConnectionPoolException

getName

java.lang.String getName()
Gets the name of the connection pool.
Returns:
The name of the connection pool.

setName

void setName(java.lang.String name)
Sets the name of the connection pool.
Parameters:
name - The name of the connection pool.

getInitialPoolSize

int getInitialPoolSize()
Gets the initial pool size.
Returns:
the initial pool size.

setInitialPoolSize

void setInitialPoolSize(int initialPoolSize)
                        throws UniversalConnectionPoolException
Sets the initial pool size. This is the number of connections that are created and placed in the pool upon initialization.
Parameters:
initialPoolSize - the initial pool size.
Throws:
UniversalConnectionPoolException

getMinPoolSize

int getMinPoolSize()
Gets the minimum number of connections that the connection pool maintains.
Returns:
The minimum number of connections.

setMinPoolSize

void setMinPoolSize(int minPoolSize)
                    throws UniversalConnectionPoolException
Sets the minimum number of connections. If the number of available connections + the number of connections in use < the minimum, then the connection is returned to the pool. Otherwise, the connection is closed.
Parameters:
minPoolSize - The minimum number of connections.
Throws:
UniversalConnectionPoolException

getMaxPoolSize

int getMaxPoolSize()
Gets the maximum number of connections that the connection pool maintains.
Returns:
The maximum number of connections.

setMaxPoolSize

void setMaxPoolSize(int maxPoolSize)
                    throws UniversalConnectionPoolException
Sets the maximum number of connections. The maximum number of connections includes the number of connections that are in use as well as the number of available connections.
Parameters:
maxPoolSize - The maximum number of connections.
Throws:
UniversalConnectionPoolException

getInactiveConnectionTimeout

int getInactiveConnectionTimeout()
Gets the inactive connection timeout value.
Returns:
The inactive connection timeout.

setInactiveConnectionTimeout

void setInactiveConnectionTimeout(int inactiveConnectionTimeout)
                                  throws UniversalConnectionPoolException
Sets the inactive connection timeout. This timeout determines how long an available connection remains in the connection pool before it is removed from the pool.
Parameters:
inactiveConnectionTimeout - The inactive connection timeout (in seconds).
Throws:
UniversalConnectionPoolException

getAbandonedConnectionTimeout

int getAbandonedConnectionTimeout()
Gets the abandoned connection timeout value.
Returns:
The abandoned connection timeout.

setAbandonedConnectionTimeout

void setAbandonedConnectionTimeout(int abandonedConnectionTimeout)
                                   throws UniversalConnectionPoolException
Sets the abandoned connection timeout. This timeout determines how long a borrowed connection can remain unused before it is considered abandoned and reclaimed by the connection pool.
Parameters:
abandonedConnectionTimeout - The value of how long a connection has not been used before it is abandoned (in seconds).
Throws:
UniversalConnectionPoolException

getConnectionWaitTimeout

int getConnectionWaitTimeout()
Gets the amount of time to wait (in seconds) for a used connection to be released by a client. This only applies when the maximum number of connections has been borrowed from the connection pool. When a client tries to borrow a connection from the pool and all connections are in use, the connection pool waits for a connection to be released back to the pool.
Returns:
The connection wait timeout.

setConnectionWaitTimeout

void setConnectionWaitTimeout(int waitTimeout)
                              throws UniversalConnectionPoolException
Sets the amount of time to wait (in seconds) for a used connection to be released by a client.
Parameters:
waitTimeout - The amount of time to wait.
Throws:
UniversalConnectionPoolException

getTimeToLiveConnectionTimeout

int getTimeToLiveConnectionTimeout()
Gets the maximum time (in seconds) a connection may remain in-use. The used connection is unconditionally returned to the connection pool when this timeout expires. A value of 0 means that the feature is not enabled.
Returns:
The maximum time (in seconds) a used connection may be active.

setTimeToLiveConnectionTimeout

void setTimeToLiveConnectionTimeout(int timeToLiveConnectionTimeout)
                                    throws UniversalConnectionPoolException
Sets the maximum time (in seconds) a connection may remain in-use.
Parameters:
timeToLiveConnectionTimeout - The maximum time (in seconds) a used connection may be active.
Throws:
UniversalConnectionPoolException

getTimeoutCheckInterval

int getTimeoutCheckInterval()
Gets the frequency (in seconds) to enforce the timeout properties. It applies to all of the connection pool timeouts including abandonedConnectionTimeout, inactiveConnectionTimeout, and timeToLiveConnectionTimeout.
Returns:
The frequency (in seconds) to enforce the timeout properties.

setTimeoutCheckInterval

void setTimeoutCheckInterval(int timeoutCheckInterval)
                             throws UniversalConnectionPoolException
Sets the frequency (in seconds) to enforce the timeout properties.
Parameters:
timeoutCheckInterval - The frequency (in seconds) to enforce the timeout properties.
Throws:
UniversalConnectionPoolException

getValidateConnectionOnBorrow

boolean getValidateConnectionOnBorrow()
Returns whether or not a connection being borrowed should first be validated. When this property is set to true, connection validity is performed before returning the connection to the user.
Returns:
Whether or not a connection being borrowed should first be validated.

setValidateConnectionOnBorrow

void setValidateConnectionOnBorrow(boolean validateConnectionOnBorrow)
Sets whether or not a connection being borrowed should first be validated.
Parameters:
validateConnectionOnBorrow - Whether or not a connection being borrowed should first be validated.

getConnectionHarvestTriggerCount

int getConnectionHarvestTriggerCount()
Gets the number of available connections below which the connection pool's connection harvesting occurs. For example, if the value is set to 10, then connection harvesting occurs when the number of available connections drops to 10.
Returns:
The number of available connections below which the connection pool's connection harvesting occurs.

setConnectionHarvestTriggerCount

void setConnectionHarvestTriggerCount(int connectionHarvestTriggerCount)
                                      throws UniversalConnectionPoolException
Sets the number of available connections below which the connection pool's connection harvesting occurs.
Parameters:
connectionHarvestTriggerCount - The number of available connections below which the connection pool's connection harvesting occurs.
Throws:
UniversalConnectionPoolException

getConnectionHarvestMaxCount

int getConnectionHarvestMaxCount()
Gets the maximum number of connections that may be harvested when the connection harvesting occurs. Note that it is possible that the number of connections that are harvested may be anywhere from 0 to the connectionHarvestMaxCount.
Returns:
The maximum number of connections that may be harvested when the connection harvesting occurs.

setConnectionHarvestMaxCount

void setConnectionHarvestMaxCount(int connectionHarvestMaxCount)
                                  throws UniversalConnectionPoolException
Sets the maximum number of connections that may be harvested when the connection harvesting occurs.
Parameters:
connectionHarvestMaxCount - the maximum number of connections that may be harvested when the connection harvesting occurs.
Throws:
UniversalConnectionPoolException

getAvailableConnectionsCount

int getAvailableConnectionsCount()
Gets the number of connections that are available in the connection pool (that is, connections in the pool that are not currently in use by clients).
Returns:
The number of connections that are available in the connection pool.

getBorrowedConnectionsCount

int getBorrowedConnectionsCount()
Gets the number of connections that are actively in use by clients.
Returns:
The number of connections that are actively in use by clients.

getStatistics

UniversalConnectionPoolStatistics getStatistics()
Gets the statistics of the connection pool.
Returns:
The statistics of the connection pool.

getLifeCycleState

UniversalConnectionPoolLifeCycleState getLifeCycleState()
Gets the life cycle state of the connection pool.
Returns:
The life cycle state of the connection pool.

getConnectionRetrievalInfo

ConnectionRetrievalInfo getConnectionRetrievalInfo()
Gets the ConnectionRetrievalInfo object which contains user and password information to create the connections.
Returns:
ConnectionRetrievalInfo object which contains user and password information to create the connections.

setConnectionRetrievalInfo

void setConnectionRetrievalInfo(ConnectionRetrievalInfo cri)
Sets the ConnectionRetrievalInfo for creating the initial connections (physical connections) in the pool based on the initialPoolSize property.
Parameters:
cri - The ConnectionRetrievalInfo with user and password for creating the initial connections in the pool.

registerConnectionAffinityCallback

void registerConnectionAffinityCallback(ConnectionAffinityCallback cbk)
                                        throws UniversalConnectionPoolException
Registers a ConnectionAffinityCallback objet on the connection pool.
Parameters:
cbk - The affinity callback object to be registered
Throws:
UniversalConnectionPoolException - If callback registration fails.

removeConnectionAffinityCallback

void removeConnectionAffinityCallback()
                                      throws UniversalConnectionPoolException
Removes the ConnectionAffinityCallback object registered on the connection pool.
Throws:
UniversalConnectionPoolException - If callback removal fails.

registerConnectionLabelingCallback

void registerConnectionLabelingCallback(ConnectionLabelingCallback cbk)
                                        throws UniversalConnectionPoolException
Registers a ConnectionLabelingCallback object with this connection pool.
Parameters:
cbk - The ConnectionLabelingCallback object to be registered.
Throws:
UniversalConnectionPoolException - If there is a callback already registered with this pool.

removeConnectionLabelingCallback

void removeConnectionLabelingCallback()
                                      throws UniversalConnectionPoolException
Removes the ConnectionLabelingCallback object registered with this connection pool, if any.
Throws:
UniversalConnectionPoolException - If callback removal fails.

getMaxConnectionReuseTime

long getMaxConnectionReuseTime()
Gets the maximum connection reuse time property value. See property description in setMaxConnectionReuseTime().
Returns:
Maximum connection reuse time (in seconds)

setMaxConnectionReuseTime

void setMaxConnectionReuseTime(long maxConnectionReuseTime)
                               throws UniversalConnectionPoolException
Sets the maximum connection reuse time property. This property specifies the maximum time any connection can potentially be reused after which the pool removes and closes a connection. The value is specified in seconds and must be greater than 0. For example, if the specified value is 3600 seconds, then when a connection is in existence for more than 3600 seconds, the connection is closed and removed from the pool. Connections are closed gracefully after they are returned to the pool and the specified property value has been exceeded. Default is 0, which means this feature is not enabled.
Parameters:
maxConnectionReuseTime - Maximum connection reuse time (in seconds).
Throws:
UniversalConnectionPoolException

getMaxConnectionReuseCount

int getMaxConnectionReuseCount()
Gets the maximum connection reuse count property value. See property description in setMaxConnectionReuseCount().
Returns:
Maximum connection reuse count.

setMaxConnectionReuseCount

void setMaxConnectionReuseCount(int maxConnectionReuseCount)
                                throws UniversalConnectionPoolException
Sets the maximum connection reuse count property. This property specifies the maximum number of times any connection can be reused after which the pool removes and closes a connection. The value must be greater than 0 for this feature to be enabled. For example, if the specified value is 100, then when a connection is reused or borrowed 100 times from the pool, it is closed and removed from the pool. Connections are closed gracefully after they are returned to the pool and the property value has been exceeded. Default is 0, which means this feature is not enabled.
Parameters:
maxConnectionReuseCount - Maximum connection reuse count.
Throws:
UniversalConnectionPoolException

Skip navigation links

Oracle® Universal Connection Pool for JDBC Java API Reference
12c Release 1 (12.1)

E17662-07


Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved.