Package oracle.jdbc.datasource

## Interface OraclePooledConnection

All Superinterfaces:
  `javax.sql.PooledConnection`

All Known Subinterfaces:
  `OracleXAConnection`

All Known Implementing Classes:
  `OraclePooledConnection`, `OracleXAConnection`, `OracleXAConnection`, `OracleXAHeteroConnection`

    public interface OraclePooledConnection
    extends javax.sql.PooledConnection

This interface defines the Oracle extensions to the standard JDBC interface `PooledConnection`.

Since:
  12.2

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`java.sql.CallableStatement` `getCallWithKey​(java.lang.String key)` Searches the explicit cache for a match on key.
`boolean` `getExplicitCachingEnabled()` Checks if explicit cache is currently enabled.
`boolean` `getImplicitCachingEnabled()` Checks if implicit cache is currently enabled.
`long` `getLastAccessedTime()` Deprecated. The Implicit Connection Cache (ICC) has been desupported since 12.1.
`java.sql.Connection` `getLogicalHandle()` Return the logical handle to the caller.
`int` `getStatementCacheSize()` Returns the current size of the application cache.
`java.sql.PreparedStatement` `getStatementWithKey​(java.lang.String key)` Searches the explicit cache for a match on key.
`javax.transaction.xa.XAResource` `getXAResource()` Return an XA resource to the caller.
`void` `purgeExplicitCache()` Removes all existing statements from the explicit cache, after which it will be empty.
`void` `purgeImplicitCache()` Removes all existing statements from the implicit cache, after which it will be empty.
`void` `registerCloseCallback​(oracle.jdbc.driver.OracleCloseCallback occ, java.lang.Object privData)` Registers a close callback.
`void` `registerImplicitCacheConnectionEventListener​(javax.sql.ConnectionEventListener cel)` Deprecated. The Implicit Connection Cache (ICC) has been desupported since 12.1.
`void` `setExplicitCachingEnabled​(boolean cache)` Enables or disables the explicit cache.
`void` `setImplicitCachingEnabled​(boolean cache)` Enables or disables the implicit cache.
`void` `setLastAccessedTime​(long lastAccessedTime)` Deprecated. The Implicit Connection Cache (ICC) has been desupported since 12.1.
`void` `setShardingKey​(OracleShardingKey shardingKey, OracleShardingKey superShardingKey)` Sets the sharding key and the super sharding key on this connection.
`boolean` `setShardingKeyIfValid​(OracleShardingKey shardingKey, OracleShardingKey superShardingKey, int timeout)` Checks the validity of the connection and also checks if the sharding keys passed to this method are valid for the connection.If the sharding keys are valid, it will be set on the connection.
`void` `setStatementCacheSize​(int size)` Specifies the size of the size of the application cache (which will be used by both implicit and explicit caching).

### Methods inherited from interface javax.sql.PooledConnection

`addConnectionEventListener, addStatementEventListener, close, getConnection, removeConnectionEventListener, removeStatementEventListener`

### Method Detail

#### getLogicalHandle

    java.sql.Connection getLogicalHandle()
                                  throws java.sql.SQLException

Return the logical handle to the caller. This logical handle refers to the physical connection that is pooled.

Returns:
  a Connection object
Throws:
  `java.sql.SQLException`

#### setLastAccessedTime

    @Deprecated
    void setLastAccessedTime​(long lastAccessedTime)
                      throws java.sql.SQLException

Deprecated.
The Implicit Connection Cache (ICC) has been desupported since 12.1. This method throws UnsupportedOperationException, and will be removed soon in the future.

Throws:
  `java.sql.SQLException`

#### getLastAccessedTime

    @Deprecated
    long getLastAccessedTime()
                      throws java.sql.SQLException

Deprecated.
The Implicit Connection Cache (ICC) has been desupported since 12.1. This method throws UnsupportedOperationException, and will be removed soon in the future.

Throws:
  `java.sql.SQLException`

#### registerCloseCallback

    void registerCloseCallback​(oracle.jdbc.driver.OracleCloseCallback occ,
                               java.lang.Object privData)

Registers a close callback.

Parameters:
  `occ` - The callback to be registered.
  `privData` - Private data object to be passed to the callback.

#### registerImplicitCacheConnectionEventListener

    @Deprecated
    void registerImplicitCacheConnectionEventListener​(javax.sql.ConnectionEventListener cel)

Deprecated.
The Implicit Connection Cache (ICC) has been desupported since 12.1. This method throws UnsupportedOperationException, and will be removed soon in the future.

#### setStatementCacheSize

    void setStatementCacheSize​(int size)
                        throws java.sql.SQLException

Specifies the size of the size of the application cache (which will be used by both implicit and explicit caching).

Parameters:
  `size` - Requested size of the cache. If the existing cache size is less than size, statements will be purged to reduce the size.
Throws:
  `java.sql.SQLException` - if size < 0, or if called on a logical connection.

