posts - 56, comments - 77, trackbacks - 0, articles - 1
  BlogJava :: 首页 :: 新随笔 :: 联系 :: 聚合  :: 管理

J2EE Connector Architecture 备忘录

Posted on 2006-01-12 11:22 切尔斯基 阅读(1950) 评论(0)  编辑  收藏

I. Questions before reading the specification, and Answers after reading the specification.

1. How the application call EIS functions to execute task or get data from EIS via JCA RA/Connector?

  • This is addressed by Common Client Interface, it involves "Interaction", "InteractionSpec", "Record" and other interfaces to do this work.
  • It is a Command Design Pattern

2. and on the other hand ?

  • This is addressed by Message Inflow Contract and EJB Client View Model together. It involves a MDB to dispatch invocation to application components.

3. CCI is a protocol between Resource Adaptor and EAI tools ?

  • You can understand it as this. CCI is so low level so that it is targeted primarily towards application development tools and EAI frameworks.

4. How the ActivationSpec get associated with MDB instance ?

  • At deployment time, it is the deployer to associate ActivationSpec instance with MDB.
  • At Runtime, it is the Resource Adapter to associate ActivationSpec instance with MDB insatnce while the application server calls endpointActivation(MessageEndpointFactory, ActivationSpec)


II. Notes

1. Overview

Roles: J2EE application, J2EE AppServer, Resource Adaptor, EIS, and their provider

The target audience for this specification includes:

  • EIS vendors and resource adapter providers
  • Messaging system vendors
  • Application server vendors and container providers
  • Enterprise application developers and system integrators
  • Enterprise tool and EAI vendors

The system-level contracts between an application server and an EIS are targeted towards EIS vendors (or resource adapter providers, if the two roles are different) and application server vendors. The CCI is targeted primarily towards enterprise tools and EAI vendors.


JCA is a standard between EIS and J2EE Application Server rather than a standard between EIS and J2EE Application, for the standard defined fixed approach for any EIS plugged into any Application Server, while it allowed custom interface defined between Application and Resource Adaptor, i.e. EIS.

Reference: "This document begins by describing the rationale and goals for creating a standard architecture to integrate an application server with multiple heterogeneous EISs."

An application server and an EIS collaborate to keep all system-level mechanisms—transactions, security, and connection management—transparent from the application components.


Connector Architecture------An architecture for integrating J2EE servers with EISs. There are two parts to this architecture: an EIS vendor-provided resource adapter and an application server that allows this resource adapter to be plugged in. This architecture defines a set of contracts (such as transactions, security, connection management) that a resource adapter has to support to plug in to an application server. These contracts support bi-directional communication (outbound and inbound) between an application server and an EIS via a resource adapter. That is, the application server may use the resource adapter for outbound communication to the EIS, and it may also use the resource adapter for inbound communication from the EIS.


The "Inbound/Outbound" is refer to direction between application and resource adapter, not resource adapter and EIS.

In fact, almost all contracts are between application server and resource adapter, or between application and resource adapter, the contracts between resource adapter and EIS is private, or vendor-specified.


The resource adapter lists the types of message listener that it supports. The J2EE Connector Architecture version 1.5 and the EJB version 2.1 specifications do not restrict message listeners to using the JMS API.

That means, MDB need not be related with JMS, in fact, MDB is related with Resource Adaptor.


2. Contracts

Contract The two parties Goals
Lifecycle management contract application server and resource adapter allows an application server to manage the lifecycle of a resource adapter
Work management contract application server and resource adapter allows a resource adapter to do work (monitor network endpoints, call application components, etc.) by submitting Work instances to an application server for execution
Transaction inflow contract application server and resource adapter allows a resource adapter to propagate an imported transaction to an application server.
Message inflow contract application server and resource adapter allows a resource adapter to asynchronously deliver messages to message endpoints residing in the application server. This contract also serves as the standard message provider pluggability contract that allows a wide range of message providers to be plugged into any J2EE compatible application server via a resource adapter


3. CCI

