Skip navigation links

oracle.ucp
Interface UniversalPooledConnection

public interface UniversalPooledConnection

The UniversalPooledConnection is the actual object that is pooled by the connection pool. A UniversalPooledConnection decorates a physical connection that is produced by a resource (JDBC is an example of a resource). <p/> UniversalPooledConnection object's are borrowed from, and returned to, a connection pool. A UniversalPooledConnection can also be closed which means that it is not returned to the connection pool and its associated physical connection is closed. <p/> The heartbeat() method is used to update this object so that the abandoned connection processing works properly. It is up to the client of the connection pool to call the heartbeat() method appropriately. <p/> The Connection Labeling mechanism is application-driven. Labels can be applied on, and removed from, a borrowed connection. Each connection label is defined as a key/value pair. Connection labels are used for connection-matching purposes. Any number of connection labels may be applied on a borrowed connection. It is also possible to obtain all the labels currently applied on a borrowed connection, as well as all the unmatched labels within application-requested labels for each connection-borrowing request.

See Also:

UniversalConnectionPool, UniversalPooledConnectionStatus

Method Summary

void	applyConnectionLabel(java.lang.String key, java.lang.String value) Applies a connection label on a borrowed connection.
AbandonedConnectionTimeoutCallback	getAbandonedConnectionTimeoutCallback() Obtains the AbandonedConnectionTimeoutCallback registered with this connection.
long	getAvailableStartTime() Gets the timestamp that this pooled connection became available.
long	getBorrowedStartTime() Gets the timestamp that this pooled connection became borrowed.
ConnectionHarvestingCallback	getConnectionHarvestingCallback() Obtains the ConnectionHarvestingCallback registered with this connection.
java.util.Properties	getConnectionLabels() Retrieves all the connection labels applied on this connection.
ConnectionRetrievalInfo	getConnectionRetrievalInfo() Gets the connection retrieval info.
long	getLastAccessedTime() Gets the last time (in milliseconds) that this pooled connection was used by the client.
java.lang.Object	getPhysicalConnection() Gets the physical connection that this UniversalPooledConnection decorates.
UniversalPooledConnectionStatus	getStatus() Gets the status of the pooled connection.
TimeToLiveConnectionTimeoutCallback	getTimeToLiveConnectionTimeoutCallback() Obtains the TimeToLiveConnectionTimeoutCallback registered with this connection.
java.util.Properties	getUnmatchedConnectionLabels(java.util.Properties requestedLabels) Obtains all the requested labels that did not match the applied labels on this connection when this connection was borrowed from the pool.
void	heartbeat() Indicates that the pooled connection is alive and being used.
boolean	isConnectionHarvestable() Whether this connection is currently harvestable.
boolean	isValid() Checks whether or not the connection is valid.
void	registerAbandonedConnectionTimeoutCallback(AbandonedConnectionTimeoutCallback cbk) Registers an AbandonedConnectionTimeoutCallback with this connection.
void	registerConnectionHarvestingCallback(ConnectionHarvestingCallback cbk) Registers a ConnectionHarvestingCallback with this connection.
void	registerTimeToLiveConnectionTimeoutCallback(TimeToLiveConnectionTimeoutCallback cbk) Registers a TimeToLiveConnectionTimeoutCallback with this connection.
void	removeAbandonedConnectionTimeoutCallback() Removes the AbandonedConnectionTimeoutCallback object registered with this connection, if any.
void	removeConnectionHarvestingCallback() Removes the ConnectionHarvestingCallback object registered with this connection, if any.
void	removeConnectionLabel(java.lang.String key) Removes the connection label with the given key from the connection labels applied on this connection.
void	removeTimeToLiveConnectionTimeoutCallback() Removes the TimeToLiveConnectionTimeoutCallback object registered with this connection, if any.
void	setAvailableStartTime() Sets the time that this pooled connection became available to be the current system time.
void	setBorrowedStartTime() Sets the time that this pooled connection became borrowed to be the current system time.
void	setConnectionHarvestable(boolean isConnectionHarvestable) Specifies whether this connection is harvestable.
void	setStatus(UniversalPooledConnectionStatus status) Sets the status of the pooled connection.
void	validate() Validates this connection and sets corresponding status on this connection.

