Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

J2EE Connector Architecture

by Anthony Lai, Jyotsna Laxminarayanan and Lars Ewe

Have you ever found yourself in a position where you had to integrate legacy data, data sources, or functionality with your new application? If so, rest assured that you are in good company. Many development organizations find themselves in the same situation.

This article discusses some of the challenges of legacy system integration, then introduces the J2EE Connector Architecture (J2EE CA) and explains how it can significantly reduce the problems of integrating your legacy system. It also offers a comprehensive example of how to use the current version of J2EE CA, version 1.0, to access a common transaction-processing platform from a Java 2 Enterprise Edition (J2EE) platform application. This article concludes with an overview of the upcoming new release of J2EE CA, version 1.5, and explains some of the additional features and benefits introduced in this new version. This article assumes that you have a working knowledge of Java and J2EE.


If you've ever had to integrate legacy data, data sources, or functionality with a new application, you've no doubt faced a number of challenges: for instance, figuring out how to connect to legacy systems, manage connections, and convert different data types between the systems. Most likely, you either implemented your own mechanisms to address these issues -- that is, if you had the time and knowledge -- or you licensed proprietary third-party technology to do so. And chances are, the final solutions cost a significant amount of time and money -- and most of it was spent solving the underlying infrastructure challenges, not the real business problem at hand.

Without an easy standards-based solution, you didn't have much of a choice.

Fortunately, J2EE Connector Architecture (J2EE CA) has changed this. J2EE CA is a standards-based mechanism of accessing legacy systems from Java / J2EE applications that significantly reduces the challenges of legacy system integration.

Related Reading

Hardcore Java
By Robert Simmons, Jr.

J2EE CA is best explained with a simple analogy. Most developers are familiar with the Java Database Connectivity (JDBC) API, which lets Java programs access relational databases in an easy, standardized way. Before JDBC came along, it was much more difficult for programs to access and interact with databases.

Programs used data source-specific mechanisms and features, as well as different data conversions, so unless you had specialized domain expertise, you were faced with substantial project delays, project quality issues, database implementation lock-in, and other problems.

J2EE CA is to legacy data and application integration as JDBC is to database interaction. It provides a standardized, easy-to-use, legacy system-independent way to communicate with the different backend systems that your project must integrate with. By doing so, it lets you reuse technology as well as domain expertise. J2EE CA is more generic in its approach than JDBC, however, providing connectivity to a broader spectrum of backend systems. JDBC assumes that data will be of a relational nature; J2EE CA does not.

Once JDBC was introduced, did you ever consider not using it, or JDBC-based technologies (such as TopLink), to access different data sources from Java or J2EE applications? Probably not. We're convinced the same will be true for J2EE CA. Once you learn how to use it and you start enjoying its benefits, you won't want to use any other method to integrate applications with legacy systems.

Let's take a look at J2EE CA 1.0, its functionality, and an overview of its high-level architecture.

At the heart of J2EE CA 1.0 are several standardized contracts and interfaces between different parties. The parties are the backend enterprise information system (EIS), the different application components, the application server, and the resource adapter. Let's look at each one:

The standardized contracts and interfaces between the different parties are the container-component contracts, the system contracts, and the optional common client interface (CCI). The resource adapter uses EIS-specific contracts to communicate with the EIS. Here's some more information on the different contracts and interfaces.

By defining the above contracts and interfaces J2EE CA helps developers, as well as resource adapter providers.

It offers developers standardized ways to connect to the EIS, managing security credentials and transactional boundaries. For most resource adapters, developers can also use the CCI to interact with the EIS. To revisit the JDBC analogy, CCI offers a standardized interaction interface to the EIS, similar to what's provided to database developers with ANSI SQL.

Resource adapter providers can write adapters that can be deployed and used across different J2EE application servers. They can rely on a set of system contracts that lets them implement adapters that are tightly integrated with application server functionality, such as security and transaction management, without having to implement any application server vendor-specific interfaces.

