Package oracle.jdbc.pool

## Class OraclePooledConnection

- java.lang.Object
- - oracle.jdbc.pool.OraclePooledConnection

All Implemented Interfaces:
  `java.beans.PropertyChangeListener`, `java.io.Serializable`, `java.util.EventListener`, `javax.sql.PooledConnection`, `OraclePooledConnection`, `oracle.jdbc.diagnostics.Diagnosable`, `oracle.jdbc.internal.Monitor`

Direct Known Subclasses:
  `OracleXAConnection`

    public class OraclePooledConnection
    extends java.lang.Object
    implements OraclePooledConnection, java.io.Serializable, oracle.jdbc.internal.Monitor, oracle.jdbc.diagnostics.Diagnosable

An OraclePooledConnection object is a connection object that provides hooks for connection pool management. A PooledConnection object represents a physical connection to a data source. It implements javax.sql.PooledConnection

See Also:
  Serialized Form

### Nested Class Summary

### Nested classes/interfaces inherited from interface oracle.jdbc.internal.Monitor

`oracle.jdbc.internal.Monitor.CloseableLock, oracle.jdbc.internal.Monitor.WaitableMonitor`

### Field Summary

Fields
`protected boolean` `autoCommit`
`static java.lang.String` `close_callback_string`
`int` `closeOption`
`static java.lang.String` `connect_auto_commit_string`
`static java.lang.String` `connection_properties_string`
`static java.lang.String` `event_listener_string`
`static java.lang.String` `explicit_caching_enabled`
`static java.lang.String` `ExplicitStatementCachingEnabled`
`static java.lang.String` `implicit_caching_enabled`
`static java.lang.String` `ImplicitStatementCachingEnabled`
`static java.lang.String` `isClearMetaData`
`protected oracle.jdbc.internal.OracleConnection` `logicalHandle`
`static java.lang.String` `LoginTimeout`
`static java.lang.String` `NO_IMPLICIT_BEGIN_REQUEST_PROPERTY`
`static java.lang.String` `object_type_map`
`protected oracle.jdbc.driver.OracleDriver` `oracleDriver`
`protected oracle.jdbc.internal.OracleConnection` `physicalConn`
`static java.lang.String` `pool_auto_commit_string`
`static java.lang.String` `private_data`
`protected oracle.jdbc.internal.OracleConnection` `replayConn`
`static java.lang.String` `sql_exception_string`
`static java.lang.String` `statement_cache_size`
`static java.lang.String` `transaction_isolation`
`static java.lang.String` `url_string`

### Constructor Summary