Method Detail

getPhysicalConnection

java.lang.Object getPhysicalConnection()

Gets the physical connection that this UniversalPooledConnection decorates.

Returns:

The physical connection. Never null.

getConnectionRetrievalInfo

ConnectionRetrievalInfo getConnectionRetrievalInfo()

Gets the connection retrieval info.

Returns:

The connection retrieval info. Never null.

heartbeat

void heartbeat()

Indicates that the pooled connection is alive and being used.

isValid

boolean isValid()

Checks whether or not the connection is valid.

Returns:

true if connection is valid; false otherwise.

validate

void validate()

Validates this connection and sets corresponding status on this connection. Possibly incurs a round-trip to the resource.

getLastAccessedTime

long getLastAccessedTime()

Gets the last time (in milliseconds) that this pooled connection was used by the client. This time is updated when the heartbeat method is called.

Returns:

The last time (in milliseconds) that this pooled connection was used by the client.

getStatus

UniversalPooledConnectionStatus getStatus()

Gets the status of the pooled connection.

Returns:

The status of the pooled connection.

setStatus

void setStatus(UniversalPooledConnectionStatus status)
               throws UniversalConnectionPoolException

Sets the status of the pooled connection.

Parameters:

status - The status of the pooled connection.

Throws:

UniversalConnectionPoolException - if an error occurs setting the status.

setAvailableStartTime

void setAvailableStartTime()

Sets the time that this pooled connection became available to be the current system time.

getAvailableStartTime

long getAvailableStartTime()

Gets the timestamp that this pooled connection became available.

Returns:

The time that this pooled connection became available.

setBorrowedStartTime

void setBorrowedStartTime()

Sets the time that this pooled connection became borrowed to be the current system time.

getBorrowedStartTime

long getBorrowedStartTime()

Gets the timestamp that this pooled connection became borrowed.

Returns:

The time that this pooled connection became available.

applyConnectionLabel

void applyConnectionLabel(java.lang.String key,
                          java.lang.String value)
                          throws UniversalConnectionPoolException

Applies a connection label on a borrowed connection. Connection labels are cumulative. Each time this method is called, the supplied key/value pair is added to those connection labels already applied. However, for each particular label key, only the last applied value is retained. Applying connection labels on a closed connection throws UniversalConnectionPoolException.

Parameters:

key - The key of the connection label to be applied. Cannot be null or an empty string.

value - The value of the connection label to be applied. Can be null or an empty string.

Throws:

UniversalConnectionPoolException - If this connection was closed or the key is null or an empty string.

removeConnectionLabel

void removeConnectionLabel(java.lang.String key)
                           throws UniversalConnectionPoolException

Removes the connection label with the given key from the connection labels applied on this connection. This method does nothing if there is no applied label with the specified key.

Parameters:

key - The key of the connection label to be removed. Cannot be null or an empty string.

Throws:

UniversalConnectionPoolException - If this connection was closed or the key is null or an empty string.

getConnectionLabels

java.util.Properties getConnectionLabels()
                                         throws UniversalConnectionPoolException

Retrieves all the connection labels applied on this connection. Any change to the result Properties object does not affect the labels applied to this connection.

Returns:

A java.util.Properties object storing all the applied labels as key/value pairs. Returns null if there are no applied labels on this connection.

Throws:

UniversalConnectionPoolException - If this connection was closed.

getUnmatchedConnectionLabels

java.util.Properties getUnmatchedConnectionLabels(java.util.Properties requestedLabels)
                                                  throws UniversalConnectionPoolException

Obtains all the requested labels that did not match the applied labels on this connection when this connection was borrowed from the pool. <p/> This method is typically used to verify, after a labeled connection is borrowed from the pool, which ones in the requested labels are matched and which ones are not.

Parameters:

requestedLabels - The requested labels that borrowed this connection from the pool.

Returns:

A java.util.Properties object storing all the requested labels that did not match the labels applied on this connection. Returns null if there are none.

Throws:

UniversalConnectionPoolException - If this connection was closed.

setConnectionHarvestable

void setConnectionHarvestable(boolean isConnectionHarvestable)
                              throws UniversalConnectionPoolException

Specifies whether this connection is harvestable.

Parameters:

isConnectionHarvestable - Whether this connection is harvestable.

Throws:

UniversalConnectionPoolException - If this connection was closed.

isConnectionHarvestable

boolean isConnectionHarvestable()

Whether this connection is currently harvestable.

Returns:

A boolean indicating whether this connection is harvestable. true if so and false otherwise.

registerConnectionHarvestingCallback

void registerConnectionHarvestingCallback(ConnectionHarvestingCallback cbk)
                                          throws UniversalConnectionPoolException

Registers a ConnectionHarvestingCallback with this connection.

Parameters:

cbk - The ConnectionHarvestingCallback object to be registered.

Throws:

UniversalConnectionPoolException - If there is a callback already registered with the connection.

removeConnectionHarvestingCallback

void removeConnectionHarvestingCallback()
                                        throws UniversalConnectionPoolException

Removes the ConnectionHarvestingCallback object registered with this connection, if any.

Throws:

UniversalConnectionPoolException - If callback removal fails.

getConnectionHarvestingCallback

ConnectionHarvestingCallback getConnectionHarvestingCallback()
                                                             throws UniversalConnectionPoolException

Obtains the ConnectionHarvestingCallback registered with this connection.

Returns:

The ConnectionHarvestingCallback object registered. null if none.

Throws:

UniversalConnectionPoolException - If an error occurs.

registerAbandonedConnectionTimeoutCallback

void registerAbandonedConnectionTimeoutCallback(AbandonedConnectionTimeoutCallback cbk)
                                                throws UniversalConnectionPoolException

Registers an AbandonedConnectionTimeoutCallback with this connection.

Parameters:

cbk - The AbandonedConnectionTimeoutCallback object to be registered.

Throws:

UniversalConnectionPoolException - If there is a callback already registered with the connection.

removeAbandonedConnectionTimeoutCallback

void removeAbandonedConnectionTimeoutCallback()
                                              throws UniversalConnectionPoolException

Removes the AbandonedConnectionTimeoutCallback object registered with this connection, if any.

Throws:

UniversalConnectionPoolException - If callback removal fails.

getAbandonedConnectionTimeoutCallback

AbandonedConnectionTimeoutCallback getAbandonedConnectionTimeoutCallback()
                                                                         throws UniversalConnectionPoolException

Obtains the AbandonedConnectionTimeoutCallback registered with this connection.

Returns:

The AbandonedConnectionTimeoutCallback object registered. null if none.

Throws:

UniversalConnectionPoolException - If an error occurs.

registerTimeToLiveConnectionTimeoutCallback

void registerTimeToLiveConnectionTimeoutCallback(TimeToLiveConnectionTimeoutCallback cbk)
                                                 throws UniversalConnectionPoolException

Registers a TimeToLiveConnectionTimeoutCallback with this connection.

Parameters:

cbk - The TimeToLiveConnectionTimeoutCallback object to be registered.

Throws:

UniversalConnectionPoolException - If there is a callback already registered with the connection.

removeTimeToLiveConnectionTimeoutCallback

void removeTimeToLiveConnectionTimeoutCallback()
                                               throws UniversalConnectionPoolException

Removes the TimeToLiveConnectionTimeoutCallback object registered with this connection, if any.

Throws:

UniversalConnectionPoolException - If callback removal fails.

getTimeToLiveConnectionTimeoutCallback

TimeToLiveConnectionTimeoutCallback getTimeToLiveConnectionTimeoutCallback()
                                                                           throws UniversalConnectionPoolException

Obtains the TimeToLiveConnectionTimeoutCallback registered with this connection.

Returns:

The TimeToLiveConnectionTimeoutCallback object registered.null if none.

Throws:

UniversalConnectionPoolException - If an error occurs.

Skip navigation links