Rather than using CCI directly, developers will use EIS specific tools which based on CCI to access EIS, such as JDBC API, JMS API

The JDBC interfaces—javax.sql.DataSource, java.sql.Connection—are examples of non-CCI connection factory and connection interfaces. Note that the methods defined on a non-CCI interface are not required to throw a ResourceException. The exception can be specific to a resource adapter, for example: java.sql.SQLException for JDBC interfaces.


Client API------The client API used by application components for EIS access may be defined as: The standard Common Client Interface (CCI)

A client API specific to the type of a resource adapter and its underlying EIS. An example of such an EIS specific client API is JDBC for relational databases. The Common Client Interface (CCI) defines a common client API for accessing EISs.
The CCI is targeted towards Enterprise Application Integration (EAI) and enterprise tools vendors.


4. Resource Adapter

The ResourceAdapter JavaBean represents a resource adapter instance and contains the configuration information pertaining to that resource adapter instance. This configuration information may also be used as global defaults for ManagedConnectionFactory and ActivationSpec JavaBeans. That is, when ManagedConnectionFactory or ActivationSpec JavaBeans are created they may inherit the global defaults (ResourceAdapter JavaBean configuration information), which make it easier to configure them. A resource adapter instance may provide bi-directional connectivity to multiple EIS instances. A ManagedConnectionFactory JavaBean can be used to provide outbound connectivity to a single EIS instance. An ActivationSpec JavaBean can be used to provide inbound connectivity from an EIS instance. A resource adapter instance may contain several such ManagedConnectionFactory and ActivationSpec JavaBeans.

from perspective of Application:

ManagedConnectionFactory : 送站通道

ActivationSpec : 接站通道

ResourceAdaptor JavaBean is not full-functional Resource Adaptor, it must combine with ManagedConnectionFactory JavaBean, ActivationSpec JavaBean and other JavaBeans to serve as a full-functional Resource Adaptor


The CCI defines javax.resource.cci.ConnectionFactory and javax.resource.cci.Connection as interfaces for a connection factory and a connection, respectively.

The connection factory instance delegates the connection creation request to the ConnectionManager instance.

The ConnectionManager instance, on receiving a connection creation request from the connection factory, does a lookup in the connection pool provided by the application server. If there is no connection in the pool that can satisfy the
connection request, the application server uses the ManagedConnectionFactory interface (implemented by the resource adapter) to create a new physical connection to the underlying EIS.

The application server registers a ConnectionEventListener with the ManagedConnection instance. This listener enables the application server to get event notifications related to the state of the ManagedConnection instance.

The application server uses the ManagedConnection instance to get a connection instance that acts as an application-level handle to the underlying physical connection. An instance of type javax.resource.cci.Connection is an example
of such a connection handle. An application component uses the connection handle to access EIS resources.

The circuitous route is for reusing application server provided services, such as transaction management, security, error logging and tracing, and connection pool management.


In the JDBC architecture, an application server provides the implementation of javax.sql.DataSource interface. Using a similar design approach for the connector architecture would have required an application server to provide implementations of various connection factory interfaces defined by different resource adapters. Since the connection factory interface may be defined as specific to an EIS, the application server may find it difficult to provide implementations of connection factory interfaces without any code generation.

The connection factory implementation class delegates the getConnection method invocation from an application component to the associated ConnectionManager instance. The ConnectionManager instance is associated with a connection factory
instance at its instantiation

Note that the connection factory implementation class must call the ConnectionManager.allocateConnection method in the same thread context in which the application component had called the getConnection method.

A resource adapter must provide a default implementation of the javax.resource.spi.ConnectionManager interface. The implementation class comes into play when a resource adapter is used in a non-managed two-tier application scenario. In an application server-managed environment, the resource adapter must not use the default ConnectionManager implementation class.


5. Transaction

The ERP system supports JTA transactions by implementing a XAResource interface through its resource adapter. The TP system also implements an XAResource interface. This interface enables the two resource managers to participate in
transactions that are coordinated by an external transaction manager. The transaction manager uses the XAResource interface to manage transactions across the two underlying resource managers.


