Home » Blogs » mvohra's blog

Understanding JCA, Implementation and Deployment (Weblogic)

<!-- main-content-block -->

<!-- <span class="submitted">By Manpreet Vohra (<a href="/users/mvohra" title="View user profile.">mvohra</a>) on 15 January, 2010</span> -->

<!-- Place this tag in your head or just before your close body tag -->

Abstract
This article talks about how to build a JCA Connector based on JCA specifications, JCA framework, features and deployment strategies for Weblogic Server.

Introduction
Prior to introduction to JCA, the J2EE platform did not address the integration of java based of Java based enterprise application with Enterprise Information System (EIS) like ERP, CRM, Mainframe, and Legacy Systems etc. As such vendor specific, tightly coupled, non-portable solutions were developed to achieve the connectivity to EIS. Now JCA defines a uniform way to integrate J2EE application servers with EIS by which the application server vendors implement the Connector Framework only once and EIS vendors develop one standard resource adapter based on this architecture. Thus a JCA compliant resource adapter can be deployed in any JCA compliant Application Server like WebLogic Server.

Resource Adapter
The resource adapter plays a central role in integration and connectivity between an Application Components, Application and EIS. To enable seamless integration the resource adapter must implement System Contracts, EIS specific Contracts and Application Component contracts (Client API). These contracts are defined in terms of interfaces that the adapter must implement. The various packages that contain these interfaces are:
javax.resource.spi - Adapter Interfaces to encapsulate EIS
javax.resource.cci - Client API Interface
javax.transaction.xa - XA Transactions Support Interface
javax.security.auth - Authentication and Authorization Interface

System Contracts
The system contract defines the interactions between Resource Adapter and the Application Server. There are 3 types of system contracts some of which are optional:

1. Connection Management (required)
This contract describes the understanding, a J2EE container has with the adapter regarding connection establishment, pooling and tearing down of connections to the EIS. The underlying protocol an adapter uses connect to EIS is outside the scope of JCA specification.
Connection Management Interfaces to Implement
ConnectionManager Provides Connection ManagementIn case of non-managed environment>/td>
ManagedConnection - Represents the physical connection to EIS
ManagedConnectionFactory - Represents a Factory For Managed Connections
ManagedConnectionMetaData - Provides information about the managed connections
ConnectionRequestInfo - Encapsulates the client credentials to obtain a connection to EIS
Connection - Represents the CCI Connection after a JNDI Lookup from the CCI Connection Factory. Each CCI Connection is associated with the Managed Connection
ConnectionFactory - Represents a Factory for CCI Connections.

2.Transaction Management (optional)
This contract allows the application to manage and propagate transaction
Context from the J2EE container to the EIS. These further are of two types:
a. Local Transactions
When only one system (EIS) is involved in an interaction, transactions are internally managed by the EIS system, thus they are called Local Transactions.
b. Distributed Transactions
When multiple systems (EIS) are involved, a transaction manager (from J2EE container) external to each EIS controls and coordinates the overall transaction (i.e. ensures a two phase commit). These transactions across multiple resources are referred as XA and are defined in the Java Transaction API (JTA) specification.

* The resource adapter can support local transactions, or both type of transactions and neither type of transaction.
Transaction Management Interfaces to Implement
LocalTransaction - Provides methods for Local Transaction demarcation
XAResource - Provides methods for distributed XA Transaction demarcation

3. Security Contracts (optional)
These security contracts define a secure way to access EIS. Java Authentication and Authorization Service (JAAS) interfaces like Subject, Principal, and Generic Credential etc. are used with the Connection Management Interfaces of the Resource Adapter to achieve this.
The Application server can use two methods to authenticate to an EIS system (via a resource adapter)
a. Container Managed Sign On
In this method the resource credentials are defined in the resource adapter deployment descriptor and the application server uses those credentials to connect to EIS
b. Component Managed Sign On
In this method the application provides the required security credentials each time a connection is acquired from the resource adapter.

Security Management Interfaces to Implement
GenericCredential -Provides methods to access the security credentials of the user
EIS specific Contracts
The resource adapter communicates with the EIS using the EIS specific protocol. The J2EE Connector does not specify a protocol or an interface between a resource adapter and EIS. The adapter can use CORBA, SOAP, XML and RMI etc. as supported by EIS to access it. The resource adapter also has to handle marshalling and un-marshalling between EIS and Java Data Types.

