A Jakarta EE application component uses a public interface called a connection factory to access a connection instance, which the component then uses to connect to the underlying EIS. Examples of connections include database connections and JMS (Jakarta Message Service) connections.

A resource adapter provides connection and connection factory interfaces, acting as a connection factory for EIS connections. For example, the javax.sql.DataSource and java.sql.Connection interfaces are JDBC-based interfaces for connecting to a relational database.

An application looks up a connection factory instance in the Java Naming and Directory Interface (JNDI) namespace and uses it to obtain EIS connections. See Obtaining the ConnectionFactory (Client-JNDI Interaction).

Version 1.5 and 1.6 resource adapters can be bound in the JNDI tree as independent objects, making them available as system resources in their own right or as message sources for message-driven beans (MDBs). In contrast, version 1.0 resource adapters are identified by their ConnectionFactory objects bound in the JNDI tree.

In a version 1.5 or 1.6 resource adapter, at deployment time, the ResourceAdapter Bean (if it exists) is bound into the JNDI tree using the value of the Example A- element, shown in the weblogic-ra.xml file. As a result, administrators can view resource adapters as single deployable entities, and they can interact with resource adapter capabilities publicly exposed by the resource adapter provider. For more information, see Example A- in weblogic-ra.xml Schema.

The application assembler or component provider configures the Connection Factory requirements for an application component in the application's deployment descriptor. For example:

res-ref-name: eis/myEIS
res-type: javax.resource.cci.ConnectionFactory
res-auth: Application or Container

The resource adapter deployer provides the configuration information for the resource adapter.

An application looks up a ConnectionFactory instance in the Java Naming and Directory Interface (JNDI) namespace and uses it to obtain EIS connections. The following events occur when an application in a managed environment obtains a connection to an EIS instance from a Connection Factory, as specified in the res-type variable.

1. The application server uses a configured resource adapter to create physical connections to the underlying EIS.

2. The application component looks up a ConnectionFactory instance in the component's environment by using the JNDI interface, as shown in Example 5-1.

3. The application component uses the returned connection to access the underlying EIS.

4. The application component invokes the getConnection method on the ConnectionFactory to obtain an EIS connection. The returned connection instance represents an application level handle to an underlying physical connection. An application component obtains multiple connections by calling the method getConnection on the connection factory multiple times:

   javax.resource.cci.Connection cx = cxf.getConnection();
   

5. After the component finishes with the connection, it closes the connection using the close method on the Connection interface:

   cx.close();
   

   If an application component fails to close an allocated connection after its use, that connection is considered an unused connection. The application server manages the cleanup of unused connections.

//obtain the initial JNDI Naming context
Context initctx = new InitialContext();

// perform JNDI lookup to obtain the connection factory
javax.resource.cci.ConnectionFactory cxf = 
    (javax.resource.cci.ConnectionFactory)
        initctx.lookup("java:comp/env/eis/MyEIS");

Section 7.13 of JSR 322: Java EE Connector Architecture 1.6 specifies that a resource adapter may determine and classify the level of transaction support it can provide at run time. To have the ability to specify the level of transaction support, a resource adapter's ManagedConnectionFactory class must implement the TransactionSupport interface. If this interface is not implemented, the Connector container uses the transaction support specified in the merged result of the resource adapter's ra.xml file and Connector annotations.

JSR 322: Java EE Connector Architecture 1.6 also defines the rules and priorities on the transaction support level determined from the ra.xml file, Connector annotation, and the TransactionSupport interface.

WebLogic Server supplements support for obtaining transaction support level by exposing the following two methods on the ConnectorConnectionPoolRuntimeMBean:

• ConnectorConnectionPoolRuntimeMBean.getRuntimeTransactionSupport() — Return the real transaction support level in use for this Connector connection pool.

  This value may also be viewed in the WebLogic Remote Console.

• ConnectorConnectionPoolRuntimeMBean.getTransactionSupport() — Returns the static transaction support level, which is configured either in ra.xml or using the @Connector annotation, for the resource adapter for this Connector connection pool.

In most cases, an adapter's ManagedConnectionFactory supports connection sharing, as defined in section 7.9 of JSR 322: Java EE Connector Architecture 1.6. The specification also says that a connection can be made unshareable by setting res-sharing-scope to Unshareable in the caller application's deployment descriptor or annotation.