If multiple resource managers participate in a transaction, the EJB container uses a transaction manager to coordinate the transaction. The contract between the transaction manager and resource manager is defined using the XAResource
interface. If a single resource manager instance participates in a transaction (either componentmanaged or container-managed), the container has two choices:
  • It uses the transaction manager to manage this transaction. The transaction manager uses one-phase commit-optimization to coordinate the transaction for this single resource manager instance.
  • The container lets the resource manager coordinate this transaction internally without involving an external transaction manager.


The Java Transaction API (JTA) is a specification of interfaces between a transaction manager and the other parties involved in a distributed transaction processing system: application programs, resource managers, and an application

The Java Transaction Service (JTS) API is a Java binding of the Common Object Request Broker Architecture (CORBA) Object Transaction Service (OTS) 1.1 specification. JTS provides transaction interoperability using the standard Internet
Inter-ORB Protocol (IIOP) for transaction propagation between servers. The JTS API is intended for vendors who implement transaction processing infrastructure for enterprise middleware. For example, an application server vendor can use a JTS
implementation as the underlying transaction manager.


The interface ManagedConnection defines method associateConnection as follows:

public interface javax.resource.spi.ManagedConnection {
    public void associateConnection(Object connection) throws ResourceException;

The container uses the associateConnection method to change the association of an application-level connection handle with a ManagedConnection instance. The container finds the right ManagedConnection instance, depending on the connection sharing scope, and calls the associateConnection method. To achieve this, the container needs to keep track of connection handles acquired by component instances and ManagedConnection instances using an implementation-specific mechanism.

The associateConnection method implementation for a ManagedConnection should dissociate the connection handle passed as a parameter from its currently associated ManagedConnection and associate the new connection handle with itself.

Note that the switching of connection associations must happen only for connection handles and ManagedConnection instances that correspond to the same ManagedConnectionFactory instance. The container should enforce this restriction
in an implementation-specific manner. If a container cannot enforce the restriction, the container should not use the connection association mechanism.

The resource adapter must implement the associateConnection method to support connection sharing. The container makes a decision on whether or not to use the associateConnection method implemented by a resource adapter.


6. Security

If the res-auth element is set to Application, the component code performs a programmatic sign-on to the EIS.

If the res-auth element is Container, the application server takes on the responsibility of setting up and managing EIS sign-on.


This security contract supports EIS sign-on by:
  • Passing the connection request from the resource adapter to the application server, enabling the application server to hook-in security services.
  • Propagation of the security context, that is, JAAS Subject with principal and credentials, from the application server to the resource adapter.


The application server has the following options for invoking the createManagedConnection method:

Option A: The application server invokes the createManagedConnection method by passing in a non-null Subject instance that carries a single resource principal and its corresponding password-based credentials, represented by the class PasswordCredential that provides the user name and password. The PasswordCredential should be set in the Subject instance as part of the private credential set. Note that the passed Subject can contain multiple PasswordCredential instances.
The resource adapter extracts the username and password from this Subject instance by looking for the PasswordCredential instance in the Subject, and uses this security information to sign-on to the EIS instance during connection creation.

Option B: The application server invokes the createManagedConnection method by passing in a non-null Subject instance that carries a single resource principal and its security credentials. In this option, credentials are represented through the GSSCredential interface. A typical example is a Subject instance with Kerberos credentials. For example, an application server may use this option for createManagedConnection method invocation when the resource principal is
impersonating the caller or initiating principal, and has valid credentials acquired through impersonation. An application server may also use this option for principal mapping scenarios with credentials of a resource principal represented through the GSSCredential interface. Note that sensitive credentials requiring special protection, such as private cryptographic keys, are stored within a private credential set, while credentials intended to be shared, such as public key certificates or Kerberos server tickets, are stored within a public credential set. The two methods
getPrivateCredentials and getPublicCredentials should be used accordingly. In the case of Kerberos mechanism type, the application server must pass the principal’s ticket granting ticket (TGT) to a resource adapter in a private credential set. The resource adapter uses the resource principal and its credentials from the Subject instance to go through the EIS sign-on process before creating a new connection to the EIS.

Option C: The application server invokes the createManagedConnection method by passing a null Subject instance. The application server must use this option for the component-managed sign-on case. In this option, security information is carried in the ConnectionRequestInfo instance. The application server does not provide any security information that can be used by the resource adapter for managing EIS sign-on. During the deployment of a resource adapter, the application server must be configured to use one of the above specified invocation options.


A resource adapter can do EIS sign-on and connection creation in an implementation-specific way, or it can use the GSS-API. A resource adapter has the following options, corresponding to the options for an application server, for handling the invocation of the createManagedConnection method:

Option A: The resource adapter explicitly checks whether the passed Subject instance carries a PasswordCredential instance using the Subject.getPrivateCredentials method. Note that the security contract assumes that a resource adapter has the necessary security permissions to extract a private credential set from a Subject instance. The specific mechanism through which such permission is set up is outside the scope of the connector architecture. If the Subject instance contains a PasswordCredential instance, the resource adapter extracts the username and password from the PasswordCredential. It uses the security information to authenticate the resource principal, corresponding to the username, to the EIS during the creation of a connection. In this case, the resource adapter uses an authentication mechanism that is EIS specific. Since a Subject instance can carry multiple PasswordCredential instances, a ManagedConnectionFactory should only use a PasswordCredential instance that has been specifically passed to it through the security contract. The getManagedConnectionFactory method enables a ManagedConnectionFactory instance to determine whether or not a PasswordCredential instance is to be used for sign-on to the target EIS instance. The ManagedConnectionFactory implementation uses the equals method to compare itself with the passed instance.

Option B: The resource adapter explicitly checks whether the passed Subject instance carries a GSSCredential instance using the getPrivateCredentials and getPublicCredentials methods defined in the Subject interface. In the case of Kerberos mechanism type, the resource adapter must extract Kerberos credentials using the getPrivateCredentials method in the Subject interface. The resource adapter uses the resource principal and its credentials, represented by the GSSCredential interface, in the Subject instance to go through the EIS sign-on process. For example, this option is used for Kerberos-based credentials that have been acquired by the resource principal through impersonation. A resource adapter uses the getter methods defined in the GSSCredential interface to extract information about the credential and its principal. If a resource adapter is using the GSS mechanism, the resource adapter uses a reference to the GSSCredential instance in an opaque manner and is not required to understand any mechanism-specific credential representation. However, a resource adapter may need to interpret credential representation if the resource adapter initiates authentication in an implementation-specific manner.

Option C: If the application server invokes the ManagedConnectionFactory.createManagedConnection method with a null Subject instance, a resource adapter has the following options: The resource adapter should extract security information passed through the ConnectionRequestInfo instance. The resource adapter should authenticate the resource principal by combining the configured security information on the ManagedConnectionFactory instance with the security information passed through the ConnectionRequestInfo instance. The default behavior for the resource adapter is to allow the security information in the ConnectionRequestInfo parameter to override the configured security information in the ManagedConnectionFactory instance. If the resource adapter does not find any security configuration in the ConnectionRequestInfo instance, the resource adapter uses the default security configuration in the ManagedConnectionFactory instance. If the EIS does not require authentication, the resource adapter does not need any security information from the ConnectionRequestInfo instance, and hence may ignore such security information. This may happen due to a disconnect between the application and the resource adapter.


7. Activation

An ActivationSpec JavaBean instance encapsulates the configuration information needed to setup asynchronous message delivery to a message endpoint.

Each ActivationSpec can also specify a list of required properties. These required properties can be used to validate the configuration of an ActivationSpec JavaBean instance.


The message-driven bean developer provides activation configuration information in the message-driven bean deployment descriptor. This includes messaging style specific configuration details, and possibly message provider-specific details as well, which is used by the message-driven bean deployer to setup the activation.


The resource adapter provides the following information via the resource adapter deployment descriptor that is used by the endpoint deployer to setup endpoint activation:
  • List of Supported Message Listener Types
  • ActivationSpec JavaBean
  • Administered Objects


The endpoint application’s activation-config properties, specified in the endpoint deployment descriptor, should be a subset of the ActivationSpec JavaBean’s properties. There must be a one-to-one correspondence between the activation-config property names and the ActivationSpec JavaBean’s property names. This allows automatic merging of the activation-config properties with an ActivationSpec JavaBean instance during endpoint deployment. Any specified activation-config property which does not have a matching property in the ActivationSpec JavaBean should be treated as an error.


Activation Spec Value Priority Activation Spec Value Position
Highest MDB Configured Deployment Descriptor
  MDB Default Deployment Descriptor(Merged ActivationSpec Bean)
  Configured ActivationSpec Bean
Lowest Default ActivationSpec Bean


Before any messages can be delivered to a message endpoint, the message endpoint must be associated with a destination. This task is performed during application installation. Therefore, the responsibility of associating a message-driven bean with a destination lies with the application deployer. The application deployer creates an instance of the ActivationSpec JavaBean for the relevant resource adapter and associates it with the message endpoint during installation. In this way an ActivationSpec JavaBean, through its destination property, associates a message endpoint with a destination on the message provider.

A message endpoint is activated by the application server when the message endpoint application is started. During message endpoint activation, the application server passes the ActivationSpec JavaBean, and a reference to the
MessageEndpointFactory, to the resource adapter by invoking its endpointActivation method.

The resource adapter uses the information in the ActivationSpec JavaBean to interact with messaging provider and setup message delivery to the message endpoint. For a JMS message-driven bean, this might involve configuring a
message selector or a durable subscription against the destination. Once the endpointActivation method returns, the message endpoint is ready to receive messages.

The following steps describe the sequence of events that occur when a message arrives at a destination:

  1. The resource adapter detects the arrival of a message at the destination.
  2. The resource adapter invokes the createEndpoint method on the MessageEndpointFactory.
  3. The MessageEndpointFactory obtains a reference to a message endpoint. This might be an unused message endpoint obtained from a pool or, if no message endpoints are available, it can create a new message endpoint.
  4. The MessageEndpointFactory returns a proxy to this message endpoint instance to the resource adapter.
  5. The resource adapter uses the message endpoint proxy to deliver the message to the message endpoint.

Several other messaging providers exist that require similar functionality to message-driven beans within the EJB container, such as the Java API for XML Messaging (JAXM). Because of this, version 2.1 of the EJB specification expanded the definition of message-driven beans to provide support for messaging providers other than JMS providers. It does this by allowing a message-driven bean to implement an interface other than the javax.jms.MessageListener interface. The type of message listener interface that a message-driven bean implements determines its type.

The EJB specification states that, if the message listener interface supports the request-reply pattern in this manner, it is the responsibility of the EJB container to deliver the reply message to the resource adapter.


8. Work

Note that, rather than calling the MessageEndpointFactory directly, the resource adapter is likely to instantiate a Work object, and pass it to the application server via the WorkManager interface. When the doWork method of the WorkManager is called the dispatch will occur. This will allow the resource adapter to continue to process incoming messages without blocking until message-driven bean dispatch has completed.


The resource adapter can use the message inflow contract to call a message-driven bean, and use the message-driven bean to dispatch calls to session and entity beans using the EJB client view model. The EJB specification allows a request-response style message-driven bean call which could be used for synchronous RPC-style calls. The message-driven bean could be packaged either with the resource adapter or separately.


9. CCI

The CCI is designed with the following goals:
  • It is targeted primarily towards application development tools and EAI frameworks, not application component.
  • It defines a remote function-call interface that focuses on executing functions on an EIS and retrieving the results. The CCI can form a base level API for EIS access on which higher level functionality can be built.
  • Although it is simple, it has sufficient functionality and an extensible application programming model.
  • It provides an API that both leverages and is consistent with various facilities defined by the J2SE and J2EE platforms.
  • It is independent of a specific EIS. For example, it does not use data types specific to an EIS. However, the CCI can be capable of being driven by EIS-specific metadata from a repository.

An important goal for the CCI is to complement existing standard JDBC API and not to replace this API. The CCI defines a common client API that is parallel to the JDBC for EISs that are not relational databases.

An EAI or application development tool uses a metadata repository to drive CCIbased interactions with heterogeneous EISs. A repository may maintain meta information about functions, with type mapping information and data structures for the invocation parameters, existing on an EIS system.

The application development tool generates Java classes based on the meta information accessed from a metadata repository. These Java classes encapsulate CCI-based interactions and expose a simple application programming model, typically based on the JavaBeans framework, to the application developers. An application component uses the generated Java classes for EIS access.

The application programming model for a Record is as follows:

  • A component creates an instance of a generated implementation class for a custom record. The implementation class represents an EIS-specific data structure.
  • A component uses the RecordFactory interface to create an instance of the generic Record implementation class. The implementation class of a generic Record is independent of any EIS-specific data structure.

In cases of both custom and generic Records, the type mapping information is provided by a metadata repository either at development-time or runtime.


It is important to note that the properties passed through the getConnection method should be client-specific, such as username, password, and language, and not be related to the configuration of a target EIS instance, such as port number or server name. The ManagedConnectionFactory instance is configured with a complete set of properties required for the creation of a connection to an EIS instance. Configured properties on a ManagedConnectionFactory can be overridden by client-specific properties passed by an application component through the getConnection method.

An important point to note is about the relationship between ConnectionSpec and ConnectionRequestInfo. The ConnectionSpec is used at the application level and is defined under the scope of CCI while ConnectionRequestInfo is defined as part of the system contracts. Separate interfaces have been defined to ensure the separation between CCI interfaces and system contracts. ConnectionRequestInfo has no explicit dependency on CCI. Note that a resource adapter may not implement CCI but it must implement system contracts. The specification of a standard repository API and metadata format is outside the scope of the current version of the connector architecture. The mapping between CCI’s ConnectionSpec and ConnectionRequestInfo is achieved in an implementation-specific manner by a resource adapter.


10. Deployment

When a standalone resource adapter RAR is deployed, the resource adapter must be made available to all J2EE applications in the application server. When a resource adapter RAR packaged within a J2EE application EAR is deployed, the resource adapter must be made available only to the J2EE application with which it is packaged.


The deployment code retrieves the configuration properties from the XML deployment descriptor for the resource adapter. The deployment code then creates an instance of the ManagedConnectionFactory implementation class and configures the properties of the instance.

The deployment code uses the ManagedConnectionFactory instance to create a connection factory instance. The code then registers the connection factory instance in the JNDI namespace.

The following steps occur when an application component calls the method JNDI Context.lookup to lookup a connection factory instance:

  • JNDI passes control to the application server. The ObjectFactory.getObjectInstance method implemented by the application server is called.
  • The application server creates a new instance of the ManagedConnectionFactory implementation class provided by the resource adapter.
  • The application server calls setter methods on the ManagedConnectionFactory instance to set various configuration properties of this instance. These properties provide information required by the ManagedConnectionFactory instance to
    create physical connections to the underlying EIS. The application server uses an existing property set configured during the deployment of a resource adapter to set the required properties of the ManagedConnectionFactory instance.
  • After the newly created ManagedConnectionFactory instance has been configured with its properties set, the application server creates a new ConnectionManager instance.
  • The application server calls the createConnectionFactory method of the ManagedConnectionFactory instance, passing in the ConnectionManager instance from the previous step, to get a ConnectionFactory instance.
  • The application server returns the connection factory instance to the JNDI provider, so that this instance can be returned as a result of the JNDI lookup. The application component gets the ConnectionFactory instance as a result of the
    JNDI lookup.


ra.xml specify ManagedConnectionFactory-->Application Server Reflect-->associate ConnectionManager-->invoke createConnectionFactory to get cci.ConnectionFactory cccf-->client invoke cccf.getConnection-->delegate to ConnectionManager.allocateConnection-->hook service-->delegate to ManagedConnectionFactory.createConnection