ONJava.

com: J2EE Connector Architecture

Published on ONJava.com (http://www.onjava.com/)

http://www.onjava.com/pub/a/onjava/2004/03/24/j2eeca.html
See this if you're having trouble printing code examples

J2EE Connector Architecture

by Anthony Lai, Jyotsna Laxminarayanan and Lars Ewe

03/24/2004

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.

Introduction

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.

J2EE CA is best explained with a simple analogy. Most developers are familiar with the Java

http://www.onjava.com/lpt/a/4645 (1 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

Database Connectivity (JDBC) API, which lets Java programs access

relational databases in an easy, standardized way. Before JDBC came Related Reading
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 Hardcore Java
generic in its approach than JDBC, however, providing connectivity By Robert Simmons,
to a broader spectrum of backend systems. JDBC assumes that data Jr.
will be of a relational nature; J2EE CA does not. Table of Contents
Index
Once JDBC was introduced, did you ever consider not using it, or Sample Chapter
JDBC-based technologies (such as TopLink), to access different data
Read Online--Safari
sources from Java or J2EE applications? Probably not. We're
Search this book on Safari:
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. Only This Book
Code Fragments only
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:

EIS: This is the backend legacy system that the application components must integrate with.

Application components: These are Java or J2EE application components (for example,
Enterprise JavaBeans) that must integrate with the EIS.

Application server: The application server (for instance, Oracle Application Server 10g)
provides the runtime environment (container) in which the application components and the
resource adapter execute. It also furnishes system-level services such as connection,
transaction, and security management.

Resource adapter: This connects application components with the EIS by implementing
system-level services specific to the EIS, thereby shielding the application components from

http://www.onjava.com/lpt/a/4645 (2 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

the EIS-specific system-level services. It plugs into the application server by using
standardized system contracts.

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.

Container-component contract: J2EE component contracts standardize the interaction between

the application components and the application server. For example, in the case of EJBs, the
contract is the Enterprise JavaBeans specification and its different guarantees and interfaces
between the EJB container and the hosted EJBs running inside the container. Transactional
attributes, security attributes, other common J2EE component attributes, interfaces, and
services are well integrated with the J2EE CA system contracts (mentioned below). This is
because J2EE CA functions as a bridge between the resource adapter and the remainder of the
J2EE application server, its services, containers, and any components running in those
containers.

System contracts: J2EE CA contracts between the application server and the resource adapter
to standardize things such as security management and transaction management.

CCI: This J2EE CA client interface standardizes the interaction API between the application
components and the resource adapter. Although CCI is a great feature, it's optional, so not all
J2EE CA-compliant resource adapters provide one. Some resource adapter providers offer EIS-
specific client interaction interfaces instead.

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.

http://www.onjava.com/lpt/a/4645 (3 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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

http://www.onjava.com/lpt/a/4645 (4 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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.

*SERVERS
"stockxml" SRVGRP="GROUP1" SRVID=30
CLOPT="-A -p 1,5:2,5 -o stock.out
-e stock.err -r"
RQADDR="stockxml"
RQPERM=0666 REPLYQ=Y RPPERM=0666
MIN=1 MAX=5 CONV=N
SYSTEM_ACCESS=FASTPATH
MAXGEN=1 GRACE=86400 RESTART=N
MINDISPATCHTHREADS=0 MAXDISPATCHTHREADS=1
THREADSTACKSIZE=0
"WSL" SRVGRP="GROUP2" SRVID=20
CLOPT="-A -- -n //host1:8090"
RQPERM=0660 REPLYQ=Y RPPERM=0660
MIN=1 MAX=1 CONV=N
SYSTEM_ACCESS=FASTPATH
MAXGEN=5 GRACE=86400 RESTART=Y
MINDISPATCHTHREADS=0 MAXDISPATCHTHREADS=1
THREADSTACKSIZE=0
SICACHEENTRIESMAX="500"

*SERVICES
"STOCKQUOTE"
LOAD=50 PRIO=50
BUFTYPE="ALL"
TRANTIME=30
AUTOTRAN=N

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:

Configure the integration engine to communicate with the Tuxedo installation by modifying
the nav_login script. In this example, the WSNADDR is set to point to: //

http://www.onjava.com/lpt/a/4645 (5 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

localhost:8090

Define the interaction for invoking the stock quote Tuxedo service from the EJB, and the data
structures for the input argument and return type for the interaction, using Attunity Connect
Studio. The interaction is named STOCKQUOTE. Its input argument is defined as a
MappedRecord (as defined in CCI) named Record1. Its return type is defined as a
MappedRecord named STOCKQUOTE_Response.

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.

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

http://www.onjava.com/lpt/a/4645 (6 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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

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

http://www.onjava.com/lpt/a/4645 (7 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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.

userName/password
The username and password of the user who started the Attunity Connect daemon process.

eisName
The name of the adapter as defined during design time (in this example, stockquote).

serverName
The machine on which the integration server runs.

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"
value="foo"/>
<config-property name="password"
value="bar"/>
<config-property name="eisName"
value="stockquote"/>
<config-property name="serverName"
value="host1"/>
<config-property name="workspace"
value="stockquoteEvent"/>
<config-property name="portNumber"
value="2552"/>
<config-property name="persistentConnection"
value="true"/>
<config-property name="keepAlive"
value="true"/>
<config-property name="firewallProtocol"
value=""/>
<config-property name="connectTimeout"
value=""/>
<config-property name="encryptionProtocol"
value=""/>
<config-property name="encryptionKeyName"
value=""/>
<config-property name="encryptionKeyValue"
value=""/>
</connector-factory>

http://www.onjava.com/lpt/a/4645 (8 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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)
ic.lookup("java:comp/env/eis/attunityForTuxedo");

// 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();
iSpec.setFunctionName("STOCKQUOTE");

// Ask Attunity's record factory to create an

// input record with the proper format
RecordFactory rf = cf.getRecordFactory();
MappedRecord input =
rf.createMappedRecord("Record1");

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

http://www.onjava.com/lpt/a/4645 (9 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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:

Lifecycle management: A new contract between an application

server and a resource adapter lets the application server Related Reading
manage the resource adapter lifecycle (deployment/
undeployment, adapter startup/shutdown).

Work management: A new contract between an application

server and a resource adapter standardizes the management of
work between both parties by letting the resource adapter
submit work requests to the application server. It also lets the
application server control thread management and pooling
associated with work requests submitted by the resource
adapter. In addition, the new contract lets the adapter create
and schedule tasks to be executed within specific transaction
contexts. Task scheduling is extremely flexible, allowing for
blocking calls as well as asynchronous calls. J2EE Design
Patterns
Transaction inflow: A new contract between an application By William Crawford,
server and a resource adapter lets the resource adapter Jonathan Kaplan
propagate transactions initiated by the EIS to the application
Table of Contents
server. It also allows for Quality of Service, such as crash

http://www.onjava.com/lpt/a/4645 (10 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

recovery. Index
Sample Chapter

Message inflow: A new contract between an application server Read Online--Safari

and a resource adapter supports generic asynchronous message Search this book on Safari:
delivery from the EIS to different message endpoints located
in the applications server through the resource adapter. In this
Only This Book
way, different message providers, such as the Java Message
Service (JMS) and Java API for XML Messaging (JAXM), Code Fragments only
can be plugged into J2EE application servers. This contract
allows the EIS to be an active process, generating its own events and messages rather than a
passive data source. Resource adapters will be able to leverage this to eliminate mid-tier
polling, a traditional but poor use of mid-tier resources.

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:

Improved resource usage and quality of service. This is a result of the addition of well-defined
lifecycle management and work management contracts.

Bi-directional integration with legacy systems based on inbound message and transaction
inflow capabilities. This lets systems such as Tuxedo send XML messages into the J2EE
platform and initiate transactions that will be propagated to the J2EE application server.

Enhanced performance, failure resilience, and scalability, by introducing asynchronous

integration.

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.

Conclusions

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

http://www.onjava.com/lpt/a/4645 (11 of 12)02/07/2004 15:09:30

 ONJava.com: J2EE Connector Architecture

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 2004 O'Reilly Media, Inc.

http://www.onjava.com/lpt/a/4645 (12 of 12)02/07/2004 15:09:30