public interface UniversalPooledConnection
extends java.io.Closeable
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).
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.
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.
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.
Modifier and Type | Method and Description |
---|---|
void |
abort()
TODO document
abort connection
|
void |
applyConnectionLabel(java.lang.String key,
java.lang.String value)
Applies a connection label on a borrowed connection.
|
void |
close()
TODO document
close 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.
|
oracle.ucp.common.CoreConnection |
getDelegator() |
long |
getLastAccessedTime()
Gets the last time (in milliseconds) that this pooled connection was
used by the client.
|
long |
getLastConnectionValidationTime()
Gets the time that this pooled connection was last validated.
|
long |
getLastNetworkAccessTime()
Gets the time (in milliseconds) when the underlying connection last
accessed the network.
|
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 |
handleTimeout()
TODO document
handle timeouts on connection
|
void |
heartbeat()
Indicates that the pooled connection is alive and being used.
|
boolean |
isAvailable()
TODO document
|
boolean |
isConnectionHarvestable()
Whether this connection is currently harvestable.
|
boolean |
isReusable() |
boolean |
isSqlWithQueryTimeoutInProgress()
Checks whether or not the connection currently performing timed-out SQL operation
|
boolean |
isValid()
Checks whether or not the connection is valid.
|
int |
labelingCost(java.util.Properties label)
TODO document - costs are now here!
|
void |
plugDelegator(oracle.ucp.common.CoreConnection delegator) |
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 |
setAvailable() |
void |
setAvailableStartTime()
Sets the time that this pooled connection became available
to be the current system time.
|
void |
setBorrowed() |
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 |
setConnectionRetrievalInfo(ConnectionRetrievalInfo cri)
Sets the connection retrieval info on the connection.
|
void |
setLastConnectionValidationTime(long lastConnectionValidationTime)
Sets or resets the time that this pooled connection was last validated.
|
void |
setSqlWithQueryTimeoutInProgress(boolean inProgress)
Marks connection currently performing timed-out SQL operation
|
void |
setStatus(UniversalPooledConnectionStatus status)
Sets the status of the pooled connection.
|
void |
validate()
Validates this connection and sets corresponding status on this
connection.
|
java.lang.Object getPhysicalConnection()
UniversalPooledConnection
decorates.null
.ConnectionRetrievalInfo getConnectionRetrievalInfo()
null
.void setConnectionRetrievalInfo(ConnectionRetrievalInfo cri)
cri
- -new CRI to be used for this connectionvoid heartbeat()
void setSqlWithQueryTimeoutInProgress(boolean inProgress)
set
- true, if timed-out SQL operation is in progressboolean isSqlWithQueryTimeoutInProgress()
boolean isValid()
true
if connection is valid; false
otherwise.void validate()
long getLastAccessedTime()
long getLastNetworkAccessTime()
UniversalPooledConnectionStatus getStatus()
void setStatus(UniversalPooledConnectionStatus status) throws UniversalConnectionPoolException
status
- The status of the pooled connection.UniversalConnectionPoolException
- if an error occurs setting the
status.void setAvailableStartTime()
long getAvailableStartTime()
void setBorrowedStartTime()
long getBorrowedStartTime()
long getLastConnectionValidationTime()
void setLastConnectionValidationTime(long lastConnectionValidationTime)
void applyConnectionLabel(java.lang.String key, java.lang.String value) throws UniversalConnectionPoolException
UniversalConnectionPoolException
.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.UniversalConnectionPoolException
- If this connection was closed
or the key is null
or an empty string.void removeConnectionLabel(java.lang.String key) throws UniversalConnectionPoolException
key
- The key of the connection label to be removed.
Cannot be null
or an empty string.UniversalConnectionPoolException
- If this connection was closed
or the key is null
or an empty string.java.util.Properties getConnectionLabels() throws UniversalConnectionPoolException
java.util.Properties
object storing all the
applied labels as key/value pairs. Returns null
if
there are no applied labels on this connection.UniversalConnectionPoolException
- If this connection was closed.java.util.Properties getUnmatchedConnectionLabels(java.util.Properties requestedLabels) throws UniversalConnectionPoolException
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.
requestedLabels
- The requested labels that borrowed this
connection from the pool.null
if there are none.UniversalConnectionPoolException
- If this connection was closed.void setConnectionHarvestable(boolean isConnectionHarvestable) throws UniversalConnectionPoolException
isConnectionHarvestable
- Whether this connection is
harvestable.UniversalConnectionPoolException
- If this connection was closed.boolean isConnectionHarvestable()
true
if so and false
otherwise.void registerConnectionHarvestingCallback(ConnectionHarvestingCallback cbk) throws UniversalConnectionPoolException
ConnectionHarvestingCallback
with this connection.cbk
- The ConnectionHarvestingCallback
object to be
registered.UniversalConnectionPoolException
- If there is a callback already
registered with the connection.void removeConnectionHarvestingCallback() throws UniversalConnectionPoolException
ConnectionHarvestingCallback
object registered
with this connection, if any.UniversalConnectionPoolException
- If callback removal fails.ConnectionHarvestingCallback getConnectionHarvestingCallback() throws UniversalConnectionPoolException
ConnectionHarvestingCallback
registered with
this connection.ConnectionHarvestingCallback
object registered.
null
if none.UniversalConnectionPoolException
- If an error occurs.void registerAbandonedConnectionTimeoutCallback(AbandonedConnectionTimeoutCallback cbk) throws UniversalConnectionPoolException
AbandonedConnectionTimeoutCallback
with this
connection.cbk
- The AbandonedConnectionTimeoutCallback
object to
be registered.UniversalConnectionPoolException
- If there is a callback already
registered with the connection.void removeAbandonedConnectionTimeoutCallback() throws UniversalConnectionPoolException
AbandonedConnectionTimeoutCallback
object
registered with this connection, if any.UniversalConnectionPoolException
- If callback removal fails.AbandonedConnectionTimeoutCallback getAbandonedConnectionTimeoutCallback() throws UniversalConnectionPoolException
AbandonedConnectionTimeoutCallback
registered
with this connection.AbandonedConnectionTimeoutCallback
object
registered. null
if none.UniversalConnectionPoolException
- If an error occurs.void registerTimeToLiveConnectionTimeoutCallback(TimeToLiveConnectionTimeoutCallback cbk) throws UniversalConnectionPoolException
TimeToLiveConnectionTimeoutCallback
with this
connection.cbk
- The TimeToLiveConnectionTimeoutCallback
object
to be registered.UniversalConnectionPoolException
- If there is a callback already
registered with the connection.void removeTimeToLiveConnectionTimeoutCallback() throws UniversalConnectionPoolException
TimeToLiveConnectionTimeoutCallback
object
registered with this connection, if any.UniversalConnectionPoolException
- If callback removal fails.TimeToLiveConnectionTimeoutCallback getTimeToLiveConnectionTimeoutCallback() throws UniversalConnectionPoolException
TimeToLiveConnectionTimeoutCallback
registered
with this connection.TimeToLiveConnectionTimeoutCallback
object
registered.null
if none.UniversalConnectionPoolException
- If an error occurs.void close()
close
in interface java.lang.AutoCloseable
close
in interface java.io.Closeable
void abort()
void handleTimeout()
boolean isAvailable()
void setAvailable()
void setBorrowed()
boolean isReusable()
int labelingCost(java.util.Properties label)
void plugDelegator(oracle.ucp.common.CoreConnection delegator)
oracle.ucp.common.CoreConnection getDelegator()