#### getStatementCacheSize

    int getStatementCacheSize()
                       throws java.sql.SQLException

Returns the current size of the application cache. This is valid on both physical and logical connections.

Throws:
  `java.sql.SQLException`

#### setImplicitCachingEnabled

    void setImplicitCachingEnabled​(boolean cache)
                            throws java.sql.SQLException

Enables or disables the implicit cache. Note that this is independent of the cache size, set with setStatementCacheSize().

Parameters:
  `cache` - If true, then implicit caching will be enabled. If false, then any existing statements will be purged and the implicit cache will be disabled.
Throws:
  `java.sql.SQLException` - if called on a logical connection.

#### getImplicitCachingEnabled

    boolean getImplicitCachingEnabled()
                               throws java.sql.SQLException

Checks if implicit cache is currently enabled. Returns true if the implicit cache is currently enabled, false otherwise. This method is valid on both logical and physical connections.

Throws:
  `java.sql.SQLException`

#### setExplicitCachingEnabled

    void setExplicitCachingEnabled​(boolean cache)
                            throws java.sql.SQLException

Enables or disables the explicit cache. Note that this is independent of the cache size, set with setStatementCacheSize().

Parameters:
  `cache` - If true, then explicit caching will be enabled. If false, then any existing statements will be purged and the explicit cache will be disabled.
Throws:
  `java.sql.SQLException` - if called on a logical connection.

#### getExplicitCachingEnabled

    boolean getExplicitCachingEnabled()
                               throws java.sql.SQLException

Checks if explicit cache is currently enabled. Returns true if the explicit cache is currently enabled, false otherwise. This method is valid on both logical and physical connections.

Throws:
  `java.sql.SQLException`

#### purgeImplicitCache

    void purgeImplicitCache()
                     throws java.sql.SQLException

Removes all existing statements from the implicit cache, after which it will be empty. This method does not affect the size of the application cache, nor the enabled/disabled status.

Throws:
  `java.sql.SQLException`

#### purgeExplicitCache

    void purgeExplicitCache()
                     throws java.sql.SQLException

Removes all existing statements from the explicit cache, after which it will be empty. This method does not affect the size of the application cache, nor the enabled/disabled status.

Throws:
  `java.sql.SQLException`

#### getStatementWithKey

    java.sql.PreparedStatement getStatementWithKey​(java.lang.String key)
                                            throws java.sql.SQLException

Searches the explicit cache for a match on key. If found, the statement is returned, with the parameter and define metadata identical to the last usage. If a CallableStatement is found (instead of a PreparedStatement, ORA-17125 is raised. If no match is found, or if explicit caching is not enabled, null is returned.

Parameters:
  `key` - Specified key to search for
Throws:
  `java.sql.SQLException`

#### getCallWithKey

    java.sql.CallableStatement getCallWithKey​(java.lang.String key)
                                       throws java.sql.SQLException

Searches the explicit cache for a match on key. If found, the statement is returned, with the parameter and define metadata identical to the last usage. If a PreparedStatement is found (instead of a CallableStatement, ORA-17125 is raised. If no match is found, or if explicit caching is not enabled, null is returned.

Parameters:
  `key` - Specified key to search for
Throws:
  `java.sql.SQLException`

#### getXAResource

    javax.transaction.xa.XAResource getXAResource()
                                           throws java.sql.SQLException

Return an XA resource to the caller. This is just a placeholder. Only the one on XAConnection is meaningful.

Returns:
  the XAResource (null if error occurs)
Throws:
  `java.sql.SQLException` - if a database error occurs

#### setShardingKeyIfValid

    boolean setShardingKeyIfValid​(OracleShardingKey shardingKey,
                                  OracleShardingKey superShardingKey,
                                  int timeout)
                           throws java.sql.SQLException

Checks the validity of the connection and also checks if the sharding keys passed to this method are valid for the connection.If the sharding keys are valid, it will be set on the connection.

Parameters:
  `shardingKey` - Sharding key to be validated against this connection
  `superShardingKey` - Super Sharding key to be validated against this connection
  `timeout` - Time in seconds before which the validation process is expected to be complete, else the validation process is aborted. The value of the timeout must be set to zero to disable the timeout during the validation.
Returns:
  true if the connection is valid and the shard keys are valid to be set on this connection.
Throws:
  `java.sql.SQLException` - if there is any exception while performing this validation or if timeout value is less than 0.

#### setShardingKey

    void setShardingKey​(OracleShardingKey shardingKey,
                        OracleShardingKey superShardingKey)
                 throws java.sql.SQLException

Sets the sharding key and the super sharding key on this connection.

Parameters:
  `shardingKey` - sharding key to be set on this connection
  `superShardingKey` - Super Sharding key to be set on this connection
Throws:
  `java.sql.SQLException` - if there is an exception while setting the sharding keys on this connection.