3 Connection Management

This chapter provides details of how OC4J administrators set up the configuration for resource adapter connections, then summarizes the J2CA connection management contract and discusses how an application component obtains a connection. This includes the following topics:

• Introduction to How EIS Connections Are Obtained

• Binding and Configuring a Connection Factory: Basic Settings

• Configuring Connection Pooling in OC4J

• Sharing Connection Pools

• Configuring OC4J Logging for Connection Factories

• Obtaining Resource Adapter Connections

• Summary of the Connection Management Contract

• Metrics for Resource Adapter Connections

Note: See Summary of Application Server Control Pages for Resource Adapters for an overview of the Application Server Control Console pages discussed here. Discussion in this chapter starts from the point where you have reached the appropriate Resource Adapter Home page.

Introduction to How EIS Connections Are Obtained

To use the resources of an EIS, a J2EE application component obtains a connection object, uses the underlying connection to conduct its business (reading or writing data as desired), then closes the connection.

Connection objects are obtained through a connection factory, which is implemented by the resource adapter provider. A connection factory object is registered in the JNDI namespace, through configuration steps that you take, and has a method that returns a connection object. The application component performs the JNDI lookup to retrieve the factory, then makes a request through the factory to obtain a connection. The factory delegates the request to OC4J. (See the Oracle Containers for J2EE Services Guide for information about the OC4J JNDI implementation.)

For a resource adapter that implements the CCI, the factory will be an instance of a class that implements the CCI (javax.resource.cci) ConnectionFactory interface, which specifies a method getConnection() that returns an instance of a class that implements the CCI Connection interface.

In the J2EE Connector Architecture, the functionality discussed here is specified in the connection management contract, which is more fully summarized in "Summary of the Connection Management Contract". This contract specifies how to create connections to an EIS and how to set up JNDI configuration for connection factories. It also provides a general outline for how a J2EE container such as OC4J can support connection pooling, which is critical for efficient use of EIS resources and scalability of applications, and it specifies how to find matching physical connections in a connection pool. See "Configuring Connection Pooling in OC4J" for information about how the administrator configures the OC4J implementation of connection pooling.

The next section, "Binding and Configuring a Connection Factory: Basic Settings", describes how the administrator sets up connection factories.

Binding and Configuring a Connection Factory: Basic Settings

Before an application component can use connections to an EIS, one or more connection factories must be configured. This section shows the most basic steps in configuring a resource adapter and binding it to JNDI. Further steps, such as configuring connection pooling for a connection factory, are discussed later in this chapter. Additional steps, such as configuring security, are discussed later in this manual.

"Obtaining Resource Adapter Connections" shows how to use a connection factory in application code.

Create and Bind a Connection Factory

When you deploy a resource adapter, OC4J generates an oc4j-ra.xml file (unless one is packaged in the RAR file), using corresponding entries in the packaged ra.xml file as defaults.

For each connection type defined, OC4J generates a <connector-factory> element in oc4j-ra.xml during deployment. (In version 1.5 of the J2EE Connector Architecture Specification, a connection type corresponds to a <connection-definition> element in the ra.xml file.) Furthermore, when you configure a resource adapter, OC4J generates subelements under the <connector-factory> element for any settings you specify through the Application Server Control Console that supplement or override entries in ra.xml.

The unique identifier for a connection type in the ra.xml file is the connection factory interface. One interface is specified as part of each ra.xml connection definition. In oc4j-ra.xml, however, there can ultimately be multiple connection factories (that is, multiple <connector-factory> elements) using the same connection factory interface and therefore corresponding to the same ra.xml connection definition. The point of this would be to configure each connection factory with different property settings, as desired. For example, you can use different connection factories to connect to different servers. (Note that the JNDI location you specify for each connection factory must be unique to that connection factory.)

A key step in creating a connection factory is to bind it, where binding consists of specifying a JNDI location. The simplest scenario for this is to use the default assembled values for the configuration properties, meaning values that come from the ra.xml file. (We will assume for this discussion that they are specified in ra.xml, which is optional.) However, when you create a connection factory, you can specify new deployment values for the configuration properties.

You also specify whether you want connection pooling for the connection factory and, if so, whether to use a private pool or shared pool.

In the Application Server Control Console, use the following steps.

1. In the Connection Factories tab accessed from the Resource Adapter Home page for the appropriate resource adapter (the generic JMS resource adapter, for example, if it is deployed), choose the "Create" feature to start the process of binding a new connection factory.

2. In the Create Connection Factory: Select Interface page, choose the desired connection factory interface. For a J2CA 1.5 adapter, each choice corresponds to one and only one connection definition in the ra.xml file. For a version 1.0 adapter, there will be only one choice. (The generic JMS resource adapter, for example, has the choices QueueConnectionFactory, XAQueueConnectionFactory, TopicConnectionFactory, and XATopicConnectionFactory.)

