Introduction to Java Connector Architecture

Introduction to Java Connector Architecture

By Paul Jensen, OCI Principal Software Engineer

May 2002

Introduction

As a required element of the Java 2 Enterprise Edition (J2EE), the Java Connector Architecture (JCA) provides a standardized means to integrate with Enterprise Integration Systems (EIS).

Such systems include:

• Enterprise Resource Planning Systems – SAP, PeopleSoft, Baan
• Transaction Monitors – CICS, Tuxedo
• Database Management Systems – Oracle, Sybase

Prior to the introduction of JCA, each EIS provided a proprietary solution for EIS/J2EE integration. This proved problematic in that each EIS driver required custom integration with each application server, restricting portability and increasing overall vendor effort.

With the advent of JCA, drivers may be written to standard J2EE application server contracts, providing integration of transactions, security, and resource pooling.

In addition, JCA defines optional client contracts to standardize access to record-based systems. These contracts, similar in nature to the JDBC APIs, may be utilized by J2EE components.

Resource Adapters

A JCA Resource Adapter serves as a software driver for an EI system.

Resource Adapters may be utilized in a standalone manner (an unmanaged environment) or in a J2EE application server (a managed environment). The architecture of the managed environment is illustrated in Figure 1.

Figure 1

As shown, the Resource Adapter supports 3 types of contract:

• EIS – specific to the EIS vendor (typically proprietary)
• Application – EIS-specific
• System – integration with the J2EE application server

The EIS contract is outside the purview of the JCA specification and will not be further discussed here.

Application contracts are utilized by EJB components to access EIS functionality. The associated APIs may be based on interfaces defined in the JCA specification (collectively referred to as the Common Client Interface), but this is not mandated in the current version of JCA.

System contracts allow integration with the general services of a J2EE application server, namely transactions, security, and connection pooling. These are primarily of interest to Resource Adapter developers, but an understanding of their capabilities is useful to those deploying adapters as well.

Common Client Interface (CCI)

The JCA Common Client Interface (CCI) is a set of interfaces providing a framework for basic interaction with a Resource Adapter. An adapter that supports CCI will provide concrete classes that implement these interfaces.

The design and usage of CCI closely resembles that of JDBC.

The table below outlines the basic functions of JDBC and CCI and maps them to the respective interfaces of each API.

While the similarity to JDBC is obvious, some CCI interfaces are worthy of further mention.

Several "Spec" interfaces are defined by CCI. These interfaces may be implemented by JavaBean-compliant vendor classes, providing users the ability pass information to either ConnectionFactory.getConnection() or Interaction.execute().

Some common properties are defined for the Spec classes. For example, ConnectionSpec utilizes the standard properties UserName and Password to allow passing of authentication information in situations where it is not container managed.

InteractionSpec is used to define the function to invoke on the underlying EIS and to configure various behaviors such as FetchSize, ResultSetConcurrency, etc.

The InteractionVerb property defines the synchronous action taken by the method invocation. This property defaults to SYNC_SEND_RECEIVE (send request and await response), but it is also possible to send a request without awaiting a response (SYNC_SEND) and to retrieve data subsequently retrieved by the adapter (SYNC_RECEIVE).

Significantly, the CCI does not support asynchronous delivery of messages to J2EE components. Java Message Service (JMS) and Message-Driven Enterprise JavaBeans (EJBs) may fill this void in future versions of the specification.

The InteractionSpec instance is passed to Interaction.execute() along with two Record objects, respectively containing all input and output parameters for the defined function. JCA defines three Record subtypes based on a HashMap, List, and the JDBC ResultSet. Vendores may define others. 

Record instances may be created via a RecordFactory or constructed directly, depending on the vendor implementation.

CCI Usage Example

The following code example (based on IBM's CICS Connector) demonstrates use of a CCI-compliant Resource Adapter in a managed environment.

InitialContext ctx = new InitialContext();
ConnectionFactory cxf = 
    (ConnectionFactory)ctx.lookup("java:comp/env/jca/myConnector");
 
// create a connection object
Connection connection = cxf.getConnection();
 
// create an interaction with CICS to start transaction
Interaction interaction = connection.createInteraction();
 
// Implements InteractionSpec
EPIInteractionSpec iSpec = new EPIInteractionSpec();
// well-known property
iSpec.setFunctionName("EPIP");
// vendor-specific property    
iSpec.setAID(AIDKey.enter);
// default
iSpec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);  
 
// Create a record to store the response from CICS - implements Record
// Can create records in this way or through RecordFactory implementations
// obtained via ConnectionFactory.getRecordFactory()
EPIScreenRecord screen = new EPIScreenRecordImpl();
 
// execute w/ InteractionSpec, InputRecord, OutputRecord
boolean rc = interaction.execute(iSpec, null, screen);
 
