Package oracle.ucp

Interface UniversalPooledConnection

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    public interface UniversalPooledConnection
extends java.io.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:
    UniversalConnectionPool, UniversalPooledConnectionStatus

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

      • 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​(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 java.util.concurrent.CompletionStage<java.lang.Boolean> isValidAsync​(UniversalPooledConnection.ValidationType validationType,
                                                                             int timeout,
                                                                             java.util.concurrent.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 java.util.concurrent.CompletionStage<java.lang.Boolean> isValidAsync​(int timeout,
                                                                             java.util.concurrent.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​(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 java.util.concurrent.CompletionStage<java.lang.Void> validateAsync​(UniversalPooledConnection.ValidationType validationType,
                                                                           int timeout,
                                                                           java.util.concurrent.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 java.util.concurrent.CompletionStage<java.lang.Void> validateAsync​(int timeout,
                                                                           java.util.concurrent.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.

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

        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.

      • close

        void close()
        Close this connection.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.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​(java.util.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

        java.util.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