3. In the resulting Create Connection Factory page, you can do the following:

   • Specify a JNDI location (mandatory).

   • Specify whether you want the connection factory to use no connection pool (the default), a private connection pool, or a shared connection pool. To use shared pooling, at least one shared pool must already exist, and you must choose which shared pool to use. See "Configuring Connection Pooling in OC4J" and "Sharing Connection Pools" for information about connection pools.

   • Optionally edit configuration properties of the connection factory.

4. Still in the Create Connection Factory page, choose the "Finish" feature to bind the connection factory.

As a result of this configuration, OC4J generates a <connector-factory> element in the oc4j-ra.xml file. Table 3-1 shows the properties that indicate the connection factory interface and JNDI location.

Also see the context-sensitive topic "Create Connection Factory: Select Interface Page" in the Application Server Control online help.

Table 3-1 Connection Factory Basic Properties

Application Server Control Property	Corresponding XML Entity	Description
Connection Factory Interface	<connectionfactory-interface> subelement	Java interface to use for the connection factory.
JNDI Location	location attribute	A JNDI location to which the connection factory object will be bound.
As applicable for the resource adapter, and as indicated by configuration property Name and Value attributes. Or, when you are editing, as indicated by Name, Assembled Value, and Deployed Value. (Name and Assembled Value are according to ra.xml.)	<config-property> Name and Value attributes	These attributes correspond to the name and desired deployed value of a connection factory configuration property.

Note: Binding a connection factory takes effect immediately; no restart of OC4J is necessary. (Note, however, that the binding of a connection factory that is preconfigured in an oc4j-ra.xml file that is packaged with the application occurs when the associated resource adapter is initialized, which follows resource adapter deployment or OC4J startup.)

Edit the Configuration Properties of an Existing Connection Factory

You can edit the settings of a connection factory that you previously created and bound.

In the Application Server Control Console, do the following:

1. In the Connection Factories tab accessed from the Resource Adapter Home page for the appropriate resource adapter, choose the JNDI location of a previously configured connection factory. Note that the JNDI location serves as the identifier of the connection factory and cannot be edited. The assembled values are from ra.xml entries.

2. In the General tab accessed from the resulting Edit Connection Factory page, you can specify new deployed values of any editable configuration properties. You can also configure the connection pool from here, if the connection factory was created with private or shared connection pooling enabled. See the next section, "Configuring Connection Pooling in OC4J", for information.

3. In the same page, apply the changes.

When you edit a connection factory, OC4J adds or updates <config-property> entries in oc4j-ra.xml to override previous settings in ra.xml or oc4j-ra.xml, as applicable.

Also see the context-sensitive topic "Resource Adapter Connection Factories Page" in the Application Server Control online help.

Note: You must restart OC4J for these changes to take effect.

Configuring Connection Pooling in OC4J

For performance and scalability, the J2EE Connector Architecture supports the implementation of connection pooling by any application server provider. This section discusses how to configure connection pooling in OC4J, beginning with basic configuration and then covering connection pooling enhancements added in the OC4J 10.1.3 implementation.

You determine whether to enable connection pooling when you create a connection factory, and you can configure the applicable pool when you edit the connection factory.

Notes: A connection pool is initialized during OC4J startup or when the resource adapter is deployed. A connection pool can be private to a single connection factory or shareable between multiple connection factories, but the configuration information discussed here generally applies in either case. See "Sharing Connection Pools" for information about shareable pools.

The presence of a <connection-pooling> subelement under a <connector-factory> element in the oc4j-ra.xml file implies that connection pooling will be used for the corresponding connector factory (unless the <connection-pooling> element has the attribute setting use="none"). When you configure connection pooling through Application Server Control, OC4J generates the <connection-pooling> element along with a <property> subelement for each connection pooling property that you set.

If you do not configure connection pooling, OC4J exhibits the default behavior of creating a new physical connection whenever an application requests a connection. You can also explicitly specify no connection pooling for any given connector factory, through the Application Server Control Console.

Note: Because the J2EE Connector Architecture is general, rather than specific to databases, the connector architecture connection pooling interface differs significantly from the JDBC connection pooling interface.

The rest of the discussion for configuring connection pools is organized as follows:

• Enable Connection Pooling for a Connection Factory

• Configure a Connection Pool

• Pooling Scheme, Minimum and Maximum Connections, Initial Capacity

• Checking for Expired or Invalid Connections

• OC4J Support for Runtime Configuration of Connection Pools

Enable Connection Pooling for a Connection Factory

As noted in "Create and Bind a Connection Factory", you choose whether to use connection pooling for a connection factory when you create the connection factory. During creation, you must specify whether you want the connection factory to use no connection pool (the default), a private connection pool, or a shared connection pool. For you to use shared pooling, at least one shared pool must already exist, and you must choose which shared pool to use. (See "Sharing Connection Pools" for information about shared pools.)

Table 3-2 documents relevant properties in the Application Server Control Console Create Connection Factory page.