// close the interaction and connection
interaction.close();
connection.close();

Note that this example is based on CCI support. While CCI support will likely be mandated in a future version of JCA, it is currently optional, and vendors are free to provide a totally unrelated set of interfaces (although this seems unlikely moving forward).

Server Contracts

The server contracts detail JCA-J2EE interactions to support integration of connection pooling, security identity propagation, and transaction control.

Introduction of standardized APIs for low-level integration is the basis for Resource Adapter portability and the primary focus of the current JCA specification. These new standards will open the door for new levels of EIS integration, as well as providing new options for the J2EE developer.

Connection Pooling

The connection pooling contract distinguishes connections handles (obtained and utilized by J2EE components) and managed connections (those managed by the Resource Adapter).

The Resource Adapter jar file (distinguished with a .rar extension) contains ConnectionFactory and Connection interfaces and implementations to support connection handles, as well as ManagedConnectionFactory and ManagedConnection classes to support managed connections.

These classes and an application-server provided ConnectionManager form the basis of the connection management contract.

Figure 2 illustrates the interactions related to a J2EE component obtaining a connection to a Resource Adapter.

The application-visible ConnectionFactory delegates its getConnection() request to the application server, which then seeks a managed connection matching a number of criteria (such as component-defined sharing scope and caller identity).

It is important to note that in the managed (J2EE) scenario, the adapter does not actually manage a pool of connections; it either provides a connection matching the given criteria from a list of connections provided by the application server (matchManagedConnection()), or it creates a new managed connection based on a separate application server request (createManagedConnection()).

Through registration of a ConnectionListener with the adapter, the application server receives notifications sufficient to manage connection pooling.

Figure 2

Transaction Management

The transaction management contracts define two types of transactions in which adapter activities may participate: distributed and local.

Distributed transactions (also referred to as XA or JCA transactions) may involve multiple resources and are managed by a centralized coordinator, which ensures a consistent outcome through a 2-phase commit (2PC) protocol.

Local transactions are limited in scope to a single resource.

A given Resource Adapter may support both distributed or local transactions or provide no transaction support. The application server determines the level of support via the adapter's deployment descriptor contained in the .rar file.

The connector architecture defines a transaction contract between an application server, a resource adapter, and the underlying resource manager. Clients may control the transaction explicitly utilizing the Java Transaction API, or they can utilize declarative, container-managed transactions.

The declarative approach is generally preferred to allow the container to implicitly enroll multiple components and Resource Adapters in a transaction.

In the case of an XA transaction, each Resource Adapter accessed by components is registered with the XA transaction coordinator, which subsequently includes them in the eventual 2PC.

Security Integration

The connector architecture also includes support for mapping of J2EE security identities (principals) to identities meaningful to an EIS adapter.

While it is possible to explicitly pass security information from the component when requesting a Connection, Resource Adapters will typically be configured to utilize authentication information passed implicitly by the application server. This is accomplished through a combination of component configuration (defining Container-based authentication) and adapter configuration (defining the specifics of principal mapping and credential format).

The security contract utilizes instances of the Java Authentication and Authorization Service (JAAS) javax.security.auth.Subject to pass authentication information to the adapter. The adapter deployment descriptor defines the format of the credential information contained in the Subject instance.

The specification specifically defines basic password and Kerberos credentials as valid options, but JCA provides sufficient flexibility to support additional types of credentials.

Future Direction

The next version of JCA offers some valuable enhancements to the architecture.

As mentioned, the current version does not specify standards for handling asynchronous notifications from the EIS. While several vendors provide proprietary support for such capability, the next version is expected to provide a standardized approach.

Definition of an XML-based metadata repository is also anticipated. Such a repository could prove useful in scripting, Web Service integration, and potential entity bean container-managed persistence support.

Other related improvements include JMS-JCA integration, mandatory CCI support, and CCI XML usage.

Summary

Currently, JCA implementations are available for all major Enterprise Integration Systems from a variety of vendors (see the JavaSoft site for a full list). Additionally, as a required part of J2EE 1.3, application-server support is widespread.

While JCA is relatively new, its introduction brightens the future of J2EE-EIS integration and provides a new tool for implementers of J2EE systems.

References

• [1] Java Authentication and Authorization Service, version 1.0
  http://java.sun.com/products/jaas/
• [2] Java Connector Architecture
  http://java.sun.com/j2ee/connector/index.html
• [3] Java Transaction API (JTA) specification, version 1.x
  http://java.sun.com/products/jta/
• [4] Generic Security Service API (GSS-API) specification, version 2
  http://www.ietf.org/rfc/rfc2078.txt
• [5] X/Open CAE Specification - Distributed Transaction Processing: the XA specification, X/Open document
  http://www.opengroup.org/pubs/catalog/c193.htm