oracle.ucp.jdbc

Class JDBCUniversalPooledConnection

java.lang.Object

oracle.ucp.common.FailoverableUniversalPooledConnectionBase

oracle.ucp.jdbc.JDBCUniversalPooledConnection

All Implemented Interfaces:

Closeable, AutoCloseable, oracle.ucp.common.FailoverableUniversalPooledConnection, UniversalPooledConnection

Direct Known Subclasses:

OracleUniversalPooledConnection

public class JDBCUniversalPooledConnection
extends oracle.ucp.common.FailoverableUniversalPooledConnectionBase

Field Summary

Fields

Modifier and Type	Field and Description
static long	CONNECTION_VALIDATION_TIMEOUT
protected Semaphore	validitySemaphore

Constructor Summary

Constructors

Constructor and Description
JDBCUniversalPooledConnection(JDBCConnectionPool connectionPool, Object connection, ConnectionRetrievalInfo connectionRetrievalInfo, boolean connectionFailoverEnabled)

Method Summary

Modifier and Type	Method and Description
void	abort() TODO document abort connection
void	applyConnectionLabel(String key, String value) Connection labels can be applied on a borrowed connection by calling this method at any time when the connection remains open.
void	close() TODO document close connection
AbandonedConnectionTimeoutCallback	getAbandonedConnectionTimeoutCallback() Obtains the AbandonedConnectionTimeoutCallback registered with this connection.
long	getAvailableStartTime() Gets the time 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.
Properties	getConnectionLabels() Retrieves all the connection labels applied on this connection.
ConnectionRetrievalInfo	getConnectionRetrievalInfo() Gets the connection retrieval info.
int	getConnectionReuseCounter() Gets the connection reuse counter.
long	getConnectionReuseTimestamp() Gets the connection reuse timestamp.
Properties	getDatabaseConnectionProperties() Fetches the connection properties.
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.
int	getMaxStatements() Gets the maximum number of statements that may be pooled or cached on a Connection.
Object	getPhysicalConnection() Gets the connection.
String	getService()
Connection	getSQLConnection(Object physicalConnection)
UniversalPooledConnectionStatus	getStatus() Gets the status of the pooled connection.
TimeToLiveConnectionTimeoutCallback	getTimeToLiveConnectionTimeoutCallback() Obtains the TimeToLiveConnectionTimeoutCallback registered with this connection.
Properties	getUnmatchedConnectionLabels(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() This method is to be called to indicate that the pooled connection is alive and being used.
protected void	initFailoverParameters() Initializes the failover properties on this Universal Pooled Connection.
boolean	isAvailable() check whether a connection is "available" or not
boolean	isConnectionHarvestable() Whether this connection is currently harvestable.
boolean	isReusable() check whether a connection is "reusable" or not
boolean	isSqlWithQueryTimeoutInProgress() Checks whether or not the connection currently performing timed-out SQL operation
boolean	isValid() This method is called to check if the connection is valid or not.
boolean	isValid(long timeout) This method is called to check if the connection is valid or not.
int	labelingCost(Properties labels) Get a cost for labeling a connection up to a required set of labels in the given CRI This is unified method: i.e.
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(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.
boolean	setAvailable() mark connection as "available"
void	setAvailableStartTime() Sets the time that this pooled connection became available.
boolean	setBorrowed() mark connection as "borrowed"
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 newCri) Sets the connection retrieval info on the connection.
void	setLastConnectionValidationTime(long lastConnectionValidationTime) Sets or resets the time when this pooled connection was last validated.
void	setMaxStatements(int maxStatements) Sets the maximum number of statements that may be pooled or cached on a connection.
boolean	setShardingKeyIfValid(OracleShardingKey key, OracleShardingKey superKey, int timeout) No implementation in base class, will be implemented in Oracle specific connection class.
void	setSqlWithQueryTimeoutInProgress(boolean sqlWithQueryTimeoutInProgress) Marks connection currently performing timed-out SQL operation
void	setStatus(UniversalPooledConnectionStatus status) Sets the status of the pooled connection.
void	setStatus(UniversalPooledConnectionStatus status, String msg)
void	validate() Validates this connection and sets corresponding status on this connection.

Methods inherited from class oracle.ucp.common.FailoverableUniversalPooledConnectionBase

isFailoverEnabled

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONNECTION_VALIDATION_TIMEOUT

public static final long CONNECTION_VALIDATION_TIMEOUT

See Also:

Constant Field Values

validitySemaphore

protected final Semaphore validitySemaphore

Constructor Detail

JDBCUniversalPooledConnection

public JDBCUniversalPooledConnection(JDBCConnectionPool connectionPool,
                                     Object connection,
                                     ConnectionRetrievalInfo connectionRetrievalInfo,
                                     boolean connectionFailoverEnabled)
                              throws UniversalConnectionPoolException

Throws:

UniversalConnectionPoolException

Method Detail

validate

public void validate()

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

Specified by:

validate in interface UniversalPooledConnection

setShardingKeyIfValid

public boolean setShardingKeyIfValid(OracleShardingKey key,
                                     OracleShardingKey superKey,
                                     int timeout)

No implementation in base class, will be implemented in Oracle specific connection class. Just redirecting the validation to isValid(timeout)

Parameters:

key -

superKey -

timeout -

Returns:

getSQLConnection

public Connection getSQLConnection(Object physicalConnection)
                            throws SQLException

Throws:

SQLException

initFailoverParameters

protected void initFailoverParameters()
                               throws UniversalConnectionPoolException

Description copied from class: oracle.ucp.common.FailoverableUniversalPooledConnectionBase

Initializes the failover properties on this Universal Pooled Connection.

Specified by:

initFailoverParameters in class oracle.ucp.common.FailoverableUniversalPooledConnectionBase

Throws:

UniversalConnectionPoolException

getMaxStatements

public int getMaxStatements()

Gets the maximum number of statements that may be pooled or cached on a Connection.

Returns:

m_maxStatements maximum number of statements that may be pooled or cached on a Connection.

setMaxStatements

public void setMaxStatements(int maxStatements)
                      throws SQLException

Sets the maximum number of statements that may be pooled or cached on a connection. This is used to enable the statement pooling.

Parameters:

maxStatements - maximum number of statements to be pooled.

Throws:

SQLException - Exception occurred during the process of setting maximum statements that may be pooled on a connection.

getPhysicalConnection

public Object getPhysicalConnection()

Gets the connection.

Specified by:

getPhysicalConnection in interface UniversalPooledConnection

Returns:

The connection. Never null.

getConnectionRetrievalInfo

public ConnectionRetrievalInfo getConnectionRetrievalInfo()

Gets the connection retrieval info.

Specified by:

getConnectionRetrievalInfo in interface UniversalPooledConnection

Returns:

The connection retrieval info. Never null.

setConnectionRetrievalInfo

public void setConnectionRetrievalInfo(ConnectionRetrievalInfo newCri)

Description copied from interface: UniversalPooledConnection

Sets the connection retrieval info on the connection.

Specified by:

setConnectionRetrievalInfo in interface UniversalPooledConnection

Parameters:

newCri - -new CRI to be used for this connection

heartbeat

public void heartbeat()

This method is to be called to indicate that the pooled connection is alive and being used.

Specified by:

heartbeat in interface UniversalPooledConnection

setSqlWithQueryTimeoutInProgress

public void setSqlWithQueryTimeoutInProgress(boolean sqlWithQueryTimeoutInProgress)

Marks connection currently performing timed-out SQL operation

Specified by:

setSqlWithQueryTimeoutInProgress in interface UniversalPooledConnection

Parameters:

set - true if timed-out SQL operation is in progress

isSqlWithQueryTimeoutInProgress

public boolean isSqlWithQueryTimeoutInProgress()

Checks whether or not the connection currently performing timed-out SQL operation

Specified by:

isSqlWithQueryTimeoutInProgress in interface UniversalPooledConnection

Returns:

true if timed-out SQL operation is in progress

isValid

public boolean isValid()

This method is called to check if the connection is valid or not.

Specified by:

isValid in interface UniversalPooledConnection

Returns:

true if connection is valid, false otherwise

isValid

public boolean isValid(long timeout)
                throws SQLException

This method is called to check if the connection is valid or not.

Parameters:

timeout - connection validation timeout in seconds.

Returns:

true if connection is valid, false otherwise.

Throws:

SQLException

getLastNetworkAccessTime

public long getLastNetworkAccessTime()

Gets the time (in milliseconds) when the underlying connection last accessed the network.

Specified by:

getLastNetworkAccessTime in interface UniversalPooledConnection

Returns:

The time (in milliseconds) when the underlying connection last accessed the network.

getLastAccessedTime

public 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.

Specified by:

getLastAccessedTime in interface UniversalPooledConnection

Returns:

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

getStatus

public UniversalPooledConnectionStatus getStatus()

Gets the status of the pooled connection.

Specified by:

getStatus in interface UniversalPooledConnection

Returns:

The status of the pooled connection.

setStatus

public void setStatus(UniversalPooledConnectionStatus status)
               throws UniversalConnectionPoolException

Sets the status of the pooled connection.

Specified by:

setStatus in interface UniversalPooledConnection

Parameters:

status - The status of the pooled connection.

Throws:

UniversalConnectionPoolException - if an error occurs setting the status.

setStatus

public void setStatus(UniversalPooledConnectionStatus status,
                      String msg)

getAvailableStartTime

public long getAvailableStartTime()

Gets the time that this pooled connection became available.

Specified by:

getAvailableStartTime in interface UniversalPooledConnection

Returns:

The time that this pooled connection became available.

setAvailableStartTime

public void setAvailableStartTime()

Sets the time that this pooled connection became available.

Specified by:

setAvailableStartTime in interface UniversalPooledConnection

getBorrowedStartTime

public long getBorrowedStartTime()

Gets the timestamp that this pooled connection became borrowed.

Specified by:

getBorrowedStartTime in interface UniversalPooledConnection

Returns:

The time that this pooled connection became available.

setBorrowedStartTime

public void setBorrowedStartTime()

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

Specified by:

setBorrowedStartTime in interface UniversalPooledConnection

getLastConnectionValidationTime

public long getLastConnectionValidationTime()

Gets the time that this pooled connection was last validated.

Specified by:

getLastConnectionValidationTime in interface UniversalPooledConnection

Returns:

The time that this pooled connection was last validated.

setLastConnectionValidationTime

public void setLastConnectionValidationTime(long lastConnectionValidationTime)

Sets or resets the time when this pooled connection was last validated.

Specified by:

setLastConnectionValidationTime in interface UniversalPooledConnection

applyConnectionLabel

public void applyConnectionLabel(String key,
                                 String value)
                          throws UniversalConnectionPoolException

Connection labels can be applied on a borrowed connection by calling this method at any time when the connection remains open. Applying connection labels is 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.

Specified by:

applyConnectionLabel in interface UniversalPooledConnection

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

public void removeConnectionLabel(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.

Specified by:

removeConnectionLabel in interface UniversalPooledConnection

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

public 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.

Specified by:

getConnectionLabels in interface UniversalPooledConnection

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

public Properties getUnmatchedConnectionLabels(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.

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.

Specified by:

getUnmatchedConnectionLabels in interface UniversalPooledConnection

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

public void setConnectionHarvestable(boolean isConnectionHarvestable)
                              throws UniversalConnectionPoolException

Specifies whether this connection is harvestable.

Specified by:

setConnectionHarvestable in interface UniversalPooledConnection

Parameters:

isConnectionHarvestable - Whether this connection is harvestable.

Throws:

UniversalConnectionPoolException - If this connection was closed.

isConnectionHarvestable

public boolean isConnectionHarvestable()

Whether this connection is currently harvestable.

Specified by:

isConnectionHarvestable in interface UniversalPooledConnection

Returns:

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

registerConnectionHarvestingCallback

public void registerConnectionHarvestingCallback(ConnectionHarvestingCallback cbk)
                                          throws UniversalConnectionPoolException

Registers a ConnectionHarvestingCallback with this connection.

Specified by:

registerConnectionHarvestingCallback in interface UniversalPooledConnection

Parameters:

cbk - The ConnectionHarvestingCallback object to be registered.

Throws:

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

removeConnectionHarvestingCallback

public void removeConnectionHarvestingCallback()
                                        throws UniversalConnectionPoolException

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

Specified by:

removeConnectionHarvestingCallback in interface UniversalPooledConnection

Throws:

UniversalConnectionPoolException - If callback removal fails.

getConnectionHarvestingCallback

public ConnectionHarvestingCallback getConnectionHarvestingCallback()
                                                             throws UniversalConnectionPoolException

Obtains the ConnectionHarvestingCallback registered with this connection.

Specified by:

getConnectionHarvestingCallback in interface UniversalPooledConnection

Returns:

The ConnectionHarvestingCallback object registered. Null if none.

Throws:

UniversalConnectionPoolException - If an error occurs.

registerAbandonedConnectionTimeoutCallback

public void registerAbandonedConnectionTimeoutCallback(AbandonedConnectionTimeoutCallback cbk)
                                                throws UniversalConnectionPoolException

Registers an AbandonedConnectionTimeoutCallback with this connection.

Specified by:

registerAbandonedConnectionTimeoutCallback in interface UniversalPooledConnection

Parameters:

cbk - The AbandonedConnectionTimeoutCallback object to be registered.

Throws:

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

removeAbandonedConnectionTimeoutCallback

public void removeAbandonedConnectionTimeoutCallback()
                                              throws UniversalConnectionPoolException

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

Specified by:

removeAbandonedConnectionTimeoutCallback in interface UniversalPooledConnection

Throws:

UniversalConnectionPoolException - If callback removal fails.

getAbandonedConnectionTimeoutCallback

public AbandonedConnectionTimeoutCallback getAbandonedConnectionTimeoutCallback()
                                                                         throws UniversalConnectionPoolException

Obtains the AbandonedConnectionTimeoutCallback registered with this connection.

Specified by:

getAbandonedConnectionTimeoutCallback in interface UniversalPooledConnection

Returns:

The AbandonedConnectionTimeoutCallback object registered. Null if none.

Throws:

UniversalConnectionPoolException - If an error occurs.

registerTimeToLiveConnectionTimeoutCallback

public void registerTimeToLiveConnectionTimeoutCallback(TimeToLiveConnectionTimeoutCallback cbk)
                                                 throws UniversalConnectionPoolException

Registers a TimeToLiveConnectionTimeoutCallback with this connection.

Specified by:

registerTimeToLiveConnectionTimeoutCallback in interface UniversalPooledConnection

Parameters:

cbk - The TimeToLiveConnectionTimeoutCallback object to be registered.

Throws:

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

removeTimeToLiveConnectionTimeoutCallback

public void removeTimeToLiveConnectionTimeoutCallback()
                                               throws UniversalConnectionPoolException

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

Specified by:

removeTimeToLiveConnectionTimeoutCallback in interface UniversalPooledConnection

Throws:

UniversalConnectionPoolException - If callback removal fails.

getTimeToLiveConnectionTimeoutCallback

public TimeToLiveConnectionTimeoutCallback getTimeToLiveConnectionTimeoutCallback()
                                                                           throws UniversalConnectionPoolException

Obtains the TimeToLiveConnectionTimeoutCallback registered with this connection.

Specified by:

getTimeToLiveConnectionTimeoutCallback in interface UniversalPooledConnection

Returns:

The TimeToLiveConnectionTimeoutCallback object registered. Null if none.

Throws:

UniversalConnectionPoolException - If an error occurs.

getConnectionReuseCounter

public int getConnectionReuseCounter()

Gets the connection reuse counter.

Returns:

the m_connectionReuseCounter.

getConnectionReuseTimestamp

public long getConnectionReuseTimestamp()

Gets the connection reuse timestamp.

Returns:

the m_connectionReuseTimestamp.

isReusable

public boolean isReusable()

Description copied from interface: UniversalPooledConnection

check whether a connection is "reusable" or not

Specified by:

isReusable in interface UniversalPooledConnection

Returns:

true, if it is "reusable", false otherwise

close

public void close()

Description copied from interface: UniversalPooledConnection

TODO document close connection

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface UniversalPooledConnection

abort

public void abort()

Description copied from interface: UniversalPooledConnection

TODO document abort connection

Specified by:

abort in interface UniversalPooledConnection

handleTimeout

public void handleTimeout()

Description copied from interface: UniversalPooledConnection

TODO document handle timeouts on connection

Specified by:

handleTimeout in interface UniversalPooledConnection

isAvailable

public boolean isAvailable()

Description copied from interface: UniversalPooledConnection

check whether a connection is "available" or not

Specified by:

isAvailable in interface UniversalPooledConnection

Returns:

true, if it is "available", false otherwise

setAvailable

public boolean setAvailable()

Description copied from interface: UniversalPooledConnection

mark connection as "available"

Specified by:

setAvailable in interface UniversalPooledConnection

Returns:

true, if it was previously "borrowed", false otherwise

setBorrowed

public boolean setBorrowed()

Description copied from interface: UniversalPooledConnection

mark connection as "borrowed"

Specified by:

setBorrowed in interface UniversalPooledConnection

Returns:

true, if it was previously "available", false otherwise

labelingCost

public int labelingCost(Properties labels)

Get a cost for labeling a connection up to a required set of labels in the given CRI This is unified method: i.e. it Handles both labeled and non-labeled connections. If called with requested labels for non-labeled conn, it returns MAX_VALUE cost of labeling (totally unsuitable case), if called with requested non-labels for non-labeled conn, it returns 0 cost (totally suitable case), if called with requested labels for labeled conn, it computes the proper labeling cost for requested and existing labels using 'cost()' method. automatically handles and uses labeling cost cache automatically takes care of connection labeling high cost and high cost connection reuse threshold mechanisms

Specified by:

labelingCost in interface UniversalPooledConnection

Returns:

cost of that labeling

plugDelegator

public void plugDelegator(oracle.ucp.common.CoreConnection delegator)

Specified by:

plugDelegator in interface UniversalPooledConnection

getDelegator

public oracle.ucp.common.CoreConnection getDelegator()

Specified by:

getDelegator in interface UniversalPooledConnection

getService

public String getService()

getDatabaseConnectionProperties

public Properties getDatabaseConnectionProperties()

Fetches the connection properties.

Specified by:

getDatabaseConnectionProperties in interface UniversalPooledConnection