Table 3-2 Properties for Enabling or Disabling Connection Pooling

Application Server Control Property	Corresponding XML Entity	Description
No Connection Pool	<connection-pooling> with use="none"	Disables connection pooling for the connection factory you are configuring.
Use Private Connection Pool	<connection-pooling> with use="private"	Specifies the use of a private connection pool for the connection factory you are configuring.
Use Shared Connection Pool	<connection-pooling> with use="shared"	Specifies the use of a shared connection pool for the connection factory you are configuring.
(Indicated name of shared connection pool)	<use-connection-pool>	Names the shared connection pool to use.

Note: If an OC4J 9.0.4 version of oc4j-ra.xml is deployed to an OC4J 10.1.3 implementation server, any <connection-pooling> element receives an attribute setting of use="private" by default. This attribute was not in use in the OC4J 9.0.4 implementation. Other supported settings are "none", for no connection pooling, or "shared" for shared pools, as discussed later in this chapter.

Configure a Connection Pool

You can change the configuration of a connection pool by editing the connection factory that uses it, regardless of whether the pool is private or shared.

Use the Application Server Control Console, as follows:

1. From the Connection Factories tab, accessed from the Resource Adapter Home page, choose the appropriate JNDI location to select the connection factory of interest.

2. From the General tab of the resulting Edit Connection Factory page, select the shared connection pool or select "Private", as applicable.

3. In the resulting Private Connection Pool page (or Shared Connection Pool page for a shared pool), specify desired settings for the connection pool parameters. For information about these parameters, see the next section, "Pooling Scheme, Minimum and Maximum Connections, Initial Capacity", and see "Checking for Expired or Invalid Connections".

4. Apply your changes.

Also see the context-sensitive topics "Private Connection Pool Page" and "Shared Connection Pool Page" in the Application Server Control online help.

Pooling Scheme, Minimum and Maximum Connections, Initial Capacity

Table 3-3 summarizes basic connection pooling settings supported since the OC4J 9.0.4 implementation. You can view or edit these in the Application Server Control Console Private Connection Pool page (or the Shared Connection Pool page, for shared pools). OC4J reflects each setting in a <property> subelement of the applicable <connection-pooling> element in oc4j-ra.xml (or the applicable <connection-pool> element for shared pools).

Table 3-3 Basic Connection Pool Properties

Application Server Control Property	Corresponding XML Entity	Description
Connection Pooling Scheme	<property> with name="scheme" and value="dynamic", "fixed", or "fixed_wait"	How OC4J handles connection requests after the maximum number of connections is reached. This attribute supports a setting of "Dynamic", "Fixed", or "Fixed Wait", as described later in this table.
Maximum Connections	<property> with name="maxConnections" and value as appropriate	Desired maximum number of connections to maintain within a pool during program execution. If no value or a value of 0 is specified, then there is no limit on the number of connections.
Minimum Connections	<property> with name="minConnections" and value as appropriate	Desired minimum number of connections to maintain within a pool during program execution. The default value is 0.
Initial Capacity	<property> with name="initial-capacity" and value as appropriate	Desired number of connections for OC4J to create during initialization of the connection pool. If the specified initial capacity is less than the specified minimum number of connections, then any additional connections, once created, will not be removed from the pool until the number of connections exceeds the minimum. Note: Initial capacity applies to private connection pools only, not to shared connection pools. Note: It is possible that OC4J will be unable to open the specified number of connections due to lack of necessary information at initialization time, such as JNDI context.
Fixed Wait Timeout	<property> with name="waitTimeout" and value as appropriate	Maximum number of seconds to wait for an available connection if the maximum number of connections is exceeded and the Fixed Wait scheme is in effect. (Otherwise, this property is ignored.) The default is no timeout.

Here are descriptions of the three supported connection pooling schemes:

• "Dynamic" to always create a new connection and return it to the application, even if this violates the maximum limit. The next time a connection is closed, it is destroyed instead of being returned to the pool if the pool is still over the maximum limit. This is the default setting.

• "Fixed" to raise an exception when the application requests a connection after the maximum limit has been reached.

• "Fixed Wait" to block the application until a connection becomes available and is returned to the pool. If the "Fixed Wait Timeout" property is specified, then OC4J throws an exception if no connection becomes available within the specified wait timeout period.

The Initial Capacity parameter is useful if you anticipate that the demand for connections will be particularly high at startup. For example, if you have a connection pool with Minimum Connections set to 5 and Maximum Connections set to 50, with an anticipated high demand at startup, you can set Initial Capacity to 25. Once the initial demand has passed, you can use the Inactive Connection Timeout parameter (described in the next section, "Checking for Expired or Invalid Connections") to allow the pool to be scaled back toward the minimum number of connections until the next peak usage period.

Note: For any oc4j-ra.xml file, if there is a <connection-pooling> element with use="private" but no connection pool properties specified, OC4J uses a default pool configuration with the Dynamic connection pooling scheme and no preset minimum or maximum number of connections. Also, no connections are pre-created when the connection pool is initialized.