However, it can be inconvenient to define an unshareable resource reference in the caller application. For example, the caller application may perform a look up to a ConnectionFactory pool from WebLogic's global JNDI directly, but the application does not define unshareable resource references to this pool. WebLogic Server treats such use of the pools as shareable by default. As a result, if an adapter does not support connection sharing, the adapter will not work.

To circumvent this problem, WebLogic Server supports the public annotation weblogic.connector.extensions.Unshareable. This annotation can be used on a ManagedConnectionFactory class if the ManagedConnectionFactory does not support sharing. When such an adapter is deployed, WebLogic Server checks the ManagedConnectionFactory class and treats the ManagedConnectionFactory and related pools as unshareable. If you configure a sharable resource reference to this unshareable pool in a Web application or an Jakarta Enterprise Beans, WebLogic Server issues a warning message—but the Web application or the EJB nevertheless treats the pool as unshareable. There is no need to configure anything in weblogic-ra.xml or in the WebLogic Remote Console.

If a ManagedConnectionFactory is shareable, nothing needs to be changed in the adapter's code. All ManagedConnectionFactory instances and pools are considered shareable by default, unless the ManagedConnectionFactory contains an Unshareable annotation.

You use the outbound-resource-adapter element and its subelements in the weblogic-ra.xml deployment descriptor to describe the outbound components of a resource adapter.

You can define outbound connection pools at three levels:

• Global - Specify parameters that apply to all outbound connection groups in the resource adapter using the default-connection-properties element. See default-connection-properties.

• Group - Specify parameters that apply to all outbound connection instances belonging to a particular connection factory specified in the ra.xml deployment descriptor using the connection-definition-group element. A one-to-one correspondence exists from a connection factory in ra.xml to a connection definition group in weblogic-ra.xml. The properties specified in a group override any parameters specified at the global level. See connection-definition-group.

  The connection-factory-interface element (a subelement of the connection-definition-group element) serves as a required unique element (a key) to each connection-definition-group. There must be a one-to-one relationship between the connection-definition-interface element in weblogic-ra.xml and the connectiondefinition-interface element in ra.xml.

• Instance - Under each connection definition group, you can specify connection instances using the connection-instance element of the weblogic-ra.xml deployment descriptor. These correspond to the individual connection pools for the resource adapter. You can use the connection-properties subelement to specify properties at the instance level too; properties specified at the instance level override those provided at the group and global levels. See connection-instance.

If an application component attempts to obtain a connection instance from a connection pool using the getConnection() method on the ConnectionFactory, but the pool is temporarily suspended, WebLogic Server generates an exception that implements javax.resource.spi.RetryableException. The application component can use an instance of RetryableException to determine whether the connection failure is transient.

By default, if a resource adapter has multiple outbound connection pools, a failure in any one connection pool causes the entire deployment of the resource adapter to fail. However, the deploy-as-a-whole deployment option is available, which you can set to isolate individual outbound connection pool failures from the resource adapter deployment. Using this deployment option enables you to use the adapter health monitoring feature to identify connection pool failures, which you can troubleshoot and repair without the need to redeploy the resource adapter.

For general information about the resource adapter health monitoring features, see Monitoring Resource Adapter Health. For information about setting the deploy-as-a-whole element in the weblogic-ra.xml file, see the following topics:

• deploy-as-a-whole: Isolating Outbound Connection Pool Failures from the Whole Adapter Deployment

• Deploying a Resource Adapter Configured with Multiple Outbound Connection Pools

The following sections explain how to use the deploy-as-a-whole deployment option and how to diagnose and recover from outbound connection pool failures:

• Using the Deploy-As-A-Whole Option
  
• Troubleshooting Failed Connection Pools
  
• Connection Pool Recovery Steps
  
• Other Options for Recovering Failed Connection Pools
  

Example 5-2 is an example of a weblogic-ra.xml deployment descriptor that configures multiple outbound connections:

<?xml version="1.0" ?> 
<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">
<jndi-name>900eisaNameOfBlackBoxXATx</jndi-name>
   <outbound-resource-adapter> 
      <connection-definition-group>
         <connection-factory-interface>javax.sql.DataSource
         </connection-factory-interface> 
            <connection-instance>
               <jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME1
               </jndi-name>
               <connection-properties>
                  <pool-params> 
                     <initial-capacity>2</initial-capacity> 
                     <max-capacity>10</max-capacity> 
                     <capacity-increment>1</capacity-increment>
                     <shrinking-enabled>true</shrinking-enabled>
                     <shrink-frequency-seconds>60</shrink-frequency-seconds>
                  </pool-params>
                  <properties> 
                     <property> 
                        <name>ConnectionURL</name>
                        <value>
                  jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
                        </value> 
                     </property> 
                     <property>
                        <name>XADataSourceName</name> 
                        <value>OracleXAPool</value> 
                     </property> 
                     <property> 
                        <name>TestClassPath</name> 
                        <value>HelloFromsetTestClassPathGoodDay</value> 
                     </property> 
                     <property> 
                        <name>unique_ra_id</name> 
                        <value>eisablackbox-xa.oracle.900</value> 
                     </property> 
                  </properties> 
               </connection-properties> 
            </connection-instance> 
            <connection-instance>
                  <jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME2
                  </jndi-name>
                  <connection-properties> 
                     <pool-params> 
                        <initial-capacity>2</initial-capacity> 
                        <max-capacity>10</max-capacity> 
                        <capacity-increment>1</capacity-increment>
                        <shrinking-enabled>true</shrinking-enabled>
                        <shrink-frequency-seconds>60
                        </shrink-frequency-seconds>
                     </pool-params>
                  <properties>
                     <property>
                        <name>ConnectionURL</name>
                        <value>
                  jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
                        </value>
                     </property>
                     <property> 
                        <name>XADataSourceName</name> 
                        <value>OracleXAPool</value> 
                     </property> 
                     <property> 
                        <name>TestClassPath</name> 
                        <value>HelloFromsetTestClassPathGoodDay</value> 
                     </property> 
                     <property> 
                        <name>unique_ra_id</name> 
                        <value>eisablackbox-xa.oracle.900</value> 
                     </property> 
                  </properties> 
               </connection-properties> 
            </connection-instance> 
      </connection-definition-group> 
     <connection-definition-group>
         <connection-factory-interface>javax.sql.DataSourceCopy
         </connection-factory-interface> 
         <connection-instance>
            <jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME3</jndi-name>
            <connection-properties> 
                  <pool-params>
                        <initial-capacity>2</initial-capacity>
                        <max-capacity>10</max-capacity>
                        <capacity-increment>1</capacity-increment>
                        <shrinking-enabled>true</shrinking-enabled>
                        <shrink-frequency-seconds>60</shrink-frequency-seconds>
                  </pool-params>
                  <properties>
                     <property>
                        <name>ConnectionURL</name>
                        <value>jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false</value>
                     </property>
                     <property>
                        <name>XADataSourceName</name>
                        <value>OracleXAPoolB</value>
                     </property>
                     <property>
                        <name>TestClassPath</name>
                        <value>HelloFromsetTestClassPathGoodDay</value>
                     </property>
                     <property>
                        <name>unique_ra_id</name>
                        <value>eisablackbox-xa-two.oracle.900</value>
                     </property>
                  </properties>
               </connection-properties>
         </connection-instance>
     </connection-definition-group>
   </outbound-resource-adapter>
</weblogic-connector>

Depending on the complexity of the Enterprise Information System (EIS) that the ManagedConnection is representing, creating ManagedConnections can be expensive. You may decide to populate the connection pool with an initial number of ManagedConnections upon startup of WebLogic Server and therefore avoid creating them at run time. You can configure this setting using the initial-capacity element in the weblogic-ra.xml descriptor file. The default value for this element is 1 ManagedConnection.

Because no initiating security principal or request context information is known at WebLogic Server startup, a server instance creates initial connections using a security subject by looking up special credential mappings for the initial connection. See Initial Connection: Requires a ManagedConnection from Adapter Without Application's Request.

As more ManagedConnections are created, they consume more system resources - such as memory and disk space. Depending on the Enterprise Information System (EIS), this consumption may affect the performance of the overall system. To control the effects of ManagedConnections on system resources, you can specify a maximum number of allocated ManagedConnections in the max-capacity element of the weblogic-ra.xml descriptor file.

If a new ManagedConnection (or more than one ManagedConnection in the case of capacity-increment being greater than one) needs to be created during a connection request, WebLogic Server ensures that no more than the maximum number of allowed ManagedConnections are created. Requests for newly allocated ManagedConnections beyond this limit results in a ResourceAllocationException being returned to the caller.

In compliance with Connector Architecture 1.6, when an application component requests a connection to an EIS through the resource adapter, WebLogic Server first tries to match the type of connection being requested with an existing and available ManagedConnection in the connection pool. However, if a match is not found, a new ManagedConnection may be created to satisfy the connection request.