Constructors
`OraclePooledConnection()`
`OraclePooledConnection​(java.lang.String url)` Creates a PooledConnection.
`OraclePooledConnection​(java.lang.String url, java.lang.String user, java.lang.String passwd)` Creates a PooledConnection.
`OraclePooledConnection​(java.sql.Connection pc)` Create a Pooled Connection.
`OraclePooledConnection​(java.sql.Connection pc, boolean ac)` Create a Pooled Connection.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `addConnectionEventListener​(javax.sql.ConnectionEventListener cel)` Add an event listener.
`void` `addStatementEventListener​(javax.sql.StatementEventListener listener)`
`void` `close()` Close the physical connection.
`java.sql.CallableStatement` `getCallWithKey​(java.lang.String key)` getCallWithKey Searches the explicit cache for a match on key.
`java.sql.Connection` `getConnection()` Create an object handle for this physical connection.
`protected oracle.jdbc.internal.OracleConnection` `getConnectionDuringExceptionHandling()`
`oracle.jdbc.diagnostics.Diagnosable` `getDiagnosable()`
`boolean` `getExplicitCachingEnabled()` getExplicitCachingEnabled Returns true if the explicit cache is currently enabled, false otherwise.
`boolean` `getImplicitCachingEnabled()` getImplicitCachingEnabled Returns true if the implicit cache is currently enabled, false otherwise.
`long` `getLastAccessedTime()` Deprecated.
`java.sql.Connection` `getLogicalHandle()` Return the logical handle to the caller.
`oracle.jdbc.internal.Monitor.CloseableLock` `getMonitorLock()`
`java.sql.Connection` `getPhysicalHandle()`
`int` `getStatementCacheSize()` getStatementCacheSize Returns the current size of the application cache.
`java.sql.PreparedStatement` `getStatementWithKey​(java.lang.String key)` getStatementWithKey Searches the explicit cache for a match on key.
`int` `getStmtCacheSize()` Deprecated.
`javax.transaction.xa.XAResource` `getXAResource()` Return an XA resource to the caller.
`boolean` `isStatementCacheInitialized()`
`void` `purgeExplicitCache()` purgeExplicitCache Removes all existing statements from the explicit cache, after which it will be empty.
`void` `purgeImplicitCache()` purgeImplicitCache Removes all existing statements from the implicit cache, after which it will be empty.
`void` `registerImplicitCacheConnectionEventListener​(javax.sql.ConnectionEventListener cel)` Deprecated.
`void` `removeConnectionEventListener​(javax.sql.ConnectionEventListener cel)` Remove an event listener.
`void` `removeStatementEventListener​(javax.sql.StatementEventListener listener)`
`void` `setConnection​(oracle.jdbc.internal.OracleConnection rconn)`
`void` `setExplicitCachingEnabled​(boolean cache)` setExplicitCachingEnabled Enables or disables the explicit cache.
`void` `setImplicitCachingEnabled​(boolean cache)` setImplicitCachingEnabled Enables or disables the implicit cache.
`void` `setLastAccessedTime​(long lastAccessedTime)` Deprecated.
`void` `setProperties​(java.util.Hashtable prop)`
`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's session.
`void` `setStatementCacheSize​(int size)` setStatementCacheSize Specifies the size of the size of the application cache (which will be used by both implicit and explicit caching).
`void` `setStmtCacheSize​(int size)` Deprecated.
`void` `setStmtCacheSize​(int size, boolean clearMetaData)` Deprecated.

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface oracle.jdbc.diagnostics.Diagnosable

`begin, begin, beginCurrentSql, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debugp, end, end, endCurrentSql, format, isDebugEnabled, isDiagnoseFirstFailureEnabled, isLoggable, isSensitiveEnabled, onClose, propertyChange, resumeLogging, secure, suspendLogging, trace, tracep`

### Methods inherited from interface oracle.jdbc.internal.Monitor

`acquireCloseableLock, acquireLock, releaseLock`

### Field Detail

#### url_string

    public static final java.lang.String url_string

See Also:
  Constant Field Values

#### pool_auto_commit_string

    public static final java.lang.String pool_auto_commit_string

See Also:
  Constant Field Values

#### object_type_map

    public static final java.lang.String object_type_map

See Also:
  Constant Field Values

#### transaction_isolation

    public static final java.lang.String transaction_isolation

See Also:
  Constant Field Values

#### statement_cache_size

    public static final java.lang.String statement_cache_size

See Also:
  Constant Field Values

#### isClearMetaData

    public static final java.lang.String isClearMetaData

See Also:
  Constant Field Values

#### ImplicitStatementCachingEnabled

    public static final java.lang.String ImplicitStatementCachingEnabled

See Also:
  Constant Field Values

#### ExplicitStatementCachingEnabled

    public static final java.lang.String ExplicitStatementCachingEnabled

See Also:
  Constant Field Values

#### LoginTimeout

    public static final java.lang.String LoginTimeout

See Also:
  Constant Field Values

#### connect_auto_commit_string

    public static final java.lang.String connect_auto_commit_string

See Also:
  Constant Field Values

#### implicit_caching_enabled

    public static final java.lang.String implicit_caching_enabled

See Also:
  Constant Field Values

#### explicit_caching_enabled

    public static final java.lang.String explicit_caching_enabled

See Also:
  Constant Field Values

#### connection_properties_string

    public static final java.lang.String connection_properties_string

See Also:
  Constant Field Values

#### event_listener_string

    public static final java.lang.String event_listener_string

See Also:
  Constant Field Values

#### sql_exception_string

    public static final java.lang.String sql_exception_string

See Also:
  Constant Field Values

#### close_callback_string

    public static final java.lang.String close_callback_string

See Also:
  Constant Field Values

#### private_data

    public static final java.lang.String private_data

See Also:
  Constant Field Values

#### autoCommit

    protected boolean autoCommit

#### logicalHandle

    protected transient oracle.jdbc.internal.OracleConnection logicalHandle

#### physicalConn

    protected transient oracle.jdbc.internal.OracleConnection physicalConn

#### replayConn

    protected transient oracle.jdbc.internal.OracleConnection replayConn

#### closeOption

    public int closeOption

#### oracleDriver

    protected transient oracle.jdbc.driver.OracleDriver oracleDriver

#### NO_IMPLICIT_BEGIN_REQUEST_PROPERTY

    public static final java.lang.String NO_IMPLICIT_BEGIN_REQUEST_PROPERTY

See Also:
  Constant Field Values

### Constructor Detail

#### OraclePooledConnection

    public OraclePooledConnection()

#### OraclePooledConnection

    public OraclePooledConnection​(java.lang.String url)
                           throws java.sql.SQLException

Creates a PooledConnection.

Parameters:
  `url` - URL of the physical connection.
Throws:
  `java.sql.SQLException`

#### OraclePooledConnection

    public OraclePooledConnection​(java.lang.String url,
                                  java.lang.String user,
                                  java.lang.String passwd)
                           throws java.sql.SQLException

Creates a PooledConnection.

Parameters:
  `url` - URL of the physical connection.
  `user` - Username
  `passwd` - Password
Throws:
  `java.sql.SQLException`

#### OraclePooledConnection

    public OraclePooledConnection​(java.sql.Connection pc)

Create a Pooled Connection.

Parameters:
  `pc` - The corresponding physical connection.

#### OraclePooledConnection

    public OraclePooledConnection​(java.sql.Connection pc,
                                  boolean ac)

Create a Pooled Connection.

Parameters:
  `pc` - The corresponding physical connection
  `ac` - autoCommit value

### Method Detail

#### addConnectionEventListener

    public void addConnectionEventListener​(javax.sql.ConnectionEventListener cel)

Add an event listener.

Specified by:
  `addConnectionEventListener` in interface `javax.sql.PooledConnection`
Parameters:
  `cel` - The listener to be added

#### close

    public void close()
               throws java.sql.SQLException

Close the physical connection.

Specified by:
  `close` in interface `javax.sql.PooledConnection`
Throws:
  `java.sql.SQLException` - if a database-access error occurs.

#### getConnection

    public java.sql.Connection getConnection()
                                      throws java.sql.SQLException

Create an object handle for this physical connection. The object returned is a temporary handle used by application code to refer to a physical connection that is being pooled.

Specified by:
  `getConnection` in interface `javax.sql.PooledConnection`
Returns:
  a Connection object
Throws:
  `java.sql.SQLException` - if a database-access error occurs.

#### getLogicalHandle

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

Specified by:
  `getLogicalHandle` in interface `OraclePooledConnection`
Returns:
  a Connection object
Throws:
  `java.sql.SQLException`

#### getPhysicalHandle

    public java.sql.Connection getPhysicalHandle()
                                          throws java.sql.SQLException

Throws:
  `java.sql.SQLException`

#### setLastAccessedTime

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

Deprecated.

Specified by:
  `setLastAccessedTime` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### getLastAccessedTime

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

Deprecated.

Specified by:
  `getLastAccessedTime` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### registerImplicitCacheConnectionEventListener

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

Deprecated.

Specified by:
  `registerImplicitCacheConnectionEventListener` in interface `OraclePooledConnection`

#### removeConnectionEventListener

    public void removeConnectionEventListener​(javax.sql.ConnectionEventListener cel)

Remove an event listener.

Specified by:
  `removeConnectionEventListener` in interface `javax.sql.PooledConnection`
Parameters:
  `cel` - The listener to be removed.

#### setStmtCacheSize

    public void setStmtCacheSize​(int size)
                          throws java.sql.SQLException

Deprecated.
Set the statement cache size. Default is 0. You cannot call this for logicalhandles obtained from PooledConnections.

If more than <it> size </it> cursors are already cached than they will be closed. By default, the metadata of the cursor will be saved. Only data and the state will be cleared. You need to call this first to enable either type of Statement caching. When both types of Statement caching are enabled, the <it> size </size> is the total number of cursors cached for both the schemes together.

Parameters:
  `size` - Size of the Cache
Throws:
  `java.sql.SQLException`

#### setStmtCacheSize

    public void setStmtCacheSize​(int size,
                                 boolean clearMetaData)
                          throws java.sql.SQLException

Deprecated.
Set the statement cache size. Default is 0. You cannot call this for logicalhandles obtained from PooledConnections.

If more than <it> size </it> cursors are already cached than they will be closed. By default, the metadata of the cursor will be saved. But if clearMetaData is set to true, even that will be cleared. You need to call this first to enable either type of Statement caching. When both types of Statement caching are enabled, the <it> size </size> is the total number of cursors cached for both the schemes together.

Parameters:
  `size` - Size of the Cache
  `clearMetaData` - Whether the state has to be cleared or not
Throws:
  `java.sql.SQLException`

#### getStmtCacheSize

    public int getStmtCacheSize()

Deprecated.
Return the size of Statement Cache.

Returns:
  int Size of Statement Cache. If not set, the default 0 is returned.

#### setStatementCacheSize

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

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

Specified by:
  `setStatementCacheSize` in interface `OraclePooledConnection`
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

    public int getStatementCacheSize()
                              throws java.sql.SQLException

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

Specified by:
  `getStatementCacheSize` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### setImplicitCachingEnabled

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

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

Specified by:
  `setImplicitCachingEnabled` in interface `OraclePooledConnection`
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

    public boolean getImplicitCachingEnabled()
                                      throws java.sql.SQLException

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

Specified by:
  `getImplicitCachingEnabled` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### setExplicitCachingEnabled

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

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

Specified by:
  `setExplicitCachingEnabled` in interface `OraclePooledConnection`
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

    public boolean getExplicitCachingEnabled()
                                      throws java.sql.SQLException

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

Specified by:
  `getExplicitCachingEnabled` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### purgeImplicitCache

    public void purgeImplicitCache()
                            throws java.sql.SQLException

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

Specified by:
  `purgeImplicitCache` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### purgeExplicitCache

    public void purgeExplicitCache()
                            throws java.sql.SQLException

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

Specified by:
  `purgeExplicitCache` in interface `OraclePooledConnection`
Throws:
  `java.sql.SQLException`

#### getStatementWithKey

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

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

Specified by:
  `getStatementWithKey` in interface `OraclePooledConnection`
Parameters:
  `key` - Specified key to search for
Throws:
  `java.sql.SQLException`

#### getCallWithKey

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

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

Specified by:
  `getCallWithKey` in interface `OraclePooledConnection`
Parameters:
  `key` - Specified key to search for
Throws:
  `java.sql.SQLException`

#### isStatementCacheInitialized

    public boolean isStatementCacheInitialized()

#### setProperties

    public final void setProperties​(java.util.Hashtable prop)

#### getXAResource

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

Specified by:
  `getXAResource` in interface `OraclePooledConnection`
Returns:
  the XAResource (null if error occurs)
Throws:
  `java.sql.SQLException` - if a database error occurs

#### addStatementEventListener

    public void addStatementEventListener​(javax.sql.StatementEventListener listener)

Specified by:
  `addStatementEventListener` in interface `javax.sql.PooledConnection`

#### removeStatementEventListener

    public void removeStatementEventListener​(javax.sql.StatementEventListener listener)

Specified by:
  `removeStatementEventListener` in interface `javax.sql.PooledConnection`

#### setConnection

    public void setConnection​(oracle.jdbc.internal.OracleConnection rconn)
                       throws java.sql.SQLException

Throws:
  `java.sql.SQLException`

#### setShardingKeyIfValid

    public 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's session.

Specified by:
  `setShardingKeyIfValid` in interface `OraclePooledConnection`
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

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

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

Specified by:
  `setShardingKey` in interface `OraclePooledConnection`
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.

#### getConnectionDuringExceptionHandling

    protected oracle.jdbc.internal.OracleConnection getConnectionDuringExceptionHandling()

#### getMonitorLock

    public final oracle.jdbc.internal.Monitor.CloseableLock getMonitorLock()

Specified by:
  `getMonitorLock` in interface `oracle.jdbc.internal.Monitor`

#### getDiagnosable

    public oracle.jdbc.diagnostics.Diagnosable getDiagnosable()

Specified by:
  `getDiagnosable` in interface `oracle.jdbc.diagnostics.Diagnosable`