j2ee connector archi

8/8/2019 J2EE Connector Archi

1/9

This Tech Tip reprinted with permission byjava.sun.com

If you've ever tried to integrate legacy systems with a J2EE application server, you know that it

can be quite a challenge. Managing connections, converting between different data types, andeven sending messages between an application server and an Enterprise Information System

(EIS) can leave an enterprise Java programmer with quite a headache. Thankfully, there's theJ2EE Connector Architecture, now in version 1.5 in J2EE 1.4, which defines a standard

architecture for connecting the J2EE platform to heterogeneous EISs.

Using the J2EE Connector Architecture, EIS vendors do not have to create custom connectionsoftware for multiple application servers. Neither do application server vendors have tocustomize their code to support various EIS packages. Instead, these vendors can package "in-

between" code that conforms to the J2EE Connector Architecture specifications. The codeimplements or extends a set of standardized contract interfaces and classes that adapt data and

messages for communication between the application server and the EIS resource. This in-between code plugs into the application server, and is called a resource adapter.

A resource adapter module, typically called a Resource Adapter Archive (RAR), is simply a JAR

file. A RAR typically includes the following:

y Java classes and interfaces that implement the resource adapter contracts and client APIs.y Any native libraries that are required to communicate with the EIS.y A deployment descriptor file, ra.xml, that the application server uses to configure the

resource adapter. The file is located in the META-INF directory.

Here is an illustration that shows where the resource adapter fits in with an application server andan EIS.


2/9

Note how each element communicates with one other.

There are three important communication bridges that comprise the J2EE ConnectorArchitecture. Let's look at each of them.

Client APIs and the Common Client Interface

Application components that plug into the application server must have a way of communicatingwith the resource adapter. The Common Client Interface (CCI) is the recommended API to do

this. The CCI is an API that is implemented in the javax.resource.cci package. The API isrecommended because it's easy to use, but it's not mandatory. Resource adapter implementers are

free to create their own specialized client APIs to communicate with application components ifthe CCI does not satisfy their needs.

Container-Component Contracts

This is a standardized communication method between the application server and the applicationcomponents. There's not much here in terms of JCA. For example, if a Web application uses

Enterprise JavaBeans (EJB) components, then the EJB specification is the container-componentcontract that governs how each EJB component communicates with the application server.

System Contracts

This is a major part of the J2EE Connector Architecture. The architecture specifies several

system contracts that a resource adapter must conform to in order to communicate clearly withthe application server. The APIs for the system contracts are implemented in the


3/9

javax.resource.spi package. The 1.0 version of the J2EE Connector Architecture introduced three

such contracts:

y Connection Management Contract: Provides interfaces and classes that allow forconnections between the EIS and the application server. It also allows the application

server to pool these connections as it deems necessary.yy ransaction Management Contract: Brings atomic transaction capabilities to the EIS. The

EIS can then be managed either by the resource adapter or a transaction manager. This

only works one way, however. Transactions must be initiated outside the EIS and passedto it, not the reverse.

yy Security Contract: Ensures that there is proper authentication between the application

server and the EIS.y

With version 1.5 of the architecture, four new contracts were created that allow greaterfunctionality inside of a resource adapter. The new contracts are:

y Lifecycle Management Contract: Provides a way for the application server to cleanly startand shutdown the resource adapter.

y Work Management Contract: Provides interfaces and classes that allow resource adaptersto submit work for execution by the application server.

y Transaction Inflow Contract: Allows transactions to be passed from the EIS to theapplication server (the reverse of the Transaction Management Contract). It also assistswith transaction recovery in the event that the EIS crashes.

y Message Inflow Contract: Allows the resource adapter to send synchronous orasynchronous messages to endpoints within the application server.

Let's examine these four new contracts in more detail.

Lifecycle Management and Work Management Contracts

The ResourceAdapter interface in the javax.resource.spi package represents a resource adapter.There are two methods in the ResourceAdapter interface that allow for lifecycle management:

start() and stop(). The start() method is called when an application server wants to start aresource adapter (for example, to deploy it). The stop() method is called when the application

server wants to release a resource adapter (for example, to undeploy it).

The Work Management contract allows the resource adapter to submit work to the applicationserver. It does this by creating an object that extends the Work interface in the

javax.resource.spi.work package. The Work interface is an extension of the Runnable interface.In addition to the run() method that it inherits from Runnable and which executes in its own

thread, the Work interface contains a release() method. The application server can use release()to request that the thread complete, and release its resources as soon as possible.


4/9

Here is part of an example implementation of the ResourceAdapter interface that illustrates the

lifecycle management and work management contracts:

public class NexesResourceAdapterImpl implementsResourceAdapter {

// Ten secondspublic static final long WORK_START_TIMEOUT = 10000L;

public NexesResourceAdapterImpl() { }public voidstart(BootstrapContext ctx)throws ResourceAdapterInternalException{

WorkManager workManager = ctx.getWorkManager();Work nexesWorkJob = new NexesWorkImpl();WorkListener workListener =

new NexesWorkListenerImpl();

try {

// Unlike scheduleWork() or doWork(), this call// blocks until the work has started. If it takes// longer than 10 seconds for the work to start,// the call throws a WorkRejectedException.

workManager.startWork(nexesWorkJob, WORK_START_TIMEOUT,new ExecutionContext(), workListener);

} catch (WorkException e) {// Handle the exception

}}

public voidstop(){

// Do whatever you need to do here to close down the// resource adapter.

}

// Transaction Inflow contract methods omitted.// See the section "Message Inflow and Transaction// Inflow Contracts"

}

Notice that there is an object passed in with the start() method that implements the

BootstrapContext interface. This is an important object that allows the EIS to pass transactioninformation to the application server, as well as the ability to pass work to the application server.

See the section "Message Inflow and Transaction Inflow Contracts" for more details about theBootstrapContext interface.


5/9

Also notice the reference to the WorkListener interface:

WorkListener workListener =new NexesWorkListenerImpl();

and the startWork method:

workManager.startWork(nexesWorkJob, WORK_START_TIMEOUT,new ExecutionContext(), workListener);

If you want the application server to notify you about the progress of any work that is submitted,

you can create an object that implements the javax.resource.spi.WorkListener interface. You canthen register this object using the startWork() method of the WorkManager object on the

application server. The WorkManager interface provides a facility to submit Work instances forexecution. Registering the object allows the server to notify the resource adapter if the work was

rejected or accepted, and if accepted, when the work was started and completed. You can alsoextend the WorkAdapter class, which implements the WorkListener interface and provides

empty methods for each of these. Here is skeleton code for a class that implementsWorkListener:

public class NexesWorkListenerImpl implements WorkListener {

public voidworkAccepted(WorkEvent e) {// myAppServerLog.log("Work instance " + e +// " has been accepted.");

}

public voidworkRejected(WorkEvent e) {

// myAppServerLog.log("Work instance " + e +// " has been rejected.");

}

public voidworkStarted(WorkEvent e) {// myAppServerLog.log("Work instance " + e +// " has been started.");

}

public voidworkCompleted(WorkEvent e) {// myAppServerLog.log("Work instance " + e +// " has been completed.");

}

}

Message Inflow and Transaction Inflow Contracts

The Message Inflow contract allows the resource adapter to react to calls made by theapplication server to activate and deactivate message endpoints. The endpointActivation()

method in the ResourceAdapter interface is called during endpoint activation. This causes the


6/9

resource adapter to do the necessary setup for message delivery to the message endpoint. The

endpointDeactivation() method of ResourceAdapter is called when a message endpoint isdeactivated. This stops the resource adapter from delivering messages to the message endpoint.

A MessageEndpointFactory object in the javax.resource.spi.endpoint package is passed in to theendpointActivation method. The object is used by the resource adapter to create a number of

message endpoints. Any information about these endpoints should be removed from the resourceadapter when the endpointDeactivation() method is called. Finally, the getXAResources()

method of ResourceAdapter can be used to retrieve transaction resources in the event of a systemcrash. The endpointActivation(), endpointDeactivation(), and getXAResources() methods are

mandated by the ResourceAdapter interface.

public class NexesResourceAdapterImpl implementsResourceAdapter {

// Lifecycle Contract methods from earlier omitted.

public XAResource[] getXAResources(ActivationSpec[] specs)

throws ResourceException{// This method should either return an array of// XAResource objects that uniquely correspond to the// resource manager given the ActivationSpecs passed// in, or null if it does not support this par// of the Message Inflow contract.

return null;}

public voidendpointActivation(MessageEndpointFactory mef,ActivationSpec as)

throws NotSupportedException

{// This is also part of the Message Inflow contract.// The idea here is to create a message endpoint// using the MEF's createEndpoint() method, which is// then stored in the ActivationSpec class. This binds// the EIS and the application server together so that// the two can communicate independently of the// messaging style of the EIS.

}

public voidendpointDeactivation(MessageEndpointFactory mef,ActivationSpec as)

{

// This removes any resources that were created by the// endpointActivation() method above for the specified// messaging endpoint. The resource adapter must notify// any message providers that the endpoint is no longer// valid

}

}


7/9

The ActivationSpec class that is passed in to the ResourceAdapter methods is a JavaBean that

implements a number of get and set methods for various properties. In addition to providing

these get and set methods, an implementation must also provide a validate() method to ensurethat all of the properties have been legally set. If a property has not been set properly, the method

must throw an InvalidPropertyException. Note that an ActivationSpec object cannot overrideequals().

public class MyActivationSpec implements ActivationSpec,Serializable {

public voidsetMyProperty(MyProperty s) { }public MyProperty getMyProperty() { }

public voidvalidate() throws InvalidPropertyException { }

}

In version 1.0 of the J2EE Connector Architecture, a resource adapter could only pass transactioninformation to the EIS, either from itself or from an external transaction manager. However with

the Transaction Inflow contract in version 1.5 of the architecture, the resource adapter can passEIS transaction requests to the application server as well as use the BootstrapContext object that

is passed in with the start() method of the Lifecycle Contract. The BootStrapContext interfacewas mentioned briefly in the discussion of the Lifecycle Management contract. Here are the

methods in the BootstrapContext interface:

public class NexesBootstrapContextImpl implementsBootstrapContext {

public WorkManager getWorkManager() {// Get the work manager from the application server

}

public XATerminator getXATerminator() {return new NexesXATerminatorImpl();

}

public Timer createTimer() {return new Timer();

}

}

Let's also take a closer look at the XATerminator interface. Notice that it's the return type of thegetXATerminator() method in the BootStrapContext interface. The XATerminator interface

contains five simple methods that handle transactions:

public class NexesXATerminatorImpl implements XATerminator {

public voidcommit(Xid xid,boolean onePhase)


8/9

throws XAException { }public voidforget(Xid xid) throws XAException { }public int prepare(Xid xid) throws XAException { }public Xid[] recover(int flag) throws XAException { }public voidrollback(Xid xid) throws XAException { }

}

The Resource Adapter File

The resource adapter descriptor file, ra.xml, is fairly easy to create. You simply need to point inthe file to the class that implements the ResourceAdapter interface. The application server will

then access that class. See the J2EE Connector Architecture 1.5 specifications for moreinformation on resource adapter deployment descriptors, including how to tie incoming message

classes to ActivationSpec classes. Like all deployment descriptors, the ra.xml file needs to be inthe WEB-INF directory of the WAR file.

Skeleton Resource AdapterSun Microsystems, Inc.Unknown1.0

com.nexes.ra.NexesResourceAdapterImpl

For more information about the J2EE Connector Architecture, see the J2EE Connector

Architecture page.

Copyright (c) 2004-2005 Sun Microsystems, Inc.

All Rights Reserved.

Related Tips

y Accessing a Secure Enterprise Bean From a Java Client or Through Java Web StartTechnology

y Accessing an EJB from an applet


9/9

y Accessing bean components from JSPy Accessing EJB from a servlet within the same containery An example of a simple JSP pagey Automated code generationy Automated update of EJB deployment descriptory Bean with Indexed Properties and Accessing Indexed values through JSP Bean tags

j2ee connector archi

Documents