Application Component Contracts
Application uses the client API to access the EIS. A resource adapter can either implement the Common Client Interface (CCI) or it can implement an API specific to EIS or itself.
The CCI interfaces are divided into four sections:
a. Connection Interfaces
API encapsulates interfaces for establishing a connection to an EIS
b. Interaction Interfaces
API encapsulates interfaces for sending command or queries to EIS
c. Record / ResultSet Interfaces
API encapsulates interfaces to retrieve command or query results as returned from EIS
d. Meta Data Interfaces
API encapsulates interfaces to query EIS's metadata.

Packing Resource Adapter
The packing of resource adapter includes packing the resource adapter implementation classes, client API implementation classes, dependent external libraries (optional) and a resource adapter deployment descriptor into Resource Archive (RAR) file using the Java Archive (JAR) format. The way to deploy of the .rar file depends on application server.

Example: The resources adapter adapter.rar might include the following files:
META-INF/ra.xml - Deployment Descriptor
AdapterImpl.jar - Adapter Implementation
ClientAPI.jar - Client API Implementation
DependentAPI.jar - Dependent API

The resource adapter includes an XML deployment descriptor file. The application server relies uses this information to properly deploy and interact with the resource adapter. The deployment descriptor contains information about:
a. General Information about Resource Adapter
b. Interface and Implementation Classes
c. Transaction support level
d. Authentication Information
e. Configuration Properties

Sample ra.xml

Deploying Resource Adapter
The resource adapter can be deployed to the WebLogic Server via the Weblogic Server Administration Console.
Step 0:
Launch and Sign in into Weblogic Sever Console
Expand the Domain Leaflets where you want to deploy the adapter.
Expand the Deployment Leaf under that Domain
Click on the Connector Leaf and the deployment wizard appears on the right frame.
Click on Configure New Connector component to launch the wizard.

Step 1:
Manually Copy or Upload the .rar file via console to an appropriate directory. Generally all these application go under directory $domainHome/applications
Step 2:
Select the .rar file which was uploaded or copied in Step1 that you would like to configure and deploy

Step 3:
Select the Servers to which the connector has to be deployed

Step 4:
Give the name for the application connector

Step 5:
Click on Configure and Deploy button to start the process.

If there is some problem with the deployment, the Weblogic Server throws the exception, which can be analyzed and fixed and finally the above steps can be repeated again for deployment.
If there are no errors, Weblogic Server gives confirmation about proper deployment of the connector.

Sample Code
This sample code describes Application Component code to Connection Lookup, creating Interaction and getting results using the CCI Interface.

// connection and interaction
javax.resource.cci.Connection con = null;
AdapterInteraction intr = null;

String exception = null;
String min = null;

// retrieve initial context
InitialContext ctx = new InitialContext();
__log.debug("Retrieve the Initial Context");

// get the connection factory
Object obj = ctx.lookup(IJNDINames.ADAPTER_CONNECTION_FACTORY);

__log.debug("Lookup Connection Factory JNDI...");

//type cast
AdapterConnectionFactory fact = (AdapterConnectionFactory)obj;
__log.debug("Object type casted into Connection Factory...");

//create adapter connection spec
AdapterConnectionSpec spec = new AdapterConnectionSpec();
spec.setUser("adapter-username ");
spec.setUser("adapter-password ");

// get the adapter connection
Object objConn = fact.getConnection(spec);

// type cast
__log.debug("Type cast object into cci connection");
con = (javax.resource.cci.Connection)objConn;

//create the interaction
__log.debug("Create a new Interaction from the connection");
intr = (AdapterInteraction)con.createInteraction();

// create interaction spec
__log.debug("Create a new Interaction Spec");
AdapterInteractionSpec specInt = new AdapterInteractionSpec();
specInt.setServiceType(ISAInteractionSpec.SERVICE_TYPE);

// create input record
__log.debug("Create a new ISA Record");
ISARecord recIn = new ISARecord();
recIn.setRecordName(name);
recIn.setParameter(param);

// execute the interaction
__log.debug("Execute the Interaction Service");
AdapterRecord recOut = (AdapterRecord)intr.execute(specInt,recIn);

__log.debug("Retrieved the ISA Record trying to get min");

// get results
param = recOut.getParameter();

Conclusion
JCA connector provides portable solutions for system integration with EIS that can be seamlessly plugged into the BEA application server providing transactional, security and connection management features with ease deployment and maintenance.