Checking for Expired or Invalid Connections

The OC4J 10.1.3 implementation adds support for removing connections that have expired or been marked invalid in a connection pool. By checking unused connections in a pool, OC4J can ensure that connections are valid when passed to J2EE applications.

Connections can become invalid due to a network timeout or other internal error. To enable OC4J to check for invalid connections, the resource adapter provider must implement the optional ValidatingManagedConnectionFactory interface to specify which connections are invalid. This interface, in the ManagedConnectionFactory implementation class underlying the connection factory, is part of the of the SPI (javax.resource.spi) package. See "Summary of the Connection Management Contract" for information about managed connection factories and how they are used.)

You can enable the checking features as follows:

• How often OC4J will check for invalid or expired connections is according to the "Expired Connection Cleanup" parameter.

• The timeout value for a connection to expire is according to the "Inactive Connection Timeout" parameter. After a connection in the pool is unused for that amount of time, it will be discarded.

These parameters, from the Application Server Control Console Private Connection Pool page (or Shared Connection Pool page, for a shared pool) are summarized in Table 3-4.

Depending on how you set these parameters, OC4J will do no checking, check for invalid connections only (if connections are set to never expire), or check for both invalid and expired connections (according to the specified timeout).

Each setting is reflected by OC4J in a <property> subelement of the applicable <connection-pooling> element.

Table 3-4 Settings to Check for Invalid or Expired Connections

Application Server Control Property	Corresponding XML Entity	Description
Expired Connection Cleanup	<property> with name="inactivity-timeout-check" and value="never", "periodic", "piggyback", or "all"	When to check for expired or inactive connections. Supported values are "never", "periodic", "piggyback" (when a new connection is fetched), and "all" (periodically and when a new connection is fetched), as described in the following text.
Inactive Connection Timeout	<property> with name="inactivity-timeout" and value as appropriate	The desired connection timeout, in seconds, as a positive integer, or 0 for connections to never expire. Negative values are disallowed.

Use "Expired Connection Cleanup" as follows:

• "never" to never check for expired or invalid connections. This effectively disables checking for both expired connections and invalid connections. If you specify a large number for maximum connections to accommodate peak usage, you can use "never" to trim the size of the connection pool to the in-use set of connections. If inactivity almost never occurs in your connection pool because the number of connections constantly in use is close to the number of maximum connections, specifying "never" can help optimize server performance.

• "periodic", the default value, to check after a set amount of time, repeatedly, such as every 10 minutes. The period used for checking is according to the granularity setting of the OC4J Task Manager (an interval in milliseconds). This is configurable through the JMX Management Console in Application Server Control and reflected in the value of the taskmanager-granularity attribute of the <application-server> element in the OC4J server.xml file. Be aware that any changes to this parameter will affect other OC4J tasks and OC4J performance. See Oracle Containers for J2EE Configuration and Administration Guide for information about Task Manager granularity.

• "piggyback" (when a new connection is fetched) to check only whenever a new connection is requested.

• "all" (periodically and when a new connection is fetched) to combine periodic checking with checking whenever a connection is requested.

When a connection is removed from a pool, the destroy() method is called.

Note: If removal of invalid or expired connections brings the number of connections in the pool below the desired minimum, OC4J will create new connections as appropriate.

OC4J Support for Runtime Configuration of Connection Pools

You can make changes to the parameters discussed in the preceding sections during program execution (with the exception of initial capacity, which takes effect only at OC4J startup). The changes are dynamic; they do not require a restart of OC4J. Here is a list of parameters for which runtime changes are supported, with notes about related OC4J behavior:

• For "Connection Pooling Scheme", the new scheme applies with the next connection request by an application. If the original scheme was "Fixed Wait", the new scheme will also take effect for any pending connection requests; and if the new scheme is "Fixed", this results in an exception for any connection request that was waiting for an available connection. If the original scheme was "Dynamic", and the number of connections is greater than the desired maximum at the time you change the scheme to "Fixed" or "Fixed Wait", then OC4J attempts to observe the maximum by closing and removing any unused connections from the pool.

• For "Maximum Connections", if the new value is less than the existing number of connections in the pool, OC4J will close any unused connections. If the number of in-use connections is still greater than the new maximum value, then as connections are closed by the application, they will not be returned to the pool until the number of connections is below the new maximum.

• For "Minimum Connections", if the new value is greater than the existing number of connections in the pool, OC4J will create enough new connections to satisfy the new minimum.

• For "Wait Timeout", the new value applies with the next connection request, assuming the scheme is "Fixed Wait".

• For "Inactive Connection Timeout", the new value applies the next time OC4J checks for expired connections. If the value was 0 and is now a positive integer, OC4J will start checking for expired connections. In this case, if the value of "Expired Connection Cleanup" is "never", it will be changed to "periodic".

