Package oracle.ucp

Interface UniversalPooledConnection

All Superinterfaces:
AutoCloseable, Closeable
public interface UniversalPooledConnection extends Closeable
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).

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.

See Also:

  • Method Details

    • getPhysicalConnection

      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.

    • setConnectionRetrievalInfo

      void setConnectionRetrievalInfo(ConnectionRetrievalInfo cri)
      Sets the connection retrieval info on the connection.
      Parameters:
      cri - -new CRI to be used for this connection

    • heartbeat

      void heartbeat()
      Indicates that the pooled connection is alive and being used.

    • setSqlWithQueryTimeoutInProgress

      void setSqlWithQueryTimeoutInProgress(boolean inProgress)
      Marks connection currently performing timed-out SQL operation
      Parameters:
      inProgress - true, if timed-out SQL operation is in progress

    • isSqlWithQueryTimeoutInProgress

      boolean isSqlWithQueryTimeoutInProgress()
      Checks whether or not the connection currently performing timed-out SQL operation
      Returns:
      true if timed-out SQL operation is in progress

    • isValid

      boolean isValid()
      Checks whether or not the connection is valid with default timeout and default Oracle JDBC driver validation type.
      Returns:
      true if connection is valid; false otherwise.

    • isValid

      default boolean isValid(UniversalPooledConnection.ValidationType validationType, int timeout)
      Checks whether or not the connection is valid with a timeout.
      Parameters:
      validationType - selection from the UniversalPooledConnection.ValidationType
      timeout - timeout in seconds
      Returns:
      true if connection is valid; false otherwise.

    • isValid

      default boolean isValid(UniversalPooledConnection.ValidationType validationType)
      Checks whether or not the connection is valid with a default timeout.
      Parameters:
      validationType - selection from the UniversalPooledConnection.ValidationType
      Returns:
      true if connection is valid; false otherwise.

    • isValid

      default boolean isValid(int timeout)
      Checks whether or not the connection is valid with default Oracle JDBC driver validation type.
      Parameters:
      timeout - timeout in seconds. Driver's current default validation type is used.
      Returns:
      true if connection is valid; false otherwise.

    • isValidAsync

      default CompletionStage<Boolean> isValidAsync(UniversalPooledConnection.ValidationType validationType, int timeout, Executor executor)
      Asynchronous version of the 'isValid()'
      Parameters:
      validationType - selection from the UniversalPooledConnection.ValidationType
      timeout - timeout in seconds
      executor - executor for asynchronous execution
      Returns:
      completion stage of this connection's validity (true - valid)

    • isValidAsync

      default CompletionStage<Boolean> isValidAsync(int timeout, Executor executor)
      Asynchronous version of the 'isValid()'. Driver's current default validation type is used.
      Parameters:
      timeout - timeout in seconds
      executor - executor for asynchronous execution
      Returns:
      completion stage of this connection's validity (true - valid)

    • validate

      void validate()
      Validates this connection and sets corresponding status on this connection. Possibly incurs a round-trip to the resource. Driver's current default validation type and current default PDS validation timeout are used.

    • validate

      default void validate(UniversalPooledConnection.ValidationType validationType, int timeout)
      Validates this connection and sets corresponding status on this connection. Possibly incurs a round-trip to the resource.
      Parameters:
      validationType - selection from the UniversalPooledConnection.ValidationType
      timeout - timeout in seconds

    • validate

      default void validate(int timeout)
      Validates this connection and sets corresponding status on this connection. Possibly incurs a round-trip to the resource. Driver's current default validation type is used.
      Parameters:
      timeout - timeout in seconds

    • validateAsync

      default CompletionStage<Void> validateAsync(UniversalPooledConnection.ValidationType validationType, int timeout, Executor executor)
      Asynchronous version of the 'validate(ValidationType, int)'.
      Parameters:
      validationType - selection from the UniversalPooledConnection.ValidationType
      timeout - timeout in seconds
      executor - executor for asynchronous execution

    • validateAsync

      default CompletionStage<Void> validateAsync(int timeout, Executor executor)
      Asynchronous version of the 'validate(int)'. Driver's current default validation type is used.
      Parameters:
      timeout - timeout in seconds
      executor - executor for asynchronous execution

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

    • getLastNetworkAccessTime

      long getLastNetworkAccessTime()
      Gets the time (in milliseconds) when the underlying connection last accessed the network.
      Returns:
      The time (in milliseconds) when the underlying connection last accessed the network.

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

    • getLastConnectionValidationTime

      long getLastConnectionValidationTime()
      Gets the time that this pooled connection was last validated.
      Returns:
      The time that this pooled connection was last validated.

    • setLastConnectionValidationTime

      void setLastConnectionValidationTime(long lastConnectionValidationTime)
      Sets or resets the time that this pooled connection was last validated.
      Parameters:
      lastConnectionValidationTime - timestamp of a last connection validation.

    • applyConnectionLabel

      void applyConnectionLabel(String key, 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(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

      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

      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.

      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.

    • close

      void close()
      Close this connection.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • abort

      void abort()
      Abort this connection

    • handleTimeout

      void handleTimeout()
      Handle timeouts on connection

    • isAvailable

      boolean isAvailable()
      check whether a connection is "available" or not
      Returns:
      true, if it is "available", false otherwise

    • setAvailable

      boolean setAvailable()
      mark connection as "available"
      Returns:
      true, if it was previously "borrowed", false otherwise

    • setBorrowed

      boolean setBorrowed()
      mark connection as "borrowed"
      Returns:
      true, if it was previously "available", false otherwise

    • isReusable

      boolean isReusable()
      check whether a connection is "reusable" or not
      Returns:
      true, if it is "reusable", false otherwise

    • labelingCost

      int labelingCost(Properties labels)
      Compute a labeling cost for this connection for a given label
      Parameters:
      labels - given labels
      Returns:
      computed cost.

    • plugDelegator

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

    • getDelegator

      oracle.ucp.common.CoreConnection getDelegator()

    • getDatabaseConnectionProperties

      Properties getDatabaseConnectionProperties()
      Fetches the connection properties.
      Returns:
      dtabase connection properties instance.

    • isOracle

      boolean isOracle()
      Is this connection an Oracle connection?
      Returns:
      true, if Oracle connection, otherwise (for non-oracle data sources) returns false