J2EE CA 1.0 in Action

After all this theory, let's take a look at a real-life example. Let's see how you can leverage J2EE CA 1.0 to connect a simple Enterprise JavaBean to a common transaction-processing platform, in this case BEA Tuxedo.

Our example uses a J2EE application that runs on Oracle Containers for J2EE (OC4J) 9.0.4 -- a J2EE-compliant application server with full support for J2EE Connector Architecture 1.0 -- and interacts with BEA Tuxedo 8.1 transaction server. The example also uses Attunity Connect 4.x, which provides standard integration between resource adapters and enterprise data sources, as well as legacy applications. The solution includes a resource adapter deployed in OC4J, and the Attunity Connect Engine configured on the target system. Attunity Connect can be used to access a wide variety of systems, including CICS, IMS, VSAM, Adabas, Tuxedo, RMS, and Enscribe.

To follow along with this article, please download the example files in oc4j-jca-tux.zip. Figure 1 shows the architecture of the sample application.

Figure 1
Figure 1. Architecture of the stockquote sample application.

Here are the high-level steps necessary to reproduce the example:

  1. Set up and configure the backend EIS (in this case, Tuxedo).
  2. Set up and configure the J2EE CA resource adapter and deploy it to the J2EE application server (in this case, Attunity's J2EE CA Tuxedo adapter).
  3. Implement and deploy the J2EE application that interacts with the EIS by using the J2EE CA resource adapter.

Let's take a closer look at these steps:

1. Tuxedo

Set up Tuxedo 8.1 on a Solaris system, and start the stock quote example (under the samples/atmi/xmlstockquote directory of the Tuxedo installation). The instructions are included in the same directory. Then, configure the Tuxedo Work Station Listener to listen on port 8090.

Here's an outline of the relevant part of the ubbconfig configuration file.

"stockxml" SRVGRP="GROUP1" SRVID=30
   CLOPT="-A -p 1,5:2,5 -o stock.out 
       -e stock.err -r" 
       MIN=1 MAX=5 CONV=N
   CLOPT="-A -- -n //host1:8090" 
       MIN=1 MAX=1 CONV=N

   LOAD=50 PRIO=50

2. Attunity Tuxedo J2EE CA Resource Adapter

The Attunity Connect solution consists of a J2EE CA resource adapter, an integration engine (Attunity Connect Engine), and a design time environment (Attunity Connect Studio). To set up the adapter, follow these steps:

First, define a MappedRecord called Record1 for a new interaction, which contains a single field of type String. Record1 is used as the input record for the interaction, as seen in Figure 2.

Click for larger view
Figure 2. Defining MappedRecord Record1 using Attunity Connect Studio. (You can click on the screenshot to open a full-size view.)

Next, define the STOCKQUOTE_Response MappedRecord as the output record of the new interaction. The Record1 field within STOCKQUOTE_Response has the same structure as the Record1 record defined earlier (see Figure 3.)

Click for larger view
Figure 3. Defining the STOCKQUOTE_Response MappedRecord. (You can click on the screenshot to open a full-size view.)

Then define the new STOCKQUOTE interaction (see Figure 4.)

Click for larger view
Figure 4. Defining the STOCKQUOTE Interaction. (You can click on the screenshot to open a full-size view.)

Finally, deploy the Attunity resource adapter into OC4J using OC4J's deployment tool, and configure the adapter to communicate with Tuxedo through Attunity Connect. Do this by setting properties in the OC4J resource adapter-specific oc4j-ra.xml configuration file. The following lists the properties you must set.

The following code example outlines the resulting oc4j-ra.xml file.

<connector-factory location="eis/attunityForTuxedo" 
   connector-name="Attunity Connect Legacy Adapter">
   <config-property name="userName" 
   <config-property name="password" 
   <config-property name="eisName" 
   <config-property name="serverName" 
   <config-property name="workspace" 
   <config-property name="portNumber" 
   <config-property name="persistentConnection" 
   <config-property name="keepAlive" 
   <config-property name="firewallProtocol" 
   <config-property name="connectTimeout" 
   <config-property name="encryptionProtocol" 
   <config-property name="encryptionKeyName" 
   <config-property name="encryptionKeyValue" 

3. J2EE Demo Application

Implement a stateless session bean that uses CCI to obtain connections and interact with Tuxedo through the Attunity resource adapter.

See the following code example.

// Do context lookup for Attunity Connection Factory
Context ic = new InitialContext();
ConnectionFactory cf = (ConnectionFactory) 

// Get a connection
Connection con = cf.getConnection();

// Create an interaction
Interaction ix = con.createInteraction();

// Add an interaction spec and set it with
// the Tuxedo service name
AttuInteractionSpec iSpec = new AttuInteractionSpec();

// Ask Attunity's record factory to create an 
// input record with the proper format
RecordFactory rf = cf.getRecordFactory();
MappedRecord input = 

// Add data, which is the stock quote request, 
// to input record
input.put("Record1_data", "<stock_quote><symbol>" 
    + symbol + "</symbol></stock_quote>");

// Execute interaction with input record and spec
MappedRecord output = 
    (MappedRecord) ix.execute(iSpec, input);

// Return output for further processing.
return output;

The connection factory, record factory, connection, and interaction classes used by the session bean come from the Attunity resource adapter and implement interfaces / APIs defined in CCI. The session bean interacts with the resource adapter by calling the methods of these classes.

When the session bean invokes the interaction, the Attunity resource adapter gathers the function name, STOCKQUOTE, from the interaction specification, and the argument, which is the stock quote request containing the stock symbol, from the input record. It then invokes the STOCKQUOTE service on the Tuxedo server with the request. Some resource adapters may invoke the Tuxedo service directly. In the case of the Attunity adapter, this call is performed through the Attunity Connect Engine. The Attunity resource adapter first sends the interaction call to the Attunity Connect Engine, which repackages the data into the appropriate Tuxedo format and then invokes the Tuxedo service, using Tuxedo's proprietary API.

Once the Attunity Connect Engine receives a response from Tuxedo, it reformats it into the return data structure type defined in Attunity Connect Studio. It then sends the response back to the EJB through the Attunity resource adapter.

J2EE 1.4 and J2EE CA Version 1.5

Now that we've introduced you to J2EE CA 1.0, let's discuss J2EE CA 1.5 (see JSR-112), which will be part of J2EE 1.4.

While J2EE CA 1.0 represents a major step forward for legacy system integration for Java and J2EE applications, certain aspects were not addressed in this release. Version 1.0 still treats the EIS as a data source to be queried, not as an active process that can produce events and initiate calls itself. J2EE CA 1.5 extends the capabilities of J2EE CA 1.0 by adding:

Related Reading

J2EE Design Patterns
By William Crawford, Jonathan Kaplan

So, how would our example above benefit from J2EE CA 1.5? Using J2EE CA 1.5 would strengthen the integration between the J2EE platform and the Attunity Tuxedo adapter in the following key areas:

After learning about all the new and exciting features provided with J2EE CA 1.5, you probably can't wait to start experiencing it first hand.

Fortunately, Oracle provides the OC4J 10g (10.0.3) Developer Preview 2 that has passed the J2EE 1.4 compatibility test suite and is officially J2EE 1.4 compatible.


This article discussed the challenges historically associated with legacy system integration and introduced the J2EE Connector Architecture as a standard way of solving these problems. J2EE CA can significantly help you with any legacy system integration. It's available today and will become even more powerful in the future through new releases. Start using it today.

Anthony Lai is a principal member of the Oracle technical staff and a developer in the J2EE Connector Architecture area of Oracle Application Server Containers of J2EE.

Jyotsna Laxminarayanan is a principal member of the Oracle technical staff and contributes to the J2EE Connector Architecture implementation, which is part of Oracle Application Server.

Lars Ewe is a senior principal product manager for Oracle System Management Products.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.