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.

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.

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.

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

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.

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.

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 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.

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.

• 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 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.

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.

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

• 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.

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.

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.

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.

• List of Supported Message Listener Types
• ActivationSpec JavaBean
• Administered Objects

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.

• 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.

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.

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.