What's New in the J2EE Connector Architecture 1.5

Print-friendly Version

There are some exciting new modifications and enhancements to the latest version of the Java 2, Enterprise Edition Connector Architecture, and that's what this article is all about. Although I'll give a brief overview of the Connector Architecture, I assume you're familiar with version 1.0, especially the resource adapter. (For detailed information about version 1.0, see the specification. An overview of its resource adapter and system-level contracts can be found in a previous article).

This article is the first in a two-part series that will concentrate on the resource adapter modifications and enhancements, with special focus on the new system-level contracts, particularly the lifecycle management and work management contracts. I'll cover implementation details and specification requirements, and we'll examine some pseudo-code to see how an EIS vendor might implement the new contracts for a version 1.5-compliant resource adapter. Part Two of this series (coming soon) will concentrate on the transaction inflow and message inflow contracts.

Connector Architecture Overview

The J2EE Connector Architecture defines a standard architecture for connecting the J2EE platform to heterogeneous enterprise information systems (EIS). Under the Connector Architecture, EIS vendors no longer have to customize their product for interaction with each compliant J2EE application server. Similarly, application server vendors needn't make modifications whenever they need connectivity to yet another EIS. Instead, application server vendors implement the Connector Architecture framework only once, and EIS vendors develop one standard resource adapter based on this architecture. Under these circumstances, a compliant EIS can plug into any application server that supports the Connector Architecture, and an application server can connect to any EIS that provides a standard resource adapter. This seamless integration between compliant application servers and enterprise information systems is depicted in Figure 1.

Figure 1: System Integration between Application Servers and EISs

By developing a standard resource adapter, EIS vendors reduce both development time and cost. Also, as long as the adapter adheres to the specification, vendors have a scalable, secure, and transactional solution to the integration problem.

Resource Adapter Overview

The resource adapter plays a central role in the integration and connectivity between an EIS and an application server. It serves as the point of contact between application components, application servers, and enterprise information systems. The resource adapter, along with other components, must communicate based on well-defined contracts that are specified by the J2EE Connector Architecture. The different components and their interactions are depicted in Figure 2.

Figure 2: Connector Architecture Components and Interactions

For seamless integration with an application server, a resource adapter must abide by guidelines -- known as system-level contracts -- that are defined by the Connector Architecture. These contracts exist between the application server and an EIS, and are implemented through the resource adapter. They specify how a system external to the J2EE platform can integrate with it by supporting basic functions that are handled by the J2EE container. The most important functions are those involved with connection management, transaction management, security, message inflow, work management, and lifecycle management.

Version 1.0 Contracts

In version 1.0 of the Connector Architecture, three contracts are defined to address the functions mentioned above:

• Connection Management Contract: Lets applications connect to an EIS through the resource adapter. It also allows the application server to pool connection requests to the EIS.
• Transaction Management Contract: Allows an application to manage and perform transactional access across one-to-many EIS resource managers.
• Security Contract: Provides support for secure access to the EIS.

New Contracts in Version 1.5

In version 1.5 of the J2EE Connector Architecture, there are more contracts that a resource adapter must support, as new functionality and features made their way into the specification. A resource adapter can support these four new contracts by implementing the required interfaces defined in the specification for each contract.

• Lifecycle Management Contract: Lets the application server manage the lifecycle -- that is, the startup and shutdown functionality -- of the resource adapter.
• Work Management Contract: Allows the resource adapter to do work by submitting it to an application server for execution. Since the application server does the work for the resource adapter, the resource adapter needn't worry about thread management. Instead, the application server manages this aspect efficiently and can use thread pooling if necessary. Although the work management contract is not required (the resource adapter can choose to manage its own thread for work), it is definitely recommended.
• Transaction Inflow Contract: Allows a resource adapter to propagate an imported transaction to an application server, as well as flow-in transaction completion and crash recovery initiated by an EIS.
• Message Inflow Contract: Allows the resource adapter to synchronously or asynchronously deliver messages to endpoints in the application server, irrespective of message style, semantics, and infrastructure.

The rest of this article will focus on two of the new contracts -- lifecycle management and work management. We'll take a look at each interface and class (in relation to the two contracts), to provide a foundation for the design and implementation of a specific resource adapter within an n-tier environment. Contracts and interfaces that must be utilized for a resource adapter to be compliant with the architecture are marked as required. Code samples show how parts of the interfaces can start to be implemented.

Lifecycle Management Contract

As mentioned previously, the lifecycle management contract provides a way for an application server to manage the lifecycle of the resource adapter instance, through starting and stopping the instance. During deployment of the resource adapter or during application server startup, the application server starts the resource adapter by bootstrapping the adapter in its address space. Upon undeployment or application server shutdown, the application server shuts down the resource adapter by notifying it.

This contract's functionality is provided through lifecycle management interfaces for both the application server and the resource adapter. For a resource adapter to meet the requirements of the lifecycle management contract, it must implement the ResourceAdapter interface, and its place in the Connector Architecture is depicted in Figure 3.

Figure 3: Lifecycle Management Interfaces for Resource Adapter

ResourceAdapter

The ResourceAdapter interface allows an application server to manage the starting and stopping of the resource adapter. The interface must be implemented as a JavaBean, and the class name must be specified in the resource adapter deployment descriptor so the application server can find it and call its two required methods, start and stop.

start

The start method initializes the resource adapter instance. It is called by the application server when the resource adapter is deployed, or when the application server starts up (if the resource adapter is already deployed). The application server passes one parameter -- a BootstrapContext instance -- to the resource adapter, which exposes the facilities of the application server that the resource adapter can use. Any exception thrown by the start method indicates an error, and initialization of the resource adapter is not successful.

stop

The stop method shuts down the resource adapter instance. It is called by the application server when the application server needs to be shut down, or when the resource adapter is undeployed. Before calling the stop method, the application server must guarantee that all applications using the resource adapter are stopped. This ensures that failing to shut down the resource adapter in an orderly manner will not harm the individual applications. Any exception thrown by the stop method does not stop the application server from shutting down or the resource adapter from undeploying.

Below is a code sample that illustrates how an EIS vendor might implement this interface.

import javax.resource.spi;

public class MyEISResourceAdapter implements ResourceAdapter {

  Work job1 = new MyEISWork (...);
  try {
    appServerWorkManager.startWork (job1);
  }catch (WorkException we) {...}
}
void stop() {
 // Perform orderly shutdown of resource adapter
}

}

Work Management Contract

The work management contract allows the resource adapter to do work by submitting it to an application server for execution. The resource adapter submits work to the application server, which dispatches a thread to run the work. Although this is not a required contract, there are a variety of reasons why it is advantageous for a resource adapter to allow the application server to handle its work. An application server handles thread management efficiently, and can even forbid a resource adapter from creating its own threads. Also, when the application server handles thread management, the resource adapter becomes more portable.

This contract's functionality is provided through work management interfaces and classes for both the application server and the resource adapter. The interfaces and class that contribute to the work management contract for the resource adapter are Work, ExecutionContext, and WorkListener. WorkListener is an optional interface, and ExecutionContext is an optional class. These interfaces and class are depicted in Figure 4.

Figure 4: Work Management Interfaces and Class for Resource Adapter

For a resource adapter to meet the requirements of the work management contract, it must implement the Work interface only. Remember, however, that this is an optional contract for the resource adapter.

Work

The Work interface allows the resource adapter to create instances of work that are submitted to the application server for execution. The resource adapter creates instances of Work and then submits them to the application server's WorkManager instance, which it obtains from the BootStrapContext instance that is passed in the start method when the resource adapter is initialized. One of the application server's free threads picks up the Work instance and executes it in the optional context, ExecutionContext, passed by the resource adapter using the run method (Work extends Runnable). The application server calls the release method when it wants the resource adapter to free the thread. The release method is the only required method for the interface. The Work instance should be thread-safe, and the release method should be re-entrant. Both the run and release methods can have synchronized blocks, but cannot be declared as synchronized methods.

Below is a code block containing a sample Work implementation:

import javax.resource.spi.work;

public class MyEISWork implements Work {

   void run () {
	...
   }

void release() {

	// Do clean up necessary on resource adapter so the
	// application server thread can be released.

}
}

ExecutionContext

ExecutionContext is a class that the resource adapter can optionally use to pass an execution context to the application server along with the Work instance. If passed, the application server must use the ExecutionContext provided when executing the work. To pass a particular context to the application server, the resource adapter must populate the ExecutionContext instance with the correct information. Otherwise, the default instance, which is null, is passed to the application server.

Since ExecutionContext is not an interface that must be implemented, sample code will not be given. A concrete implementation of ExecutionContext would extend the ExecutionContext class in the specification and would provide the appropriate execution context information. To find out more about configuring the ExecutionContext, please refer to the specification.

WorkListener

WorkListener is an optional interface that allows the resource adapter to be notified regarding work the application server is doing on its behalf. The resource adapter supplies the WorkListener to the application server when it submits a Work instance. Once passed, the application server must provide updates regarding the work to the WorkListener via application server threads. The notifications the WorkListener listens for include work accepted, work rejected, work started, and work completed. It is imperative that the WorkListener implementation be thread-safe and not make any assumptions regarding the ordering of notifications it receives.

Here is a code block containing a sample WorkListener implementation:

import javax.resource.spi.work;

public class MyEISWorkListener implements WorkListener
{
void workAccepted (WorkEvent e){
}
void workRejected(WorkEvent e) {
}
void workStarted(WorkEvent e) {
}
void workCompleted(WorkEvent e) {
}
}

The adapter implementation may also extend the WorkAdapter class to avoid having to provide an implementation for all of the methods. An implementation could instead just override specific methods of interest if it extended the WorkAdapter class. For more information, see the JavaDoc on this class.

Summary

Resource adapters are an important piece of the standard integration between an EIS and an application server. Version 1.0 of the J2EE Connector Architecture revolutionized the way in which these integrations were done -- reducing the cost and time of both design and implementation, as well as creating a portable, standard solution. Version 1.5 includes powerful new enhancements in the form of new contracts, and two of them were covered in this article. The last two contracts, message inflow and transaction inflow, will be addressed in Part 2 of this series.

See Also

• Java 2 Enterprise Edition Connector Architecture Specification, Proposed Final Draft 2
• Java 2 Enterprise Edition Connector Architecture Web Page
• The Java 2, Enterprise Edition Connector Architecture's Resource Adapter 1.0 Summary by Jennifer Rodoni

About the author

Jennifer Rodoni is an engineer at Sun Microsystems, Inc. Currently, she works in the Market Development Engineering Organization and helps evangelize Java technology. She is also the author of An Introduction to the Java Connector Architecture. You can contact her at jennifer.rodoni@sun.com.