Statement Caching
Statement caching improves performance by caching executable statements that are used repeatedly, such as in a loop or in a method that is called repeatedly. Starting from JDBC 3.0, JDBC standards define a statement-caching interface.
Statement caching can do the following:
■ Prevent the overhead of repeated cursor creation
■ Prevent repeated statement parsing and creation
■ Reuse data structures in the client
Note:Oracle strongly recommends you use the implicit Statement cache. Oracle JDBC drivers are designed on the assumption that the implicit Statement cache is enabled. So, not using the Statement cache will have a negative impact on performance.
Basics of Statement Caching
Applications use the Statement cache to cache statements associated with a particular physical connection. The cache is associated with an OracleConnection object. OracleConnection includes methods to enable Statement caching. When you enable Statement caching, a statement object is cached when you call the close method.
Because each physical connection has its own cache, multiple caches can exist if you enable Statement caching for multiple physical connections. When you enable Statement caching on a connection cache, the logical connections benefit from the Statement caching that is enabled on the underlying physical connection. If you try to enable Statement caching on a logical connection held by a connection cache, then this will throw an exception.
There are two types of Statement caching: implicit and explicit. Each type of Statement cache can be enabled or disabled independent of the other. You can have either, neither, or both in effect. Both types of Statement caching share a single cache per connection.
Implicit Statement Caching
When you enable implicit Statement caching, JDBC automatically caches the prepared
or callable statement when you call the close method of this statement object. The
prepared and callable statements are cached and retrieved using standard connection
object and statement object methods.
Plain statements are not implicitly cached, because implicit Statement caching uses a
SQL string as a key and plain statements are created without a SQL string. Therefore,
implicit Statement caching applies only to the OraclePreparedStatement and
OracleCallableStatement objects, which are created with a SQL string. You
cannot use implicit Statement caching with OracleStatement. When you create an
OraclePreparedStatement or OracleCallableStatement, the JDBC driver
automatically searches the cache for a matching statement. The match criteria are the
following:
■ The SQL string in the statement must be identical to one in the cache.
■ The statement type must be the same, that is, prepared or callable.
■The scrollable type of result sets produced by the statement must be the same, that
is, forward-only or scrollable.
If a match is found during the cache search, then the cached statement is returned. If a
match is not found, then a new statement is created and returned. In either case, the
statement, along with its cursor and state are cached when you call the close method
of the statement object.
When a cached OraclePreparedStatement or OracleCallableStatement
object is retrieved, the state and data information are automatically reinitialized and
reset to default values, while metadata is saved. Statements are removed from the
cache to conform to the maximum size using a Least Recently Used (LRU) algorithm.
Using Implicit Statement Caching
Once you enable implicit Statement caching, by default, all prepared and callable
statements are automatically cached. Implicit Statement caching includes the following
steps:
1. Enable implicit Statement caching.
2. Allocate a statement using one of the standard methods.
3. Disable implicit Statement caching for any particular statement you do not want to
cache. This is an optional step.
4. Cache the statement using the close method.
5. Retrieve the implicitly cached statement by calling the appropriate standard
prepare method.
Enabling Implicit Statement Caching
There are two ways to enable implicit Statement caching. The first method enables
Statement caching on a nonpooled physical connection, where you need to explicitly
specify the Statement size for every connection, using the setStatementCacheSize
method. The second method enables Statement caching on a pooled logical
connection. Each connection in the pool has its own Statement cache with the same
maximum size that can be specified by setting the MaxStatementsLimit property.
Method 1
Perform the following steps:
■Call the OracleDataSource.setImplicitCachingEnabled(true) method
on the connection to set the OracleDataSource property
implicitCachingEnabled to true. For example:
OracleDataSource ods = new OracleDataSource();
...
ods.setImplicitCachingEnabled(true);
...
■Call the OracleConnection.setStatementCacheSize method on the
physical connection. The argument you supply is the maximum number of
statements in the cache. For example, the following code specifies a cache size of
ten statements:
((OracleConnection)conn).setStatementCacheSize(10);
Method 2
Perform the following steps:
■Set the OracleDataSource properties implicitCachingEnabled and
connectionCachingEnabled to true. For example:
OracleDataSource ods = new OracleDataSource();
...
ods.setConnectionCachingEnabled( true );
ods.setImplicitCachingEnabled( true );
...
■Set the MaxStatementsLimit property to a positive integer on the connection
cache, when using the connection cache. For example:
Properties cacheProps = new Properties();
...
cacheProps.put( "MaxStatementsLimit", "50" );
To determine whether implicit caching is enabled, call getImplicitCachingEnabled, which returns true if implicit caching is enabled, false otherwise.
Disabling Implicit Statement Caching
Disable implicit Statement caching by calling setImplicitCachingEnabled(false) on the connection or by setting the ImplicitCachingEnabled property to false.
Allocating a Statement for Implicit Caching
To allocate a statement for implicit Statement caching, use either the
prepareStatement or prepareCall method as you would typically.
The following code allocates a new statement object called pstmt:
PreparedStatement pstmt = conn.prepareStatement
("UPDATE emp SET ename = ? WHERE rowid = ?");
Disabling Implicit Statement Caching for a Particular Statement
With implicit Statement caching enabled for a connection, by default, all callable and
prepared statements of that connection are automatically cached. To prevent a
particular callable or prepared statement from being implicitly cached, use the
setDisableStatementCaching method of the statement object. You can manage
cache space by calling the setDisableStatementCaching method on any
infrequently used statement.
The following code disables implicit Statement caching for pstmt:
PreparedStatement pstmt = conn.prepareStatement("SELECT 1 from DUAL");
((OraclePreparedStatement)pstmt).setDisableStmtCaching(true);
pstmt.close ();
If you are using JSE 6, then you can disable Statement caching
by using the standard JDBC 4.0 method setPoolable:
Note:
PreparedStatement.setPoolable(false);
Use the following to check whether the Statement object is poolable:
Statement.isPoolable();
Implicitly Caching a Statement
To cache an allocated statement, call the close method of the statement object. When
you call the close method on an OraclePreparedStatement or
OracleCallableStatement object, the JDBC driver automatically puts this
statement in cache, unless you have disabled caching for this statement.
The following code caches the pstmt statement:
pstmt.close ();
Retrieving an Implicitly Cached Statement
To retrieve an implicitly cached statement, call either the prepareStatement or
prepareCall method, depending on the statement type.
The following code retrieves pstmt from cache using the prepareStatement
method:
pstmt = conn.prepareStatement ("UPDATE emp SET ename = ? WHERE rowid = ?");
Using Explicit Statement Caching
A prepared or callable statement can be explicitly cached when you enable explicit
Statement caching. Explicit Statement caching includes the following steps:
1. Enable explicit Statement caching.
2. Allocate a statement using one of the standard methods.
3. Explicitly cache the statement by closing it with a key, using the closeWithKey
method.
4. Retrieve the explicitly cached statement by calling the appropriate Oracle WithKey
method, specifying the appropriate key.
5. Re-cache an open, explicitly cached statement by closing it again with the
closeWithKey method. Each time a cached statement is closed, it is re-cached
with its key.
Enabling Explicit Statement Caching
To enable explicit Statement caching you must first set the Statement cache size. For
setting the cache size, call OracleConnection.setStatementCacheSize method
on the physical connection. The argument you supply is the maximum number of
statements in the cache. An argument of 0 specifies no caching. To check the cache
size, use the getStatementCacheSize method in the following way:
System.out.println("Stmt Cache size is " +
((OracleConnection)conn).getStatementCacheSize());
The following code specifies a cache size of ten statements:
((OracleConnection)conn).setStatementCacheSize(10);
Enable explicit Statement caching by calling setExplicitCachingEnabled(true)
on the connection.
To determine whether explicit caching is enabled, call
getExplicitCachingEnabled, which returns true if explicit caching is enabled,
false otherwise.
Note:
■You enable implicit and explicit caching for a particular
physical connection independently. Therefore, it is possible to
do Statement caching both implicitly and explicitly during the
same session.
■Implicit and explicit Statement caching share the same cache.
Remember this when you set the statement cache size.
Disabling Explicit Statement Caching
Disable explicit Statement caching by calling
setExplicitCachingEnabled(false). Disabling caching or closing the cache
purges the cache. The following example disables explicit Statement caching:
((OracleConnection)conn).setExplicitCachingEnabled(false);
Allocating a Statement for Explicit Caching
To allocate a statement for explicit Statement caching, use either the
createStatement, prepareStatement, or prepareCall method as you would
typically.
The following code allocates a new statement object called pstmt:
PreparedStatement pstmt =
conn.prepareStatement ("UPDATE emp SET ename = ? WHERE rowid = ?");
Explicitly Caching a Statement
To explicitly cache an allocated statement, call the closeWithKey method of the
statement object, specifying a key. The key is an arbitrary Java String that you
provide. The closeWithKey method caches a statement as is. This means the data,
state, and metadata are retained and not cleared.
The following code caches the pstmt statement with the key "mykey":
((OraclePreparedStatement)pstmt).closeWithKey ("mykey");
Retrieving an Explicitly Cached Statement
To recall an explicitly cached statement, call either the getStatementWithKey or
getCallWithKey methods depending on the statement type.
If you retrieve a statement with a specified key, then the JDBC driver searches the
cache for the statement, based on the specified key. If a match is found, then the
matching statement is returned along with its state, data, and metadata. This
information is as it was when the statement was last closed. If a match is not found,
then the JDBC driver returns null.
The following code recalls pstmt from cache using the "mykey" key with the
getStatementWithKey method. Recall that the pstmt statement object was cached
with the "mykey" key.
pstmt = ((OracleConnection)conn).getStatementWithKey ("mykey");
If you call the creationState method on the pstmt statement object, then the
method returns EXPLICIT.
Table 20–3 Methods Used to Retrieve Explicitly Cached Statements
Method Functionality for Explicit Statement Caching
getStatementWithKey Specifies the key needed to retrieve a prepared statement from cache
getCallWithKey Specifies the key needed to retrieve a callable statement from cache
Closing a Cached Statement
Perform the following to close a Statement and assure that it is not returned to the cache.
In J2SE 5.0
■Disable caching for that statement
stmt.setDisableStatementCaching(true);
■Call the close method of the statement object
stmt.close();
In JSE 6.0
stmt.setPoolable(false);
stmt.close();
Physically Closing a Cached Statement
With implicit Statement caching enabled, you cannot physically close statements
manually. The close method of a statement object caches the statement instead of
closing it. The statement is physically closed automatically under one of following
three conditions:
■When the associated connection is closed
■When the cache reaches its size limit and the least recently used statement object is preempted from cache by the LRU algorithm
■If you call the close method on a statement for which Statement caching is disabled
Reusing Statements Objects
The JDBC 3.0 specification introduces the feature of statement pooling that allows an
application to reuse a PreparedStatement object in the same way as it uses a
Connection object. The PreparedStatement objects can be reused by multiple
logical connections in a transparent manner.
Using a Pooled Statement
An application can find out whether a data source supports statement pooling by
calling the isPoolable method from the Statement interface. If the return value is
true, then the application knows that the PreparedStatement object is being
pooled. The application can also request a statement to be pooled or not pooled by
using the setPoolable method from the Statement interface.
Reusing of pooled statement should be completely transparent to the application, that
is, the application code should remain the same whether a PreparedStatement
object participates in statement pooling or not. If an application closes a
PreparedStatement object, it must still call Connection.prepareStatement
method in order to reuse it.
An application has no direct control over how statements are
pooled. A pool of statements is associated with a
PooledConnection object, whose behavior is determined by the
properties of the ConnectionPoolDataSource object that
produced it.
Note:
Closing a Pooled Statement
An application closes a pooled statement exactly the same way it closes a nonpooled
statement. Once a statement is closed, whether is it pooled or nonpooled, it is no
longer available for use by the application and an attempt to reuse it causes an
exception to be thrown. The only difference visible is that an application cannot
directly close a physical statement that is being pooled. This is done by the pool
manager. The method PooledConnection.closeAll closes all of the statements
open on a given physical connection, which releases the resources associated with
those statements.
The following methods can close a pooled statement:
■close
This java.sql.Statement interface method is called by an application. If the
statement is being pooled, then it closes the logical statement used by the
application but does not close the physical statement being pooled.
■close
This java.sql.Connection interface method is called by an application. This
method acts differently depending upon whether the connection using the
statement is being pooled or not:
–Nonpooled connection
This method closes the physical connection and all statements created by that
connection. This is necessary because the garbage collection mechanism is
unable to detect when externally managed resources can be released.
–Pooled connection
This method closes the logical connection and the logical statements it
returned, but leaves open the underlying PooledConnection object and any
associated pooled statements
■PooledConnection.closeAll
This method is called by the connection pool manager to close all of the physical
statements being pooled by the PooledConnection object
