OC4J Data Sources: Implicit Connection Caching and Fast Connection Failover
OC4J Data Sources: Implicit Connection Caching and Fast Connection Failover
Written by Frances Zhao, Oracle Corporation
May 2005
1. Introduction
Oracle Containers for J2EE (OC4J) data sources integrate the new Implicit Connection Caching features in Oracle Database 10g JDBC, minimizing database access time while allowing transparent access to rich cache management functions such as connection striping, recycling, refreshing, and weight-based connection retrieval.
OC4J data sources also integrate Oracle Database 10g JDBC’s Fast Connection Failover support for Oracle databases. Fast Connection Failover provides the ability to failover connections in the connection cache as quickly and efficiently as the database itself, which is achieved by listening to the Oracle Database 10g RAC UP/DOWN failover events generated by the database.
This article gives an overview of the level of support and configuration for both Implicit Connection Caching and Fast Connection Failover in OC4J data sources, in Oracle Application Server 10g 9.0.4.x, 10.1.2, and 10.1.3. The overview of Fast Connection Failover support is minimal, as the subject will be explained in more detail in a forthcoming article on Oracle Application Server High Availability. Among different Oracle Application Server versions, OC4J 10g (10.1.3) data sources offer the best integrated support for both JDBC features, along with tools for users to migrate from pre-10.1.3 data sources to 10.1.3 data sources.
2. Implicit Connection Caching
2.1 Support in Oracle Application Server 10g (9.0.4.x) and 10g (10.1.2)
For these Oracle Application Server versions, Implicit Connection Caching support is limited to native data sources. Other types of data sources (e.g., emulated and non-emulated data sources) do not support this feature and use an older form of caching. For Oracle Application Server 10g (9.0.4.x) versions, since the default Oracle JDBC driver is older than Oracle 10g, users must upgrade the default driver to at least Oracle Database 10g JDBC in order to take advantage of this feature.
Configuring Implicit Connection Caching for these Oracle Application Server versions is mostly done in a declarative way by modifying the data-sources.xml file directly. The affected OC4J instance has to be restarted for the changes to take effect.
To configure Implicit Connection Caching, follow these two steps: (1) specify “oracle.jdbc.pool.OracleDataSource” as the “class” attribute in a <data-source> element; (2) specify the “connectionCacheName” and “connectionCachingEnabled” properties within the same <data-source> element. For example:
It is not possible to declaratively change the connection cache’s default property values like minimum and maximum number of connections. Oracle Database 10g JDBC provides APIs to change these default values programmatically. Please refer to the Oracle Database 10g JDBC documentation (Implicit Connection Caching Chapter) for details. A link to the JDBC documentation is provided in the References section.
2.2 Support in Oracle Application Server 10g (10.1.3)
Compared with earlier Oracle Application Server versions, OC4J 10g (10.1.3) data sources offer the best integrated support for Implicit Connection Caching, along with tools for users to migrate from pre-10.1.3 data sources to 10.1.3 data sources.
OC4J 10.1.3 offers two simple types of data sources: managed data source and native data source. Implicit Connection Caching is supported in both types of data sources.
The primary tool for configuring Implicit Connection Caching in OC4J 10.1.3 data sources is the user-friendly Oracle Enterprise Manager (EM) 10g Application Server Control Console. Central management of the data sources via the Console significantly lowers administrative cost. Standard JMX-based management supports the dynamic creation, deletion, and modification of both data source types, as well as the associated connection caches, without OC4J restart.
Alternatively, Implicit Connection Caching can still be enabled or disabled declaratively within the data-sources.xml deployment descriptor file for any OC4J data source. Because the descriptor syntax has changed in 10.1.3, this would be different from how it is done in earlier Oracle Application Server versions in Section 2.1.
Since some of the connection cache properties are not yet supported via the EM ASControl Console, we will explain in more detail how to configure Implicit Connection Caching declaratively in the next sections, based on data source types.
2.2.1 Managed Data Source
For managed data sources, configuring connection caches can be done in two steps: (1) add a connection cache with the <connection-pool> XML element in data-sources.xml to specify the details of its desired attributes; (2) use the "connection-pool-name" attribute in each <managed-data-source> XML element in the same file to specify the name of the connection cache that this managed data source uses to pool its connections.
Step (2) is relatively simple (as shown in red in above figure), so now we take a closer look at how Step 1 is done. The <connection-pool> element has the following attributes (each attribute is optional except when marked as 'Required'):
Attribute Name
Description
Default
name
<Required>. The name of the connection pool. Must be unique.
None
min-connections
The minimum number of connections that the connection pool will maintain.
0
max-connections
The maximum number of connections that can be open at any given time. A value of 0 or less indicates that there is no maximum limit.
0
initial-limit
This sets the size of the connection cache when the cache is initially created or reinitialized. When this property is set to a value greater than 0, that many connections are pre-created and are ready for use. This property is typically used to reduce the "ramp up" time in priming the cache to its optimal size.
0
used-connection-wait-timeout
The amount of time to wait (in seconds) for a used connection to be released by a client. This only applies when the maximum number of connections have been retrieved from the data source and are in use. In this case when a client tries to borrow a connection from the pool and all connections are in use, the connection pool will wait for a connection to be released back to the pool.
60
inactivity-timeout
The amount of time (in seconds) that an unused connection is inactive before it is removed from the pool.
60
login-timeout
The maximum amount of time (in seconds) that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout.
0
connection-retry-interval
The interval to wait (in seconds) before retrying a failed connection attempt. This is used in conjunction with "max-connnect-attempts".
1
max-connect-attempts
The number of times to retry making a connection. This is used in conjunction with "connection-retry-interval".
3
validate-connection
Indicates whether or not a connection, when borrowed from the pool, will be validated against the database. A value of "true" indicates that when a connection is borrowed from the connection pool, the statement, stated by "validate-connection-statement", is executed to verify that the connection is valid. A value of "false" means that no statement will be executed when a connection is borrowed from the pool. Used in conjunction with "validate-connection-statement".
false
validate-connection-statement
The SQL statement to execute when a connection is borrowed from the pool. Used in conjunction with "validate-connection".
None
num-cached-statements
The maximum number of statements that should be cached for each connection. Any value greater than 0 automatically enables statement caching for the data source.
0
time-to-live-timeout
The maximum time, in seconds, a used connection may be active. When this timeout expires, the used connection is unconditionally closed, the relevant statement handles are canceled, and the connection is returned to the connection pool. A value of –1 means that the feature is not enabled.
-1
abandoned-connection-timeout
Oracle databases only. Abandoned-connection-timeout is similar to the inactivity-timeout, but on a logical connection. When set, JDBC monitors SQL database activity on this logical connection (connection borrowed from the cache by the user). For example, when a stmt.execute() is invoked on this connection, a heart beat is registered to convey that this connection is active. The heart beats are monitored only at places (to lower the cost of monitoring), that result in database execute calls. If a connection has been inactive for the specified amount of time, the underlying PooledConnection is reclaimed and returned to the cache for reuse. The default value is -1, meaning, this feature is not in effect.
-1
disable-server-connection-pooling
Determines whether or not to disable the application server's connection pool. This attribute is available because some JDBC drivers provide connection pooling inside the driver. When the JDBC driver is Oracle and the driver is using the Implicit Connection Cache, then this attribute will be ignored.
false
property-check-interval
Oracle databases only. The time interval (in seconds) for the cache daemon thread to enforce the time out limits.
900
lower-threshold-limit
Oracle databases only. The lower threshold limit on the connection pool. Defaults to 20% of the max-connections.
20%
Besides the above attributes, each <connection-pool> element must contain one <connection-factory> element, which defines the connection factory used to create connections for the connection pool. A <connection-factory> element has the following attributes (each attribute is optional except when marked as 'Required'), and can also contain <property> tags, each defining a property on the connection factory instance.
Attribute Name
Description
Default
factory-class
<Required>. Defines the fully-pathed class of the connection-factory implementation. It must be an implementation of java.sql.Driver, javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, or javax.sql.XADataSource.
None
url
<Required>. The url to use to connect to the underlying database.
None
user
The default user to use to connect to the database.
None
password
The default password to use to connect to the database.
None
login-timeout
The maximum time (in seconds) to wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout.
0
Now let us look at two concrete examples:
Managed Data Source Using an XADataSource Connection Factory
For native Oracle data sources, declarative configuration of connection caches is very similar to how it is done in earlier Oracle Application Server versions (Section 2.1). Specifically, it can be done in two steps: (1) use "oracle.jdbc.pool.OracleDataSource" as the value for the "data-source-class" attribute in each <native-data-source> XML element in data-sources.xml; (2) specify in the <property> elements within <native-data-source> any cache-specific properties to control the connection cache's behavior.
For Step (2), the following property names can be used in the <property> element's specifications:
Name
Type
Description
connectionCacheName
String
Name of cache; cannot be changed after cache has been created.
Regardless of Oracle Application Server versions, in order to use Fast Connection Failover with OC4J data sources, you need to configure Oracle Notification Service (ONS) and RAC appropriately. You would need at least Oracle Database 10g (10.1.0.3) RAC, and the necessary patches. Please refer to the Oracle Database 10g JDBC documentation (Fast Connection Failover Chapter) for details. A link to the JDBC documentation is provided in the References section.
When using “oracle.jdbc.pool.OracleDataSource” as the native data source, there is a common way in all Oracle Application Server versions to enable Implicit Connection Caching and Fast Connection Failover at the same time, with all the connection cache properties taking their default values. That is, setting the system property “oracle.jdbc.FastConnectionFailover” to true when launching an OC4J instance. For example,
3.1 Support in Oracle Application Server 10g (9.0.4.x) and 10g (10.1.2)
For these Oracle Application Server versions, Fast Connection Failover support is limited to the native data sources. Other types of data sources (e.g., emulated and non-emulated data sources) do not support this feature. For Oracle Application Server 10g (9.0.4.x) versions, since the default Oracle JDBC driver is older than Oracle 10g, users must upgrade the default driver to at least Oracle Database 10g JDBC in order to take advantage of this feature.
Configuring Fast Connection Failover for these Oracle Application Server versions is done in a declarative way by modifying the data-sources.xml file directly. The affected OC4J instance has to be restarted for the changes to take effect.
To configure Fast Connection Failover, follow these two steps: (1) specify “oracle.jdbc.pool.OracleDataSource” as the “class” attribute in a <data-source> element; (2) specify the “fastConnectionFailoverEnabled” property with value “true” within the same <data-source> element. Remember, Implicit Connection Caching must already be configured a priori. For example:
3.2 Support in Oracle Application Server 10g (10.1.3)
For OC4J 10.1.3 data sources, declarative configuring of Fast Connection Failover is very similar to how it is done in earlier Oracle Application Server versions (Section 3.1). Specifically, it can be done in two steps, depending on the data source type.
For managed data sources, (1) specify “oracle.jdbc.pool.OracleDataSource” as the “factory-class” attribute in a <connection-factory> element for a configured <connection-pool>; (2) specify the “fastConnectionFailoverEnabled” property with value “true” within the same <connection-factory> element. For example,
For native data sources, (1) specify “oracle.jdbc.pool.OracleDataSource” as the “data-source-class” attribute in a <native-data-source> element; (2) specify the “fastConnectionFailoverEnabled” property with value “true” within the same <native-data-source> element. For example:
Bookmark