• For "Expired Connection Cleanup", if the old value was "periodic" or "all" (periodically and when a new connection is fetched), the next periodic check may still be carried out.

Sharing Connection Pools

Beginning with the OC4J 10.1.3 implementation, there is support for multiple connection factories to share a single connection pool if all the factories are for the same resource adapter and use the same managed connection factory implementation class. This allows users to better manage the number of concurrent connections to the same type of EIS, or to utilize the same connection pool for all connection factories used with a single resource adapter.

This section documents shared connection pools, covering the following topics:

• Create and Configure a Shared Connection Pool

• Edit and Reconfigure a Shared Connection Pool

• Use a Shared Connection Pool

Create and Configure a Shared Connection Pool

To create a shareable connection pool, take the following steps in the Application Server Control Console:

1. Go to the Connection Factories tab, accessible from the Resource Adapter Home page.

2. Under "Shared Connection Pools", choose the "Create" function.

3. In the resulting Create Shared Connection Pool page, specify a desired name for the pool, such as SharedPool1. This is how it will be referred to later, when you want to use it for a connection factory. This property is summarized in Table 3-5.

4. Set parameters as desired. They are used in the same ways as for a private connection pool, as described in "Pooling Scheme, Minimum and Maximum Connections, Initial Capacity" and "Checking for Expired or Invalid Connections".

5. Apply your changes.

For a shared connection pool, OC4J will generate a <connection-pool> element directly under the root <oc4j-connector-factories> element in the oc4j-ra.xml file, instead of generating a <connection-pooling> element under a <connector-factory> element, as for a private pool associated with just one connection factory.

The supported properties for a shared pool are the same as for a pool that is specific to a particular connection factory. In the oc4j-ra.xml file, however, these would appear in <property> subelements of a <connection-pool> element, instead of in <property> subelements of a <connection-pooling> element (which is a subelement of the <connector-factory> element).

Also see the context-sensitive topic "Create Shared Connection Pool Page" in the Application Server Control online help.

Table 3-5 Shared Connection Pool Name Property

Application Server Control Property	Corresponding XML Entity	Description
Connection Pool Name (applicable only for a shared connection pool)	<connection-pool> name attribute	Desired name of a connection pool, to make it available for sharing between connection factories.

Note: Runtime changes are supported for shared connection pools, as they are for private connection pools. See "OC4J Support for Runtime Configuration of Connection Pools".

Edit and Reconfigure a Shared Connection Pool

To edit an existing shared connection pool:

1. You can get to the Shared Connection Pool page in the Application Server Control Console in either of two ways:

   • From the Connection Factories tab, accessible from the Resource Adapter Home page, select the pool you want to edit from the list under "Shared Connection Pools".

   • From the Connection Factories tab, select a connection factory that uses the shared connection pool you want to edit.

2. In the resulting Edit Connection Factory page, select the shared connection pool.

3. In the resulting Shared Connection Pool page, set parameters as desired.

   Parameters are used in the same ways as for a private connection pool, as described in "Pooling Scheme, Minimum and Maximum Connections, Initial Capacity" and "Checking for Expired or Invalid Connections".

4. Apply your changes.

Also refer to the topic "Shared Connection Pool Page" in the Application Server Control online help.

Note: You cannot change the name of an existing shared connection pool.

Use a Shared Connection Pool

As noted in "Enable Connection Pooling for a Connection Factory", you specify whether you want to use shared connection pooling (or private connection pooling or no connection pooling) when you first create a connection factory, in the Create Connection Factory page of the Application Server Control Console. If you choose to use shared connection pooling, you must also specify which shared pool to use.

When a connection factory is to use a shared connection pool, OC4J updates the oc4j-ra.xml file, adding a <connection-pooling> element for the appropriate connection factory (under the appropriate <connector-factory> element) with an attribute setting of use="shared" and a <use-connection-pool> subelement with a value that specifies the name of the shared pool. This name corresponds to the name attribute of the <connection-pool> element that specifies the shareable pool being used.

Notes: If a <connection-pooling> element has a <use-connection-pool> subelement, OC4J ignores any <property> subelements that would relate to a private pool. If a <connection-pooling> element has an attribute setting of use="shared" but there is no <use-connection-pool> subelement, OC4J will throw an exception. After specifying that a connection factory use a shared connection pool, you must restart OC4J for the change to take effect.

Configuring OC4J Logging for Connection Factories

The J2EE Connector Architecture includes optional features for system-level error logging and tracing for a particular managed connection factory. Using these features, an application server can detect error conditions in a resource adapter or its EIS and use error information in debugging problems. The application server manages the association between a log writer and a managed connection factory.

In OC4J, through Application Server Control, you can enable logging for a resource adapter by specifying a log file for a corresponding connection factory. Accomplish this through the following steps in the Application Server Control Console:

1. Go to the Connection Factories tab from the appropriate Resource Adapter Home page.

2. Choose the connection factory for which you want to enable logging.