Using the capacity-increment element in the weblogic-ra.xml descriptor file, you can specify a number of additional ManagedConnections to be created automatically when a match is not found. This feature provides give you the flexibility to control connection pool growth over time and the performance hit on the server each time this growth occurs.

Although setting the maximum number of ManagedConnections prevents the server from becoming overloaded by more allocated ManagedConnections than it can handle, it does not control the efficient amount of system resources needed at any given time. WebLogic Server provides a service that monitors the activity of ManagedConnections in the connection pool of a resource adapter. If the usage decreases and remains at this level over a period of time, the size of the connection pool is reduced to the initial capacity or as close to this as possible to adequately satisfy ongoing connection requests.

This system resource usage service is turned on by default. However, to turn off this service, you can set the shrinking-enabled element in the weblogic-ra.xml descriptor file to false.

Use the shrink-frequency-seconds element in the weblogic-ra.xml descriptor file to identify the amount of time (in seconds) the Connection Pool Manager will wait between attempts to reclaim unused ManagedConnections. The default value of this element is 900 seconds.

If the maximum number of connections has been reached and there are no available connections, WebLogic Server retries until the call times out. The highest-num-waiters element controls the number of clients that can be waiting at any given time for a connection.

When a connection is created and fails, the connection is placed on an unavailable list. WebLogic Server attempts to recreate failed connections on the unavailable list. The highest-num-unavailable element controls the number of unavailable connections that can exist on the unavailable list at one time.

To configure WebLogic Server to attempt to recreate a connection that fails while creating additional ManagedConnections, enable the connection-creation-retry-frequency-seconds element. By default, this feature is disabled.

A connection request contains parameter information. By default, the connector container calls the matchManagedConnections() method on the ManagedConnectionFactory to match the available connection in the pool to the parameters in the request. The connection that is successfully matched is returned.

It may be that the ManagedConnectionFactory does not support the call to matchManagedConnections(). If so, the matchManagedConnections() method call throws a javax.resource.NotSupportedException. If the exception is caught, the connector container automatically stops calling the matchManagedConnections() method on the ManagedConnectionFactory.

You can set the match-connections-supported element to specify whether the resource adapter supports connection matching. By default, this element is set to true and the matchManagedConnections() method is called at least once. If it is set to false, the method call is never made.

If connection matching is not supported, a new resource is created and returned if the maximum number of resources has not been reached; otherwise, the oldest unavailable resource is refreshed and returned.

The test-frequency-seconds element allows you to specify how frequently (in seconds) connections in the pool are tested for viability.

You can set the test-connections-on-create element to enable the testing of connections as they are created. The default value is false.

You can set the test-connections-on-release element to enable the testing of connections as they are released back into the connection pool. The default value is false.

You can set the test-connections-on-reserve element to enable the testing of connections as they are reserved from the connection pool. The default value is false.

You can set the deploy-as-a-whole element to determine whether or not the deployment of a resource adapter, which contains multiple outbound connection pools, should fail if a failure occurs in any connection pool. The default value is true, which causes the whole resource adapter deployment to fail if any error occurs (not just with connection pools).

Setting this element to false enables the resource adapter deployment to succeed as long as at least one outbound connection pool remains healthy, allowing you isolate, diagnose, repair, and dynamically update the resource adapter without the need to redeploy it.

1. Rather than having MyConnection be a class that implements the resource adapter's Connection interface, modify MyConnection to be an interface that extends Connection.
2. Implement a MyConnectionImpl class that implements the MyConnection interface.

If you know for sure whether or not a connection proxy can be used in the resource adapter, you can avoid a proxy test by explicitly setting the use-connection-proxies element in the WebLogic Server 8.1 version of weblogic-ra.xml to true or false.

If set to true, the proxy test is not performed and connection properties are generated.

If set to false, the proxy test is not performed and connection proxies are generated.

If use-connection-proxies is unspecified, the proxy test is performed and proxies are generated if the test passes. (The test passes if a ClassCastException is not thrown by the resource adapter).

The following optional elements in the weblogic-ra.xml deployment descriptor allow you to control the testing of connections in the pool.

• test-frequency-seconds - The connector container periodically tests all the free connections in the pool. Use this element to specify the frequency with which the connections are tested. The default is 0, which means the connections will not be tested.

• test-connections-on-create - Determines whether the connection should be tested upon its creation. By default it is false.

• test-connections-on-release - Determines whether the connection should be tested upon its release. By default it is false.

• test-connections-on-reserve - Determines whether the connection should be tested upon its reservation. By default it is false.