You are on page 1of 4

Sun Java Solaris Communities My SDN Account

APIs Downloads Products Support Training Participate » search tips  Search

SDN Home > Sun Java System Application Server > Reference > Code Samples and Apps >
 

Code sample
Application Integration with Legacy Systems Using Java Connector Architecture
By Manish Verma, Principal Architect, Second Foundation, Inc.  

To download the source code associated with this article, follow these instructions.

 
Introduction

The objective of this paper is to demonstrate and document the steps towards integrating a J2EE technology application with a legacy application using J2EE Connector Architecture
(JCA) version 1.0. In this article, we will review and discuss various features provided by JCA-based resource adapters.
 
The components of this integration scenario are illustrated in this figure.
 

The Sun ONE Application Server is at the heart of the system. It provides a framework for transaction management, connection management including connection pooling, security, and
so on The application server serves as a single integration point between all the applications. It thus reduces the integration complexity from "many to many" to "many to one."
 
We have chosen an enterprise information system (EIS) to model a typical legacy system, e.g., multiple back-office applications running on an RDBMS like Oracle. The EIS
communicates with the application server via a connector. An EIS with an appropriate connector can connect to any other application that can be deployed on the application server.
Once a connector for an EIS has been developed, it can be deployed on any application server that conforms to the J2EE specifications.
 
The Web services component is a mechanism for exposing the public methods of the Enterprise JavaBeans (EJB) components that have been deployed in the application server.
These Web services are available to clients via the Sun ONE Application Server.
 
Intended Audience for This Article

This article demonstrates how Sun ONE products and technology such as JCA compliant adapters, EJB components and Web services can work together to expose the functionality of
enterprise legacy applications. This article assumes that the reader is familiar with technologies such as J2EE, JCA, EJB components and Web services.
 
This article is not intended to be a reference document for implementing JCA compliant adapters, EJB components, or Web services.
 
Scope of This Article

This article discusses JCA version 1.0, which does not support asynchronous adapters. Thus we will not cover integration issues related to asynchronous communication (including
Push / Pull Systems).
 
In addition, resource adapters can be used in a managed or non-managed environment. In a managed environment, resource adapters are deployed on an application server. In a non-
managed environment, clients can directly use resource adapters in a client server architecture where the resource adapter becomes a part of the client and the legacy system
becomes the server. In this article we consider only connectors deployed in a managed environment.
 
The EJB component created in the example code is compliant with the EJB 1.0 specification.
 
This article defines Web services using RPC. Messaging-based Web services are not discussed.
 
The remainder of this article discusses the integration details on a per-component basis.
 
In Part I, we discuss how to create a connector for an enterprise information system. As part of the creation of the resource adapter, we also provide information on:
 

Connection management
Transaction management
Security implementation

 
Part II discusses the creation of the EJB components that connect to the connector developed in Part I. We create a stateless session bean that accesses the adapter through the J2EE
Connector Architecture (JCA) Common Client Interface (CCI).
 
Part III deals with the Web service and Web service client creation for exposing and executing the EJB methods developed in Part II.
 
Part IV summarizes the article paper and looks at performance implications and future developments.
 
Part I: Creating a Resource Adapter

The first step in creating a resource adapter is identification of parameters required for connecting to a legacy application. The next step is to create a connection management
infrastructure, followed by transaction management, security, and finally, invoking the legacy application functions/APIs.
 
The J2EE Connector Architecture requires that the adapter implements the following interfaces.
 

ConnectionFactory
ManagedConnectionFactory
Connection
ManagedConnection
LocalTransaction
XAResource
ConnectionRequestInfo*
ConnectionEventListenerImpl*
Interaction*
InteractionSpec*
ConnectionSpec*
(Other metadata interfaces)

 
(*Not covered in this paper, but provided as a part of the source code associated with this paper; Click here to download the source code.)
 
All the parameters that are required to establish a connection to the legacy system must be defined as M a n a g e d C o n n e c t i o n F a c t o r y bean attributes. These attributes are set at
the time of the deployment of the resource adapter.
 
Some connection parameters can also be specified as part of C o n n e c t i o n R e q u e s t I n f o. The connection parameters that form part of C o n n e c t i o n R e q u e s t I n f o must be
client-specific (username, password, and so on) and should not change the configuration of the underlying legacy application (database URL, and so on). The client can pass this
object as input for establishing the connection.
 
The adapter implements the C o n n e c t i o n F a c t o r y interface. It takes C o n n e c t i o n R e q u e s t I n f o as input and calls a l l o c a t e C o n n e c t i o n on C o n n e c t i o n M a n a g e r that is
provided by the application server to get the connection. Connection Manager internally calls M a n a g e d C o n n e c t i o n F a c t o r y provided by adapter to match existing connection (if any)
using M a n a g e d C o n n e c t i o n F a c t o r y . m a t c h M a n a g e d C o n n e c t i o n.
 
If it does not find an existing connection, it calls M a n a g e d C o n n e c t i o n F a c t o r y . c r e a t e M a n a g e d C o n n e c t i o n to create a new connection. In order to use connection pooling, it
is imperative that the developer provides the implementation of the equals and hashcode methods on M a n a g e d C o n n e c t i o n F a c t o r y. These methods should be implemented
such that they consider only the differentiating property of the legacy application. This is a must for differentiating one resource adapter connection from another.
 
Connection Management

Connection Management is establishing connections and managing the pool of connections between adapter and legacy application. This section documents the following aspects of
connection management:
 

Method for the Client to Establish the Connection to the Legacy Application
Method Used by Application Server to Get a Matching Connection from the Connection Pool
Methods Used by Application Server to Match the Connections
Method to Create a New Connection with the Legacy Application

 
In addition to those listed above, there are methods for deleting and reauthentication not listed here. The adapter can also provide an implementation of the C o n n e c t i o n E v e n t
interface to take specific actions on certain connection events. These additional implementations of classes and methods are available as part of the source code associated with this
paper.
 
Method for the Client to Establish the Connection to the Legacy Application
Code example 1 (C o n n e c t i o n F a c t o r y) shows the implementation of all important g e t C o n n e c t i o n methods for this interface. The resource adapter client calls the
g e t C o n n e c t i o n method on the C o n n e c t i o n F a c t o r y class. The g e t C o n n e c t i o n method calls a l l o c a t e C o n n e c t i o n on c o n n e c t i o n M a n a g e r, which in turn is
supplied by the application server.
 
Method Used by Application Server to Get a Matching Connection from the Connection Pool
Code example 2 (M a n a g e d C o n n e c t i o n F a c t o r y . M a t c h M a n a g e d C o n n e c t i o n) shows how a C o n n e c t i o n M a n a g e r class implemented by the application server handles the
allocation of M a n a g e d C o n n e c t i o n to the client application. The application server maintains a candidate set of M a n a g e d C o n n e c t i o n instances that it uses to look for a
M a n a g e d C o n n e c t i o n suitable for servicing the client request. To match the existing set of connections to the requested connection, the application server calls
M a n a g e C o n n e c t i o n F a c t o r y . M a t c h M a n a g e d C o n n e c t i o n.
 
Methods Used by Application Server to Match the Connections
Code example 3 (M a n a g e d C o n n e c t i o n F a c t o r y - equals and HashCode) illustrates how the application server uses equals and the H a s h c o d e method on the
M a n a g e d C o n n e c t i o n F a c t o r y to manage the pool of connections.
 
Method to Create a New Connection with the Legacy Application
If no matching connection is found in the connection pool maintained by the application server, the application server calls c r e a t e M a n a g e d C o n n e c t i o n on
M a n a g e d C o n n e c t i o n F a c t o r y.
 
The C r e a t e M a n a g e d C o n n e c t i o n based on the connection parameters supplied by the client in C o n n e c t i o n R e q u e s t I n f o returns a M a n a g e d C o n n e c t i o n instance.
 
Code example 4 (M a n a g e d C o n n e c t i o n F a c t o r y . C r e a t e M a n a g e d C o n n e c t i o n) is the C r e a t e M a n a g e d C o n n e c t i o n method of M a n a g e d C o n n e c t i o n F a c t o r y. This
method also has code that handles security and transaction management. We will explore that in subsequent sections. Here we will explain the instantiation of
M a n a g e d C o n n e c t i o n.
 
Transaction Management

The resource adapters have three levels of transaction management:


 

No transaction
Local transaction
Distributed transaction

 
"No transaction" is the case when each operation with the legacy application is independent of any other operation. For creating a M a n a g e d C o n n e c t i o n with a legacy application that
does not support transactions, specify NoTransaction as the value of the transaction-support tag in the deployment descriptor.
 
"Local transaction" is where multiple operations performed on a single legacy application are tied to succeed or fail together as a group. For creating ManagedConnections to participate
in a local transaction, the value of transaction-support tag in deployment descriptor should be set to LocalTransaction.
 
We use the "distributed transaction" capability when we need to do multiple operations on multiple legacy applications, and also when we need them to be tied to succeed or fail
together as a group. The creation of ManagedConnections for distributed transactions is more complex, and is handled later in this chapter.
 
Implementation of Local Transaction

For a M a n a g e d C o n n e c t i o n to participate in a local transaction or to have no transaction at all, a normal connection that does not support distributed transaction can be used.
 
In our implementation of M a n a g e d C o n n e c t i o n F a c t o r y . C r e a t e M a n a g e d C o n n e c t i o n (Code example 4
M a n a g e d C o n n e c t i o n F a c t o r y . C r e a t e M a n a g e d C o n n e c t i o n), you can see that we support both types of connections. The type of connection returned is based on the value of
the distributed data source name in the deployment descriptor.
 
If the data source name is not set, we create a normal connection. Otherwise, if the data source name is set, we return a connection that supports distributed transactions. This is also
explained in more detail in the "Implementation of Distributed Transaction" section later in this paper. For example, in the case of a legacy application database, we will either create a
j a v a . s q l . c o n n e c t i o n or a j a v a x . s q l . X A C o n n e c t i o n, based on the data source value in the deployment descriptor.
 
Code example 5 (M a n a g e d C o n n e c t i o n - L o c a l T r a n s a c t i o n) shows some key methods that have to be implemented for supporting L o c a l T r a n s a c t i o n s.
 
For supporting local transactions, the adapter itself has to provide the implementation of the L o c a l T r a n s a c t i o n. This is shown in code example 6 (L o c a l T r a n s a c t i o n).
 
Implementation of Distributed Transaction
We employ the "distributed transaction" capability when we need to do multiple operations on multiple legacy applications, and also when we need them to be tied together to succeed
or fail as a group.
 
For creating a M a n a g e d C o n n e c t i o n that supports distributed transactions, we need to specify the datasource JNDI name in the deployment descriptor. At the time of the creation of
the connection, the resource adapter does a lookup on the JNDI name and gets the distributed transaction supporting the connection from the legacy application.
 
The resource adapter then retrieves the distributed resource that implements a distributed transaction from the distributed connection, and stores it with M a n a g e d C o n n e c t i o n. It then
uses this distributed resource to control the transaction.
 
Code example 7 (M a n a g e d C o n n e c t i o n - D i s t r i b u t e d t r a n s a c t i o n) shows how to create a M a n a g e d C o n n e c t i o n with a legacy application that supports distributed
transaction.
 
The adapter must provide the implementation of the X A R e s o u r c e interface for supporting a distributed transaction that is performed on the underlying resource manager. Code
example 8 (X A R e s o u r c e).shows one such implementation of X A R e s o u r c e.
 
Providing Security

Here we discuss security in the context of accessing information from a legacy application using a resource adapter. The issues fall under the following categories:
 

Client authentication
Client authorization: to provide or deny access to various resources
Secure communication: between a client and legacy application

 
This article deals only with client authentication, because it is usually implemented in the legacy application itself. Furthermore, establishment of a secure communication channel
between a client and a legacy application is a major topic in itself; that subject will be covered in future articles.
 
Application servers can adopt any kind of authentication mechanism to support client authentication. In our example, we have chosen to use the B a s i c P a s s w o r d authentication
mechanism. The type of authentication supported by the resource adapter can be specified in the deployment descriptor by setting the authentication-mechanism-type tag to
B a s i c P a s s w o r d.
 
Please refer to code example 4 (M a n a g e d C o n n e c t i o n F a c t o r y . C r e a t e M a n a g e d C o n n e c t i o n). We have used P a s s w o r d C r e d e n t i a l s to authenticate the user before we
provide the connection in M a n a g e d C o n n e c t i o n F a c t o r y . C r e a t e M a n a g e d C o n n e c t i o n.
 
Part II: Creation of an EJB Component to Access the Resource Adapter

This chapter explores creating an EJB component to connect to the adapter that we discussed and created in Part I. We will create a stateless session bean that has one method for
executing an SQL statement.
 
Specifying the Remote Interface

To implement this session bean we will need to provide a remote interface for the bean. This interface has one function that we want to expose to the clients. Code example 9
(E J B O b j e c t) has the implementation of the class.
 
Specifying the Home Interface

The next step is to create a home interface for the bean. This is to provide a mechanism to allow the application server to create new session beans on behalf of the client. Code
example 10 (EJBHome) shows the implementation of the home interface for our bean.
 
Writing the EJB Class

This class has all the business logic for the methods exposed through the bean's remote interface. Code example 11 (Enterprise JavaBean Logic) shows the methods required to
service the methods in the remote interface.
 
Part III: Creating a Web Service to Expose the Methods of the EJB Component

This chapter describes exposing the public methods of the EJB component developed in Part II of this paper as a Web service and accessing it through a Web service client.
 
We will write two Java classes for creating a Web service for the EJB methods:
 

The WebService Interface class shown in code example 12 defines the interface that has the methods ultimately made visible to the Web service clients.

The WebService Implemenation class shown in code example 13 provides the actual implementation of the interface.

 
Writing a Client to Access the Web Service

We will now create W e b S e r v i c e C l i e n t for accessing the Web service. The code is shown in code example 14 (W e b S e r v i c e C l i e n t).
 
Part IV: Performance Implications and Future Developments

Thus far we have created a chain of components ranging from the legacy application adapter to the W e b S e r v i c e C l i e n t. This layering of components, which gives us greater
flexibility and helps us illustrate the concepts in a modular fashion, necessitates a drop in performance in the real world.
 
Performance Enhancement Options

A good design trade-off would be to keep the chain of components down to a judicious size. Depending on the need, it is possible to write a client application at any point in the
component chain to directly access the legacy application's functionality. This reduces the length of the component chain, thereby improving overall performance. For instance, in our
example, we have a client application that talks to the Web service, which then communicates with the EJB component, which then talks to the resource adapter via CCI.
 
In order to shorten the chain, we could create a client application which would access the EJB component, which would then access the resource adapter using Common Client
Interface (CCI). This would be fine, provided we were willing to live with the fact that each time we had to develop a new client, we would need to embark on a fairly complex coding
exercise.
 
We could shorten the chain still further by writing a client application that could directly access the resource adapter using CCI. While this might improve performance, new client
development would be even more complicated than in the previous example. However, this approach might be fine for a "one-off" client implementation.
 
Of course, we could always write a client to directly communicate with the legacy application, but that would negate the object of this exercise, which is to establish a general and
application-independent communication mechanism between a Java technology-based application and a legacy system. Furthermore, we would lose out on the performance gains
provided by the Sun ONE Application Server, e.g., connection pooling, pooling of EJB components (where applicable), transaction control and management, and so on.
 
What's New in JCA 1.5?

The latest J2EE Connector Architecture specification, JCA 1.5, introduces many new features, some of which are:
 

Adapter life-cycle management


Work management
Message Inflow for two-way communications

 
Adapter Life-Cycle Management
A life-cycle management contract allows an application server to initialize an adapter during the deployment of the adapter or application server startup. It also allows an application
server to send notifications to the adapter during server shutdown or undeployment of the adapter. The adapter can then choose to implement interfaces defined for this purpose and
thus take appropriate actions when these events occur.
 
Work Management
This mechanism enables the adapter to simulate multithreaded behavior without the need to actually implement multithreaded support in the adapter itself. The adapter creates an
instance of the W o r k interface and submits it to the W o r k M a n a g e r provided by the application server.
 
The W o r k M a n a g e r picks a free thread from the thread-pool maintained by the application server, and executes the W o r k item submitted by the adapter.
 
Here are some advantages of using a multithreaded simulation mechanism provided by the application server, over implementing multithreaded capabilities within the adapter:
 

The application server is better placed to manage system resources like threads that it can pool across various resource adapters.
Threads created by the adapter may interfere with the orderly shutdown of the application server.
The application server has complete knowledge of its runtime environment. This allows it to use its resources more efficiently, as well as perform better housekeeping.

 
Message Inflow for Two-Way Communications
Asynchronous communication is a very powerful and well accepted message delivery and notification mechanism. Here are some advantages of using asynchronous communication:
 

The message producer can create messages regardless of whether or not a consumer is listening. This lets the adapters' clients submit a request to the legacy application and
move on to other tasks, while the request is being processed.

Message consumers have to express their interest in the message sent out by the producer. Multiple consumers can subscribe to the messages published by a producer. For
example, various adapters could be listeners to the messages being produced by the clients, and can subscribe to the produced messages.

Message types no longer have any significance. All messages are treated as Binary Large Objects (BLOBs). What goes in the body of the message does not have any impact on
how a message is handled or delivered.

Message production and consumption do not share any execution context; message production and consumption could happen at different times in different processes.

 
According to the JCA 1.5 specification, it is possible for legacy application adapters to call applications deployed in the application server. This can be achieved by using Java Message
Service APIs directly or by using message-driven beans.
 
Conclusion

This paper has described integrating Java technology-based applications with legacy applications. We have made use of the robust and proven connection management, connection
pooling, transaction management, and security mechanisms provided by the Sun ONE Application Server and Sun's J2EE Connector Architecture.
 
Manish Verma is a principal software architect working with Second Foundation Inc., a global software services and systems integration company. Manish has 10 years of experience in
all aspects of the software development life cycle and has designed integration strategies for client organizations running disparate systems. Manish's integration expertise is founded on
his understanding of a host of technologies including various legacy systems, .NET, Java and the latest middleware. Prior to Second Foundation, Manish worked as a software architect
and technical lead at Quark Inc., Hewlett Packard, Endura Software and The Williams Company.
 

Back to top

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.

Oracle is reviewing the Sun product roadmap and will provide guidance to customers in accordance with Oracle's standard product communication policies. Any resulting features
and timing of release of such features as determined by Oracle's review of roadmaps, are at the sole discretion of Oracle. All product roadmap information, whether communicated
by Sun Microsystems or by Oracle, does not represent a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. It
is intended for information purposes only, and may not be incorporated into any contract.

About Sun  |  About This Site  |  Newsletters  |  Contact Us  |  Employment  |  How to Buy  |  Licensing  |  Terms of A Sun Developer Network Site
Use  |  Privacy  |  Trademarks
 
Unless otherwise licensed,
 
code in all technical manuals
© 2010, Oracle Corporation and/or its affiliates herein (including articles,
FAQs, samples) is provided
under this License.
 

 Sun Developer RSS Feeds

You might also like