3. From the resulting Edit Connection Factory page, go to the Options tab.

4. Specify the desired absolute or relative path and file name for a log file.

5. Apply your changes.

This setting is reflected in the <log> subelement of a <connector-factory> element in the oc4j-ra.xml file, as summarized in Table 3-6.

Also see the context-sensitive topic "Edit Connection Factory Options Page" in the Application Server Control online help.

Table 3-6 Log File Properties

Application Server Control Property	Corresponding XML Entity	Description
Log File	path attribute of the <file> subelement of the <log> element	This specifies the absolute or relative path and name of a log file where OC4J will write logging and tracing messages relating to the resource adapter and its EIS.

A relative path is relative to the resource adapter deployment directory. As noted in "What Are the Packaging and Deployment Features?", this is as follows, where instance is the name of the OC4J instance (home by default in an Oracle Application Server environment and always home in a standalone environment); app_name is the deployed application name (or default for a standalone resource adapter); and ra_name is the deployed resource adapter name (as specified during deployment for a standalone resource adapter, or according to the RAR file name, without the .rar extension, for a resource adapter deployed within an EAR file):

j2ee/instance/application-deployments/app_name/ra_name

Specifying either "mylog.log" or "./mylog.log", for example, results in the following log file location:

j2ee/instance/application-deployments/app_name/ra_name/mylog.log

Or "mydir/mylog.log" results in the following:

j2ee/instance/application-deployments/app_name/ra_name/mydir/mylog.log

Notes: If the specified directory for the log file does not exist, or if OC4J does not have permission to write to the specified directory, then OC4J does not enable logging and outputs a warning message. If the specified directory exists but the file does not exist, OC4J creates the file and enables logging. Messages written by OC4J to the log include those for error conditions that occur during deployment of the resource adapter or when OC4J attempts to start the resource adapter. The log file location is also passed on to managed connections.

Obtaining Resource Adapter Connections

This section shows a JNDI lookup of the connection factory that was configured in "Create and Bind a Connection Factory".

This example also depends on the associated JNDI configuration in the ejb-jar.xml and orion-ejb-jar.xml files. Following is a corresponding sample ejb-jar.xml entry. This file would be packaged in the application EAR file.

<resource-ref>
   <res-ref-name>eis/myEIS</res-ref-name>
   <res-type>javax.resource.cci.ConnectionFactory</res-type>
   <res-auth>Application</res-auth>
</resource-ref>

Use the Application Server Control Console to specify a resource reference mapping entry to link the JNDI location previously bound, eis/ConnectionFactory, to the JNDI name in the ejb-jar.xml file, eis/myEIS. This generates an entry in orion-ejb-jar.xml such as the following:

<resource-ref-mapping name="eis/myEIS" location="eis/ConnectionFactory" />

See the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide for information about EJB configuration for resource references.

Here is the sample code to look up the connection factory:

try
{
 Context ic = new InitialContext();
 ConnectionFactory cf = (ConnectionFactory) ic.lookup("java:comp/env/eis/myEIS");
} catch (NamingException ex) {
 ex.printStackTrace();
}

For a connection factory that implements the CCI ConnectionFactory interface, use the getConnection() method to create a connection to the EIS. This returns a connection object that implements the CCI Connection interface.

Connection conn = cf.getConnection();

Summary of the Connection Management Contract

"Introduction to How EIS Connections Are Obtained" provides a brief overview of how a connection is obtained. Now that we have covered the necessary configuration steps earlier in this chapter for connection factories and connection pooling, this section goes into more detail about the specifications of the connection management contract for obtaining a connection. We outline the steps as follows:

1. The application component performs a JNDI lookup to obtain a connection factory object. The connection factory is implemented by the resource adapter provider. If the resource adapter implements the CCI, this is through a class that implements the CCI ConnectionFactory interface. The connection factory is registered in JNDI by the OC4J administrator.

2. The application component calls a method of the connection factory to request a connection to the EIS. If the resource adapter implements the CCI, this is through a getConnection() call to a ConnectionFactory object. Additionally, in the CCI, the application can optionally pass a connection spec object in the getConnection() call, to pass in properties specific to the connection request. A connection spec is an instance of a class, typically a JavaBean, that implements the CCI ConnectionSpec interface. Connection spec properties must be defined through the getter and setter method pattern.

3. The connection factory delegates the connection request to OC4J, which maintains a connection pool. Specifically, the connection factory calls the allocateConnection() method of the OC4J connection manager, an instance of a class that implements the SPI ConnectionManager interface.

