Introduction

IBM ® WebSphere® Application Server V5 introduces extensions to the J2EE Connector Architecture. These extensions improve performance of the embedded relational resource adapter, which is used to access relational databases. The purpose of this article is to provide guidance for resource adapter developers who want to take advantage of these extensions when building their own resource adapters.

The article discusses two extensions: inactive connection support (smart handles) and dynamic transaction enlistment.

Back to top

Supporting smart connection handles

For shareable physical connections (ManagedConnection instances), the connection manager can allocate multiple handles for the same ManagedConnection. A servlet, EJB, or other J2EE component may cache connection handles for use across different sharing scopes, that is, in multiple transactions.

For this to occur:

• The application server must associate any unclosed connection handles that a component holds with a valid ManagedConnection before a new method is dispatched. Since the application server cannot know which, if any, of the open connections will have an interaction performed on them, then it must associate all of the cached handles. Similarly, at the end of a method marking the end of a sharing scope, the application server must disassociate all cached handles, regardless of whether any were used.
  
  
• To call the cleanup method on a ManagedConnection without having its associated handles invalidated, WebSphere Application Server needs to use a reserved ManagedConnection instance. This consumes one physical connection which could otherwise be used to perform work on the back-end resource.
  
  
• The application server needs to track information concerning the handles that each component uses for appropriate action on method boundaries.

Managing connection handles for these shared ManagedConnection instances results in significant overhead for the application server.

Therefore, to allow for association only when needed, the connection handles must be smart. WebSphere Application Server supports such smart handles by providing the associateConnection method on the ConnectionManager interface:

public void associateConnection(ManagedConnectionFactory mcf,
      javax.security.auth.Subject subj, ConnectionRequestInfo cri,
      Object connection) throws ResourceException;

WebSphere Application Server provides this method on the com.ibm.websphere.j2c.ConnectionManager interface, extending the javax.resource.spi.ConnectionManager interface. A resource adapter might call this service provider interface (SPI) method for a particular handle (or the handle itself might call it) when an application executes an interaction on a connection when the connection is in an inactive state.

The inactiveConnectionClosed method is also provided on the com.ibm.websphere.j2c.ConnectionManager interface:

			
public void inactiveConnectionClosed( Object connection )

This SPI method must be called by a resource adapter implementing smart handles whenever an inactive connection handle is closed. This is necessary because no ManagedConnection instance is associated with an inactive handle, so you cannot call the ConnectionClosed event on the associated ConnectionEventListener.

The J2EE Connector Architecture 1.0 specification provides a state diagram of an application-level connection handle. Figure 1 displays a revised state diagram with the inactive state (shaded) illustrating the new interactions between the application server and a resource adapter that implements associateConnection.

The responsibility of tracking and association of connection handles moves from the application server to the resource adapter, which can more precisely determine when a handle is to be used and requires (re)association.

Setting the value of the InactiveConnectionSupport <config-property> element in the resource adapter's XML document, ra.xml , to true tells WebSphere Application Server not to perform an aggressive connection association. Instead, the resource adapter will call the associateConnection method on the ManagedConnection. Setting this value to false results in behavior consistent with the J2EE Connector Architecture 1.0 specification.

<config-property>
      <description>Specify whether connection handles support explicit
         reactivation. (Smart Handle support).  
         Value may be "true" or "false".</description>
      <config-property-name>InactiveConnectionSupport</config-property-name>
      <config-property-type>java.lang.Boolean</config-property-type>
      <config-property-value>true</config-property-value>
</config-property>

Back to top

Supporting deferred transaction enlistment

J2EE components may, within a global transaction, obtain connections that are not necessarily going to be used within that particular transaction scope. Even if used, they might not necessarily be used transactionally. Also, the application server does not need to reassociate an unshared connection handle when crossing transaction boundaries. For each of these cases, aggressively enlisting XAResource objects (which must be done when entering a transaction scope) is potentially unnecessary. Enlisting statically at getConnection time might also prevent the single-phase commit optimization if only a single connection is used within a transaction but multiple connections are enlisted.

Since the J2EE Connector Architecture does not provide a way for an application server to know the intended use of connections, WebSphere Application Server has its own mechanism for handling deferred enlistment of connections within transaction scopes. Resource adapters can use the interactionPending connection event to notify the connection manager when a ManagedConnection is about to be used and needs to be enlisted in a (global) transaction. Any resource adapter may take advantage of this extension by calling the interactionPending method on the com.ibm.websphere.j2c.ConnectionEventListener interface:

public interface ConnectionEventListener 
      extends javax.resource.spi.ConnectionEventListener {
      public static final int INTERACTION_PENDING;  
      public abstract void 
           interactionPending(javax.resource.spi.ConnectionEvent) 
         throws javax.resource.ResourceException;
}

The INTERACTION_PENDING SPI event type is defined on the com.ibm.websphere.j2c.ConnectionEventListener interface. The other SPI event types are defined on the class javax.resource.spi.ConnectionEvent and not on an interface.

Setting the value of the TransactionResourceRegistration <config-property> element to dynamic in the ra.xml document lets WebSphere Application Server monitor the interaction pending events. Consequently, ManagedConnection instances are enlisted in their global transaction scopes only as necessary. Setting this value to static results in behavior consistent with the J2EE Connector Architecture 1.0 specification.

<config-property>
      <description>Type of transaction resource registration
           (enlistment). Valid values are either "static" 
           (immediate) or "dynamic" (deferred).</description>
      <config-property-name>TransactionResourceRegistration
           </config-property-name>
      <config-property-type>java.lang.String</config-property-type>
      <config-property-value>dynamic</config-property-value>
</config-property>

Back to top

How does WebSphere Application Server detect resource adapter capabilities?

The resource adapter deployment descriptor in the META-INF\ra.xml document describes the capabilities of a resource adapter:

<resourceadapter>

      <config-property>
         <description>Specify whether connection handles support 
              implicit reactivation. (Smart Handle support). 
              Value may be "true" or "false". </description>
         <config-property-name>InactiveConnectionSupport
              </config-property-name>
         <config-property-type>java.lang.Boolean</config-property-type>
         <config-property-value>true</config-property-value>
      </config-property>

      <config-property>
         <description>Type of transaction resource registration
              (enlistment). Valid values are either "static"
              (immediate) or "dynamic" (deferred).</description>
         <config-property-name>TransactionResourceRegistration
              </config-property-name>
         <config-property-type>java.lang.String</config-property-type>
         <config-property-value>dynamic</config-property-value>
      </config-property>

</resourceadapter>

WebSphere Application Server handles these capabilities like it would any other modifiable configuration property. The resource adapter must be able to operate in both modes for each of these extensions. Both a get and setInactiveConnectionSupport, and get and setTransactionResourceRegistration method must reside on the ManagedConnectionFactory. The resource adapter should throw an exception on an attempt to set to an invalid or unsupported state. WebSphere Application Server will log errors for these exceptions and continue running.

Back to top

How does the resource adapter detect WebSphere Application Server capabilities?

Since these WebSphere Application Server extensions are not currently part of the J2EE Connector Architecture specification, a resource adapter plugged into another J2EE-compliant application server needs to be able to revert to the specification-defined behavior. The simplest way to determine whether an application server supports these extensions is by using the instanceof operator. For example:

if ( cm instanceof com.ibm.websphere.j2c.ConnectionManager ) {
   cm.associateConnection(mcf, null, cri, cxn);
}

Of course, the resource adapter would cache a boolean flag to avoid using the instanceof operator more than necessary. The com.ibm.websphere.j2c.ConnectionManager interface introduces the associateConnection and the inactiveConnectionClosed methods.

To determine whether the application server supports dynamic enlistment, you can use the instanceof operator again on the ConnectionEventListener object:

if ( cel instanceof com.ibm.websphere.j2c.ConnectionEventListener ) {
     ConnectionEvent event = new ConnectionEvent
          ( mc, ConnectionEventListener.INTERACTION_PENDING );
     cel.interactionPending( event );
}

The com.ibm.websphere.j2c.ConnectionEventListener interface introduces the interactionPending method and the INTERACTION_PENDING event ID constant.

The lib\j2c.jar file contains both the com.ibm.websphere.j2c.ConnectionManager and the com.ibm.websphere.j2c.ConnectionEventListener interfaces.

Back to top

Conclusion

This article discussed two performance-enhancing extensions to the J2EE Connector Architecture that resource adapter developers can leverage when plugged into WebSphere Application Server V5.

The key points are:

• Smart connection handles get associated with physical connections only when needed
• Deferred transaction enlistment avoids unnecessarily enlisting XAResources

These extensions have been accepted in the next revision of the J2EE Connector Architecture specification.

Resources

• J2EE Connector Architecture Specification(s)
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Supporting smart connection handles
• Supporting deferred transaction enlistment
• How does WebSphere Application Server detect resource adapter capabilities?
• How does the resource adapter detect WebSphere Application Server capabilities?
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers