The J2EE Connector Architecture's Resource Adapter

Print-friendly Version

This paper is intended for EIS vendors and developers that want to learn more about the resource adapter component of the connector architecture before delving into the Java 2 Platform, Enterprise Edition (J2EE) Connector Architecture specification. While the connector architecture is mentioned to illustrate how the resource adapter component fits into the overall scheme, most of the paper concentrates on the resource adapter. Benefits of implementing a resource adapter, as well as implementation details and specification requirements, are discussed. Pseudo-code is given to illustrate how an EIS vendor might implement a resource adapter.

Motivation

Prior to the introduction of the J2EE Connector Architecture, the J2EE platform did not address the integration of Java-based, enterprise applications with Enterprise Information Systems (EIS). These systems include ERP, CRM, and Supply Chain Management business applications as well as database systems. If an enterprise application needed to access the information associated with an EIS, the application server, EIS, or integration vendor would have to manually customize the connectivity between the two in a vendor-specific, non-standard way. The amount of work involved in this type of integration grew as the number of enterprise information systems and application servers increased. This complex integration problem is illustrated in Figure 1 below.

Figure 1: Problem Integrating Application Servers and EISs before JCA

Now that the J2EE Connector Architecture is public, the scope of this integration problem has been greatly reduced because the architecture defines a uniform way to integrate J2EE application servers with enterprise information systems. 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 do not have to 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. An application server, which conforms to this standard, 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 2.

Figure 2: System Integration between Application Servers and EISs

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

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. A resource adapter, along with the other components, must communicate with one another based on well-defined contracts that are specified by the J2EE Connector Architecture. The different components and their interactions are depicted in Figure 3.

Figure 3: Connector Architecture Components and Interactions

To enable 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 the EIS, and are implemented through the resource adapter.

These contracts specify how a system external to the J2EE platform can integrate with it by supporting basic functions that are handled by the J2EE container. There are three major categories of these functions:

• Connection management

  The connection management contract allows applications to connect to an EIS. It also enables the application server to utilize pooling.

• Transaction management

  The transaction management contact allows an application to manage and perform transactional access across one to many EIS resource managers.

• Security

  The security contract provides support for secure access to the EIS.

Figure 4: Resource Adapter and Contracts

Each of these contracts define what the resource adapter must support to achieve connectivity and interoperability between the EIS and any compliant application server.

Resource Adapter Implementation

The J2EE Connector Architecture specification defines interfaces, which implement the three contracts summarized above. Most of these interfaces are mandatory, in that they must be implemented by the adapter, while others do not need to be implemented. These non-mandatory interfaces are provided for the developers so they can maintain a consistent programming model if they choose. Vendors can define and implement their own interfaces, with no effect, as long as methods, which are required by the architecture, are provided in an EIS-specific manner. In the end, these vendor-defined interfaces will be very similar to the provided interfaces. All of the interfaces deliver a useful and standard framework that an EIS vendor can follow to develop a resource adapter. Descriptions of each interface, in relation to the contracts, are included below to provide a foundation for the design and implementation of a specific resource adapter within an n-tier environment. Interfaces that must be utilized are marked as required. Generic code samples are provided to show how parts of the interfaces can be implemented.

Connection Management Interfaces

The connection management part of the framework illustrates the way that applications interact with an EIS. Figure 5 depicts the interfaces that contribute to the connection management contract for the resource adapter.

Figure 5: Connection Management Interfaces

• ConnectionFactory

  ConnectionFactory is an interface that allows an application component to get a connection to an EIS instance. An application establishes a connection through the getConnection method. Then, this method must ask the application server to allocate a connection through the server's ConnectionManager.allocateConnection method. The resource adapter relinquishes this responsibility to the application server since the server is in charge of pooling connections and providing other services. Any of the resource adapter's specific request information must be passed to the ConnectionManager.allocateConnection method through the ConnectionRequestInfo parameter. The method getConnection can be overloaded if the EIS requires additional functionality. Below is a code sample that illustrates how an EIS vendor might implement this interface.

  public class myEISConnectionFactory implements javax.resource.cci.ConnectionFactory { public javax.resource.cci.Connection getConnection() throws javax.resource.ResourceException { // Gets the connection to myEIS // in an EIS specific way. // This method must invoke the // application server's // ConnectionManager.allocateConnection // method. } }

  
  

  The ConnectionFactory interface does not need to be implemented. An EIS vendor can choose to support the functionality of this interface in another way as long as the getConnection method is provided by the resource adapter. The getConnection method is required because it is how an application acquires a connection to the EIS.

• Connection

  The Connection interface provides an application with connectivity to an EIS. A close method must be provided so the application component can terminate the connection to the EIS. The sample below details how this interface might be implemented.

  public class myEISConnection implements javax.resource.cci.Connection { public void close() throws javax.resource.ResourceException { // Closes the connection to myEIS // in an EIS specific way. } }

  
  

  This interface is not required by the connector architecture. The resource adapter just has to provide a Connection object with a corresponding close method to abide by this portion of the contract. The Connection object is necessary because that is how an application represents a connection to the EIS. A close method is also required because the application must have the ability to terminate the connection with the EIS.

• ConnectionRequestInfo

  ConnectionRequestInfo represents a resource adapter's request-specific data. It is passed to the application server's ConnectionManager.allocateConnection. The value null can be used if there is no data to pass. If a resource adapter chooses to implement this interface, then it must provide the equals and hashcode methods to aide the application server in connection pooling. An example of how this interface might be implemented is shown in the code sample below.

  public class myEISConnectionRequestInfo implements javax.resource.spi.ConnectionRequestInfo { // myEIS specific data structure // The structure is used to pass specific // connection information about myEIS to // the application server public boolean equals (Object other) { // The equality of the instance is // specific to myEIS. } public int hashcode () { // The implementation is specific // to myEIS. } }

  
  
• ManagedConnectionFactory

  The interface ManagedConnectionFactory either matches an existing connection to the EIS with the incoming request or creates a new physical connection to the EIS. When the application server needs to allocate a connection to the EIS, it asks the resource adapter's ManagedConnectionFactory instance to get either an existing or a new connection. The configuration of the instance is facilitated by request-specific data. This interface, along with ManagedConnection, supports connection pooling. A resource adapter must provide an implementation of this interface. The code fragments below detail how this interface can be implemented.

  public class myEISManagedConnectionFactory implements javax.resource.spi.ManagedConnectionFactory { public Object createConnectionFactory ( ConnectionManager connectionManager) throws javax.resource.ResourceException { // Creates a connection factory // instance based on the // ConnectionManager instance // from the application server. } public Object createConnectionFactory () throws javax.resource.ResourceException { // Not applicable to n-tier // environments } public ManagedConnection createManagedConnection ( javax.security.auth.Subject subject, ConnectionRequestInfo cxRequestInfo) throws javax.resource.ResourceException { // Creates a new physical connection // to myEIS in an EIS specific way. // The subject parameter is related to // the security contract and will be // described later. } public ManagedConnection matchManagedConnections ( java.util.Set connectionSet, javax.security.auth.Subject subject, ConnecionRequestInfo cxRequestInfo) throws javax.resource.ResourceException { // Determines if there is an existing // connection, from the parameter // ConnectionSet, that can be used as // the connection to myEIS. The check // is based on criteria that is // specific to myEIS. // Must return null if a match does // not exist. // The subject parameter is related to // the security contract and will // be described later. } public boolean equals (Object other) { // Used by matchManagedConnections to check // the criteria of an incoming request with // existing connections. The implementation // depends on the criteria that is specific // to myEIS. } public int hashcode () { // Used by matchManagedConnections. The // implementation is specific to myEIS. } public void setLogWriter (java.io.PrintWriter out) throws javax.resource.ResourceException { // Registers an output stream, for logging // and tracing, with the instance. // Implementation is specific to myEIS. } public java.io.PrintWriter getLogWriter () throws javax.resource.ResourceException { // Returns the log writer of the instance. // Specific to myEIS. } }

  
  
• ManagedConnection

  The ManagedConnection interface provides an application-level connection handle from the EIS to the resource adapter's ManagedConnection instance. Communication between the two occurs through listeners and event notifications. Support for error logging and tracing must be present. Metadata about this instance and the EIS can be retrieved by invoking getMetaData, which returns information encapsulated in a ManagedConnectionMetaData instance. The interface also provides methods, like cleanup, to reinitialize the instance and free resources after communication ceases. The instance does not close the connection, however. This is handled by the application server so connection pooling can be utilized. An implementation of this interface is required by the specification. Generic code below shows how this might be implemented by an EIS vendor.

  public class myEISManagedConnection implements javax.resource.spi.ManagedConnection { public Object getConnection ( javax.security.auth.Subject subject, ConnectionRequestInfo cxRequestInfo) throws javax.resource.ResourceException { // Creates an application-level handle // to myEIS in an EIS specific way. // The subject parameter is related to // the security contract and will // be described later. } public void destroy () throws javax.resource.ResourceException { // Destroys a physical connection. // Typically called by the application // server. } public void cleanup () throws javax.resource.ResourceException { // Reinitializes handles created by // instance before the handle is put // back in the pool. } public void addConnectionEventListener ( ConnectionEventListener listener) { // Registers a connection event // listener with the instance. } public void removeConnectionEventListener ( ConnectionEventListener listener) { // Removes a connection event // listener from the instance. } public ManagedConnectionMetaData getMetaData () throws javax.resource.ResourceException { // Returns metadata information for myEIS // and ManagedConnection instance. } public void setLogWriter (java.io.PrintWriter out) throws javax.resource.ResourceException { // Allows the default log writer, provided // by the factory instance, to be overridden. // Should be set to null when the connection // instance is returned to the pool. // Specific to myEIS. } public java.io.PrintWriter getLogWriter () throws javax.resource.ResourceException { // Returns the log writer. } // Additional methods related to security // contract ... }

  
  
• ManagedConnectionMetaData

  ManagedConnectionMetaData facilitates the retrieval of metadata about a ManagedConnection instance and the particular EIS. The metadata must provide the enterprise information system's product name and version, the maximum number of concurrent connections that it can support, and the username associated with the connection. To comply with the connector architecture, an implementation of this interface must be included with the resource adapter.

  public class myEISManagedConnectionMetaData implements javax.resource.spi.ManagedConnectionMetaData { public String getEISProductName () { // Returns the name of myEIS // associated with ManagedConnection. } public String getEISProductVersion () { // Returns the version of myEIS // associated with ManagedConnection. } public int getMaxConnections () { // Returns the maximum number of // connections that myEIS can support. } public String getUserName () { // Returns the username associated // with ManagedConnection. } }

  
  
• Transaction Management Interfaces

  The transaction management interfaces provide a framework that the application server uses to manage and perform transactions with the EIS for the enterprise application. An application can perform ransactional access across any number of distributed enterprise information systems. In the case of one system, transactions are internally managed by the EIS and thus are called local transactions. When diverse systems are involved, a transaction manager, external to each EIS, controls and coordinates the transaction. These transactions are referred to as JTA or XA transactions because the transactions are performed across a variety of enterprise information systems. XA transactions are defined in the Java Transaction API (JTA) specification. The resource adapter can support either local transactions, both types of transactions, or neither type of transaction.

  Since the resource adapter can choose what, if any, types of transactions to support, the transaction management interfaces that are required by the specification depend on the transaction level that the adapter chooses to support. These interfaces, as well as whether or not they must be implemented, are detailed below. Figure 6 illustrates the interfaces that comprise the transaction management contract for the resource adapter.

  Figure 6: Transaction Management Interfaces

  
  
• ManagedConnection

  In addition to providing a connection handle to an EIS, a ManagedConnection instance gives access to two interfaces: javax.transaction.xa.XAResource and javax.resource.spi.LocalTransaction. The XAResource interface facilitates the transaction between a transaction manager and a particular EIS. The LocalTransaction interface manages local transactions. Transactions are setup before the getConnection method is invoked. Connection sharing is also enabled through the associateConnection method. The transaction management components of this interface must be implemented regardless of the level of transactional support provided by the resource adapter. The implementation, however, should throw appropriate exceptions if the type of transaction is not allowed by the resource adapter. The part of the ManagedConnection implementation that refers to the transaction management contract is shown below.

  public class myEISManagedConnection implements javax.resource.spi.ManagedConnection { // Methods related to connection // contract described above ... public XAResource getXAResource () throws javax.resource.ResourceException { // Returns the XAResource instance // associated with the ManagedConnection // instance. If XA transactions are not // supported, this method should throw an // exception. // Implementation is specific to myEIS. } public LocalTransaction getLocalTransaction () throws javax.resource.ResourceException { // Returns the LocalTransaction instance // associated with the ManagedConnection // instance. If local transactions are // not supported, this method should throw // an exception. // Implementation is specific to myEIS. }

  
  
• XAResource

  The XAResource interface is a Java mapping of the XA interface, which defines the contract between any resource adapter and a transaction manager in a distributed transaction processing environment. In reference to an enterprise information system's resource adapter, this interface enables the resource manager to participate in distributed transactions that are controlled and coordinated by an external transaction manager. The transaction manager uses the XAResource instance to manage the transaction. The XAResource interface must be implemented if XA transactions are supported by the resource adapter. In this case, certain requirements, like maintaining a 1-1 relationship between the ManagedConnection and XAResource instances and implementing one-phase commit, are mandated by the specification. For more information on the XAResource interface, consult the JTA and XA specifications.

• LocalTransaction

  The LocalTransaction interface provides support for local transactions, which are managed and performed by the EIS. Information regarding the transaction is achieved through listeners and event notifications. If either local or both transactions are supported by the resource adapter, then it must supply this interface. Specific implementation details can be found in the specification.

Security Interfaces

The security contract enables secure access to the EIS from the application component. The security contract is adhered to by incorporating the J2EE Java Authentication and Authorization Service (JAAS) into the connection management interfaces. The interfaces from JAAS that are used in a resource adapter are described below.

• Subject

  A Subject represents a grouping of related information for a single entity, such as a person. It includes identities, each known as a Principal, and security-related attributes, which are called Credentials. The subject is passed to the resource adapter by the application server for authentication and authorization.

• Principal

  As mentioned above, a Principal represents an identity.

• Generic Credential

  The GenericCredential interface defines a way to access the security credentials of a Principal. With this interface, the resource adapter is able to retrieve the credentials passed from the application server.

In addition to the security interfaces from JAAS, the security contract includes the final class PasswordCredential to help facilitate secure communication between the application server and the EIS.

• Password Credential

  The PasswordCredential class encapsulates a username and password, which is passed from the application server to the resource adapter. Besides providing get methods that retrieve the values of the username and password, this class also defines get/setManagedConnectionFactory methods, which get or set the managed connection factory instance for which the username and password has been set up by the application server.

The JAAS interfaces and the PasswordCredential class are incorporated into the connection interfaces to provide the security contract for the resource adapter. The three connection interfaces that must be modified to implement the security contract are ConnectionFactory, ManagedConnectionFactory and ManagedConnection. The modifications depend on what component is in charge of the logon process. The additions to these interfaces are described below.

• ConnectionFactory

  Security services from the application server are enabled by the resource adapter when the ConnectionFactory instance asks the application server to allocate a connection through the ConnectionManager.allocateConnection method. Depending on whether the application server or the application component manages the logon to the EIS, the resource adapter calls this method differently.

  • If the application server is in charge of logging on to the EIS, then the application component does not pass any security information to the resource adapter in the getConnection method. Since the resource adapter does not have this info, it does not forward any security information to the server.
    
    
  • If the application component is in charge of the logon to the EIS, however, it provides the necessary security information to the resource adapter through the getConnection method. Then, the resource adapter will handle the logon process through the ManagedConnectionFactory instance.
    
    
• ManagedConnectionFactory

  The ManagedConnectionFactory interface of the connection contract must be modified to support the security contract via the createManagedConnection method. The necessary modifications depend on whether the application server or the resource manager facilitates the logon to the EIS.

  • If the application server is in charge of this process, then it invokes createManagedConnection with the appropriate security information. This security data can be passed in a variety of ways established by JAAS. The instance retrieves the security information and then uses it to logon to the EIS.
    
    
  • If the resource adapter is in charge of the logon process, then the application server passes a null security parameter to the createManagedConnection method. In this case, the resource adapter looks for security information in the ContextRequestInfo instance. If it finds what it is looking for, then this information is used to connect to the EIS. Otherwise, the resource adapter uses the default security of the ManagedConnectionFactory instance.

  The resource adapter must implement createManagedConnection to support the security contract. A generic implementation is provided below.

  public class myEISManagedConnectionFactory implements javax.resource.spi.ManagedConnectionFactory { // Other methods related to connection and // transaction contracts ... public ManagedConnection createManagedConnection ( javax.security.auth.Subject subject, ConnectionRequestInfo cxRequestInfo) throws javax.resource.ResourceException { // Creates a physical connection to myEIS // using the security information in the // parameter subject. // The resource adapter must decipher how // the security information is passed // from the application server so that it // can retrieve the necessary data. If // the security information is null, then // the resource manager must find it // elsewhere. // The connection and logon details are // specific to myEIS. } }

  
  
• ManagedConnection

  If the resource adapter supports reauthentication, then the ManagedConnection interface must be changed to support this functionality. This capability is tied into the getConnection method. Reauthentication is not required by the security contract, but a generic implementation is described below.

  public class myEISManagedConnection implements javax.resource.spi.ManagedConnection { // Other methods related to connection // and transaction contracts public Object getConnection ( javax.security.auth.Subject subject, ConnecionRequestInfo cxRequestInfo) throws javax.resource.ResourceException { // Reauthenticates the connection to // myEIS using the security information // provided. // Connection details are specific to myEIS. } }

  
  

Summary

Resource adapters are important and beneficial in the standard integration of an EIS with an application server. Since resource adapters provide a way for an EIS to seamlessly plug into any application server, the complex integration problem that once existed has been simplified and standardized. The cost of the design and implementation of this integration for the EIS vendor has been greatly reduced. Plus, the resource adapter interfaces help the vendor produce a scalable, secure and transactional resource adapter.

References

J2EE Connector Architecture Specification

Java Authorization and Authentication Service

Java Transaction API