4. The OC4J connection manager obtains a connection, using the resource adapter managed connection factory as appropriate, which implements the SPI ManagedConnectionFactory interface. A physical connection to the EIS is referred to as a managed connection, represented by an instance of a class that implements the SPI ManagedConnection interface. OC4J attempts to obtain a connection as follows:

   1. First, a new logical connection can be created from a physical connection already in use if it is being used within the same transaction scope and is not marked as unshareable (by a <res-sharing-scope> subelement of a <resource-ref> element in the standard ejb-jar.xml or web.xml file).

   2. If the first scenario is not feasible, OC4J looks for an available managed connection in the connection pool. The OC4J connection manager calls the matchManagedConnection() method of the managed connection factory. If a suitable ManagedConnection object is found in the pool, then OC4J will use it to satisfy the connection request.

   3. If neither of the first two scenarios is feasible, the OC4J connection manager calls the createManagedConnection() method of the managed connection factory. This method creates a new physical connection and returns a new ManagedConnection object to OC4J to represent the physical connection. OC4J places the new managed connection in the pool and will use it to satisfy the connection request.

5. OC4J obtains an application-level connection handle from the managed connection. The handle is an instance of a class implemented by the resource adapter. If the resource adapter implements the CCI interface, then this class implements the CCI Connection interface.

6. OC4J returns the connection handle to the application.

7. The application component uses the connection handle to access the EIS (then closes the connection when through).

Additionally, OC4J registers a connection event listener—an instance of a class that implements the SPI ConnectionEventListener interface—with the ManagedConnection instance for the physical connection. OC4J accomplishes this by calling the addConnectionEventListener() method of the managed connection. The purpose of this is to allow OC4J to be notified of events related to the managed connection, which is useful in managing the connection pool.

Metrics for Resource Adapter Connections

OC4J provides performance metrics for resource adapter connection factories and connection pools, based on the Oracle Dynamic Monitoring Service (DMS) as well as on industry standard metrics specified in the Java 2 Platform, Enterprise Edition Management Specification (JSR-77). The following sections describe these metrics and how to access them:

• Viewing Resource Adapter Connection Pool Metrics

• Descriptions of Connection Pool Configuration Metrics

• Descriptions of Connection Factory Performance Metrics

• Descriptions of Connection Pool Performance Metrics

• Troubleshooting with Resource Adapter Connection Pool Metrics

(For more information about OC4J performance metrics, see the topic "Summary of the OC4J Performance Metrics" in the Application Server Control online help.)

Note: DMS adds performance-monitoring features to a number of Oracle Application Server components, including OC4J. The goal of DMS is to provide information about runtime behavior through built-in performance measurements so that users can diagnose, analyze, and debug any performance problems. DMS provides this information in a package that can be used at any time, including during live deployment. Data are published through HTTP and can be viewed with a browser. For general information about how to use DMS, the built-in DMS metrics that are available, and other OC4J performance considerations, refer to the Oracle Application Server Performance Guide.

Viewing Resource Adapter Connection Pool Metrics

You can view metrics for resource adapter connection factories and pools by taking the following steps in the Application Server Control Console:

1. From the appropriate Resource Adapter Home page, go to the Connection Factories tab.

2. For the appropriate JNDI location, corresponding to the connection factory of interest, choose the "Monitor" feature.

3. The resulting Connection Factory Metrics page displays statistics such as wait time, time of use, connection acquisition rate, and connection release rate.

Metrics listed under "General" are for the particular connection factory that you chose, corresponding to a single JNDI location. Metrics listed under "Connection Pool" are for the connection pool as a whole, which can be either private, where it is used by a single connection factory corresponding to a single JNDI location, or shared, where it is used by multiple connection factories corresponding to multiple JNDI locations.

The following metrics are available under the "General" category. See "Descriptions of Connection Factory Performance Metrics" for information.

• Connection Wait Time (seconds)

• Connection Use Time (seconds)

• Connection Acquisition Rate (per second)

• Connection Release Rate (per second)

The following metrics are available under the "Connection Pool" category. See "Descriptions of Connection Pool Performance Metrics" for more information.

• Pool Type (private or shared)

• Pool Name

• Connection Wait Time (seconds)

• Connection Use Time (seconds)

• Connection Creation Rate (per second)

• Connection Closure Rate (per second)

• Connections in Use

• Available Connections

• Waiting Threads

• Connection Error Rate (per second)

Also see the context-sensitive topic "Connection Factory Metrics Page" in the Application Server Control online help.

Descriptions of Connection Pool Configuration Metrics

As listed in Table 3-7, there are DMS metrics that correspond to connection pool configuration parameters that are described in "Configuring Connection Pooling in OC4J". XML entities in the table refer to subelements of the applicable <connection-pooling> element in the oc4j-ra.xml file.

Table 3-7 OC4J Connection Pool Configuration Metrics

DMS Metric Name (and Sensor Type)	Application Server Control Property	Corresponding XML Entity
maxPoolSize (State)	Maximum Connections	<property> with name="maxConnections"
minPoolSize (State)	Minimum Connections	<property> with name="minConnections"
scheme (State)	Connection Pooling Scheme	<property> with name="scheme"
waitTimeout (State)	Fixed Wait Timeout	<property> with name="waitTimeout"
inactivityTimeout (State)	Inactive Connection Timeout	<property> with name="inactivity-timeout"
inactivityTimeoutCheck (State)	Expired Connection Cleanup	<property> with name="inactivity-timeout-check"

Descriptions of Connection Factory Performance Metrics

Table 3-8 lists and describes OC4J DMS metrics for a connection factory and notes the corresponding metrics in the Application Server Control Connection Factory Metrics page (under "General") and in the J2EE Management Specification, as applicable. A connection factory corresponds to a single JNDI location.

These statistics are of interest regardless of whether connection pooling is used.

Table 3-8 OC4J Connection Factory Performance Metrics

DMS Metric Name (and Sensor Type)	Application Server Control Metric	J2EE Management Specification / JSR-77 Statistics (and Type)	Description
waitTime (PhaseEvent)	Connection Wait Time	JCAConnectionStats.getWaitTime() (TimeStatistics)	Average number of seconds spent waiting for a connection from this connection factory.
useTime (PhaseEvent)	Connection Use Time	JCAConnectionStats.getUseTime() (TimeStatistics)	Average number of seconds spent using a connection.
createCount (Event)	Connection Acquisition Rate	JCAConnectionStats.getCreateCount() (CountStatistics)	Number of connection handles acquired (expressed as per second in Application Server Control).
closeCount (Event)	Connection Release Rate	JCAConnectionStats.getCloseCount() (CountStatistics)	Number of connection handles released (expressed as per second in Application Server Control).

Note: When you do not use a connection pool, acquiring a connection is equivalent to creating a connection, and releasing a connection is equivalent to closing a connection. When you do use a connection pool, a single connection handle may be acquired and released multiple times between creation and closure.

Descriptions of Connection Pool Performance Metrics

Table 3-9 lists and describes OC4J DMS metrics for a connection pool, and notes the corresponding metrics in the Application Server Control Connection Factory Metrics page (under "Connection Pool") and in the J2EE Management Specification, as applicable. A connection pool may be private, in which case it corresponds to a single connection factory and JNDI location, or it may be shared, in which case it corresponds to multiple connection factories and JNDI locations.

These statistics are of interest only when connection pooling is used.

Table 3-9 OC4J Connection Pool Performance Metrics

DMS Metric Name (and Sensor Type)	Application Server Control Metric	J2EE Management Specification / JSR-77 Statistics (and Type)	Description
poolName (State)	Pool Name	n/a	Name of the connection pool.
waitTime (PhaseEvent)	Connection Wait Time	JCAConnectionPoolStats.getWaitTime() (TimeStatistics)	Average number of seconds spent waiting for a connection from this connection pool. For a shared pool, this is for all the connection factories in the pool.
useTime (PhaseEvent)	Connection Use Time	JCAConnectionPoolStats.getUseTime() (TimeStatistics)	Average number of seconds spent using a connection. For a shared pool, this is for all the connection factories in the pool.
createCount (Event)	Connection Creation Rate	JCAConnectionPoolStats.getCreateCount() (CountStatistics)	Number of connection handles created (expressed as per second in Application Server Control). For a shared pool, this is for all the connection factories in the pool.
closeCount (Event)	Connection Closure Rate	JCAConnectionPoolStats.getCloseCount() (CountStatistics)	Number of connection handles closed (expressed as per second in Application Server Control). For a shared pool, this is for all the connection factories in the pool.
freePoolSize (State)	Available Connections	JCAConnectionPoolStats.getFreePoolSize() (BoundedRangeStatistics)	Number of available connections in the pool.
poolSize (State)	None, but equivalent to Connections in Use + Available Connections	JCAConnectionPoolStats.getPoolSize() (BoundedRangeStatistics)	Size of connection pool—number of free connections plus number of connections in use.
waitingThreadCount (PhaseEvent)	Waiting Threads	JCAConnectionPoolStats.getWaitingThreadCount() (BoundedRangeStatistics)	Number of threads waiting for a connection.
expiredCount (Event)	n/a	n/a	Number of expired connections removed from the pool.
invalidCount (Event)	n/a	n/a	Number of connections determined by the resource adapter to be invalid.
requestTimeoutCount (Event)	n/a	n/a	Number of connection requests that failed due to timeout.
errorCount (Event)	Connection Error Rate	n/a	Number of connection error events (expressed as per second in Application Server Control).

Troubleshooting with Resource Adapter Connection Pool Metrics

OC4J connection metrics discussed in the preceding sections are for your use in learning the tendencies of your resource adapters and application server environment. There are no specific desired value ranges for these metrics. Over time, you will learn what ranges are normal for your environment, and what ranges may indicate trouble.

Typically, you should pay particular attention to wait times, the number of waiting threads, and the connection error rate.

Note: An additional tool for troubleshooting connections is the OC4J system property jca.connection.debug, which you can use to output diagnostic information for J2CA connections. See the Oracle Containers for J2EE Configuration and Administration Guide for general information about OC4J system properties.