Tutorial: Deploying a JCA Resource Adapter for an EJB Application

Why JCA

Enterprise Information Systems (EIS) transact enterprise level information that can be stored in various formats like ERP systems, databases, and mainframe systems. As more organizations move towards Internet-based businesses, integration between applications and these legacy heterogeneous EIS becomes necessary. But most EIS vendors and application server vendors use non-standard vendor-specific architectures to provide connectivity between application servers and EIS.

J2EE Connector Architecture (JCA) defines a standard architecture for connecting J2EE compliant applications to heterogeneous information systems. The architecture can be used to define Resource Adapters, J2EE components that implements the JCA for a specific EIS.

Back to Top

What are Resource Adapters

A Resource Adapter forms the connecting layer between the enterprise application, application server and the EIS. It is a system-level software driver that is used by a Java application server or an application client, to connect to the EIS. A Resource Adapter is specific to the EIS. In literature, resource adapters are also referred to as Connectors.

Some examples of a Resource Adapter are:

• A JDBC driver to connect to a relational database
• A Resource Adapter to connect to an ERP system
• A Resource Adapter to connect to a transaction processing system

Each EIS requires just one implementation of a Resource Adapter which is created as per the JCA specification. Since the implementation is compliant with the JCA, it is portable across all compliant J2EE servers.

What is a Compliant Resource Adapter

Compliance is defined by the following implementation rules specified in JCA version 1.0:

• Standard set of system-level contracts between an application server and the EIS. These contracts focus on integration aspects like: connection management, transaction management, and security.
• Common Client Interface (CCI) that defines a client API for interacting with multiple EIS.
• Standard deployment and packaging protocol for resource adapters.

Back to Top

Implementing JCA

About JCA Contracts

The Connector Architecture provides these contracts:

• System contracts between the application server and the resource adapter in the form of connection pooling, transaction, and security.
• Application contracts between the client and the resource adapter.

In addition, there is an EIS specific interface between the resource adapter and the EIS.

A resource adapter interacts with a J2EE server with system contracts defined as per the JCA 1.0 specification. These are transparent to the J2EE component. The system contracts link the resource adapter to important services like - connection, transaction, and security. These services are managed by the J2EE server.

The connection management contract supports connection pooling. Connection objects are pooled by the application server. This provides a scalable application environment that can support a large number of clients requiring access to an EIS. Using connection factories, connection is obtained between the application and the EIS through the application server. On receiving a client request, connections are given to the client from the pool. After use, these connections are released by the client and are put back in the connection pool.

The transaction management contract allows an application server to use a transaction manager to manage transactions across multiple resource managers. A resource manager represents an EIS. Transactions managed by the transaction manager external to the resource manager, in this case the transaction manager in the application server, are called global or XA transactions. This contract also supports local transactions that are managed internally by a resource manager.

The security management contract provides authentication, authorization and secure communication between the J2EE server and the EIS.

Back to Top

Managed and Non-managed Environment

There are two types of client access scenarios: managed and non-managed.

In a managed environment, the application server takes over the management of the connection objects. When the client makes a call to the Connection Factory, it is routed to the Connection Manager. The Connection Manager requests the Managed Connection Factory to obtain a connection object.

In a non-managed environment, an application client directly uses the resource adapter to access the EIS.

Back to Top

JCA Interfaces

The Connector architecture includes the following interfaces:

• ConnectionFactory: Repository of connection objects. This is implemented by the resource adapter.
• ConnectionManager: Implemented by the application server to manage connections and transactions in a managed environment.
• ManagedConnectionFactory: Implemented by the resource adapter and used to decide and return the connection object that is suitable to the client.
• Connection: Implemented by the resource adapter, this interface is the object that allows access to the EIS.
• ConnectionEventListener: Each connection instance is associated with this interface. This is used by the application server to get information from a connection instance and manage the connection pool.

To get a connection to the EIS, the client does a look up of the connection factory in the JNDI namespace. In a managed environment, the client invokes the getConnection method and the Connection Factory (CF) sends the connection request to the ConnectionManager (CM). The connection manager routes the request to the Managed Connection Factory (MCF). The MCF decides if the connection objects existing in the connection pool match the connection request from the client. If there is a match, the connection object is returned to the client. However, if there is no match, the connection manager creates the required connection object using the MCF. This new connection object is now a part of the connection pool. The MCF then returns the connection object to the client through the CF.

Each connection object is associated with a ConnectionEventListener interface. Any change in the connection status is passed to the application server through this interface.

The application client uses the connection to access the EIS. The connection is enlisted in the regular application server started transaction (in the case of local and XA transactions). Information exchange between the client and the EIS now takes place.

After the client closes the connection, the change in status is passed to the application server through the ConnectionEventListener interface. The connection object is then returned to the connection pool for reuse.

Back to Top

Package Resource Adapters

A resource adapter is packaged in a Resource Adapter Archive (RAR, archived with extension .rar) and can be deployed on any J2EE server. A RAR can be further packaged in an EAR as part of an application, or deployable as a standalone archive.

Resource Adapter Archive Components

After deployment, the standalone resource adapter files are located in <install_dir>\server\nodes\StandAlone\<server name>\config\connector.

If the resource adapter is part of an application, the files are located in <install_dir>\server\nodes\StandAlone\<server name>\archives\<application name>\connector\.

If the resource adapter is deployed on a cluster node, the path to the resource adapter is the same, except replace \StandAlone with \Cluster.

The files and directories contained in a RAR file are:

Back to Top

Resource Adapter Descriptor File (ra.xml)

Similar to web application and EJB applications, a resource adapter has a descriptor file that contains the resource adapter specific parameters. These parameters are defined based on the JCA specification. The resource adapter descriptor file (ra.xml) is located in <install_dir>\server\nodes\StandAlone\<server name>\config\connector\application.rar\META-INF\.

If the resource adapter is part of an application, the files are located in <install_dir>\server\nodes\StandAlone\<server name>\archives\<application name>\connector\<RAR name>\META-INF\.

If the resource adapter is deployed on a cluster node, the path to the resource adapter files is the same except replace StandAlone with Cluster.

This file contains:

• Generic information about the resource adapter like
• Name
• Type of EIS
• Vendor name
• Connection factory details like
• Connection factory interface
• Connection factory implementation class
• Connection interface
• Connection implementation class
• Configuration properties like
• Name
• Type and
• Value
• Authentication information

Back to Top

Resource Adapter Configuration File

In addition to the descriptor file (ra.xml), the resource adapter has a Pramati specific descriptor file connector-config.xml. It contains the name of the resource adapter and the configuration details of all the connection factories that are bound to it. The configuration details are:

• JNDI name.
• If authentication is application or container managed. If it is container managed, the user name and password.
• The maximum size of the connection pool, for the connection factory.
• The configuration properties.

Configuration properties are (name, value) pairs containing information specific to the resource adapter and the associated EIS. These properties are defined in the deployment descriptor of each file. By changing the value of these properties, you can connect to different EIS.

This file is located in the location: <install_dir>\server\nodes\StandAlone\<server name>\config\connector\<RAR name>\

If the resource adapter is part of an application, the files are located in <install_dir>\server\nodes\StandAlone\<server name>\archives\connector\<RAR name>\

If the resource adapter is deployed on a cluster node, the path to the resource adapter files is the same except replace \StandAlone with \Cluster.

Back to Top

Using Resource Adapters in an Application

Usage Scenario

In a typical enterprise usage scenario, to integrate a client with an EIS, you need to:

1. Obtain a resource adapter that is specific to the required EIS.
2. Deploy the resource adapter on the application server.
3. Define and bind a connection factory for the resource adapter in the server namespace.
4. Use the client API that is provided by the resource adapter to access data from the information system.

The resource adapter acts as a factory of connections. An application client uses a connection factory to access a connection instance, which it then uses to connect to the EIS.

Back to Top

About Client Interfaces

The client interface used by enterprise applications and resource adapters for connecting to heterogeneous EIS can be of two types:

• Common Client Interface (CCI) defined as per JCA specification that supports a common client API across heterogeneous EIS.
• A client interface (non-CCI) that is specific to the resource adapter and the associated EIS.

The main interfaces in CCI are:

• javax.resource.cci.ConnectionFactory (for connection factory implementation)
• javax.resource.cci.Connection (for connection implementation)

ConnectionFactory is an interface that allows an application client to get a connection to an EIS instance.

Sample code

//obtain application server specific naming context

Context ic = new InitialContext();
javax.resource.cci.ConnectionFactory cf = javax.resource.cci,ConnectionFactory)ic.lookup("myconnfact");
javax.resource.cci.Connection con = cf.getConnection();
//use the connection object to access data using CCI
con.doSomething();.........

//Finally close the connection

con.close();

Example of a non-CCI interface:

//For ConnectionFactory interface javax.sql.DataSource;
//For Connection Interface java.sql.Connection
//Obtain application server specific naming context

Context ic = new InitialContext();
javax.sql.DataSource ds = (javax.resource.DataSource)ic.lookup("myconnfact");
java.sql.Connection con = cf.getConnection();
con.doSomething();.........

//Finally close the connection

con.close();

Also,

//For ConnectionFactory interface com.myeis.SomeConnectionFactory;
//For Connection Interface com.myeis.MyConnection
//Obtain application server specific naming context

com.myeis.SomeConnectionFactory cf = (com.myeis.SomeConnectionFactory)ic.lookup("myconnfact");
>
com.myeis.MyConnection myCon = cf.getConnection();

//Use the connection object to access data using the API provided by the connection interface

myCon.doSomething();
...

//finally close the connection

myCon.close();

Back to Top

Pramati JCA Implementation

Pramati Server implements the system contracts defined for application servers as per the JCA specification. You can download the specification from http://java.sun.com/j2ee/download.html#connectorspec

Pramati Server JCA implementation has the following features:

• It is based on JCA 1.0 specification.
• Supports connection, transaction and security contracts.
• Supports deployment of both standalone resource adapter and also a resource adapter that is part of an application.
• Supports local transaction optimization which is an optional requirement according to the JCA specification. When only one resource adapter is involved, instead of using a global transaction, a local transaction is started, avoiding a global transaction overhead.
• Security contract supports only.

• Password credential interface

• Basic password authentication mechanism that is specific to an EIS.

Back to Top

Install Sample

1. Download the sample application (*.zip).
2. Extract the files into a local directory.
3. Extracted files include the RAR blackbox-tx.rar, the application Connector.ear, and the application with embedded connector, ConnectorApplication.ear. These files will be deployed on the Server.

Back to Top

Deploy Sample Connectors

This tutorial discusses both standalone resource adapters and resource adapters that are stored as part of an application deployed on Pramati Server. The sample resource adapter shipped with this tutorial is one supplied by Sun Microsystems as part of the Java^TM 2 Enterprise Edition Reference Implementation (RI). You can download it from http://java.sun.com/j2ee/sdk_1.3/.

The sample application can access customer information from a JDBC database. This tutorial assumes a Windows environment. Enter the values as specified in this tutorial.

Back to Top

Start the Server

When you install Pramati Server, a default configuration is created for you. When you do not specify a Server to start, the default server starts. The default server has the following standard configuration:

• Server name: default
• Host: Localhost
• Lookup Port: 9191
• HTTP Port: 8181
• User name: root
• Password: pramati
• Realm: system

To start Server:

1. Open a DOS window and change directory to <install_dir>\server\bin
2. Run setup.bat. This sets the classpath for the Server to start.
3. Enter cd.. to return to <install_dir>\server
4. Run the command java -Djdbc.drivers=COM.cloudscape.core.JDBCDriver com.pramati.J2eeServer -shell -verbose. The Server starts. The Cloudscape driver is registered. The default prompt appears.

Note: You need to register the required database driver before deploying the resource adapter. For the Cloudscape database used for this tutorial, the driver is COM.cloudscape.core.JDBCDriver.

Back to Top

Deploy the Resource Adapter

Archives (WAR, JAR, EAR and RAR) can be prepared and deployed on Pramati Server through the Deploy Tool.

To deploy the resource adapter:

1. Start Pramati Deploy Tool from the default prompt: default:>deploytool.
2. Select Archive > Open from the main menu of the Deploy Tool.
3. Enter the name and location of the RAR. The name of the RAR is blackbox-tx.rar.
4. Select Archive > Deploy.

The RAR is deployed.

Back to Top

Viewing the Deployed Resource Adapter

1. Open a browser and enter the URL http://localhost:8181/admin/login, where 8181 is the port on which Pramati Web Container is listening. This will bring you to the login page of Pramati Server Management Console.
2. Enter the user name and password as root and pramati. Click on Login to enter the default server home page.
3. Click on the Applications link in the left hand Explore Panel. This will bring up the list of applications currently deployed on the default server.

blackbox-tx.rar is listed on the Applications page.

List of applications showing the deployed RAR. Click to enlarge.

Back to Top

Add a Connection Factory

Server management operations such as adding a connection factory is done via Pramati Server Management Console.

1. In the Explore Panel, expand the Resources node and click on Connectors link. This will open the connectors home page.
2. Under the list of connectors defined on the Server, click + symbol. The Connector Resource : New page appears to add a Connector.


Adding a connection factory. Click to enlarge.

3. Enter jcademo as the JNDI name for the connection factory.
4. Select the resource adapter as blackbox-tx.rar.
5. Specify if the authorization of the connection factory is given by the application or the Container. Enter user name and password if it is Container. However, for this sample do not specify these details.
6. Enter the maximum size of the connection pool as 40 and click on Next>>.


Database URL for the connector. Click to enlarge.

7. Specify the value of the ConnectionURL properties as jdbc:cloudscape:<install_dir>\server\samples\sample_db.
   Note: By changing the value of this property, you can connect to different JDBC databases.
8. Click Save.

The connection factory is defined and bound for blackbox-tx.rar in the server namespace.

Back to Top

View the Connection Factories

From the server default prompt, run the command default:>status. This fetches a status report on the Server. In addition to other information, you see the following details:

Back to Top

Test the Resource Adapter

To test the resource adapter, deploy the sample application on the server and use blackbox-tx.rar to access a JDBC database. This involves two steps:

• Deploy the sample application
• Access the application

Back to Top

Deploy the sample application

1. Start deploy tool by running the command default:>deploytool.
2. Select Archive > Open to load the sample application archive Connector.ear.
3. To deploy the application, select Archive > Deploy.

The application is deployed and ready to be accessed.

Deploying RAR from Deploy Tool. Click to enlarge.

Back to Top

Access the application

1. Open a browser and enter the URL http://localhost:8181/ConnectorWeb/index.jsp, where ConnectorWeb is the context root for the application. The Pramati JCA Sample page appears.
2. To add a new customer, select Add Customer and enter the required details.
3. Return to the main page and click View to see the new customer details.

The sample application uses blackbox-tx.rar to connect to the customer database and view data.

Back to Top

Undeploying the Resource Adapter and Application

To undeploy the resource adapter:

1. From the Console, click on the Applications link and select blackbox-tx.rar.
2. Click the - symbol.

The resource adapter is undeployed. The connection factories that were bound to the resource adapter are unbound.

Note: You can enter status at the default prompt to verify that the connection factories are no longer bound to the resource adapter.

To undeploy the application, follow the same procedure by selecting Connector.ear.

Note: You must undeploy both blackbox-tx.rar and Connector.ear before proceeding with deploying the sample resource adapter contained in application. This is because in this sample, both share the same ConnectionFactory name and context root.

Back to Top

Deploying a Resource Adapter in an Application

1. In the Deploy Tool, select Archive > Open.
2. Open the application containing the resource adapter, which in this case is ConnectorApplication.ear.

The number of pending deployment tasks required to be completed is shown in the status bar of the Deploy Tool. iN this sample, the only task that needs to be resolved is adding a connection factory.

Deploying app with embedded RAR. Click to enlarge.

Back to Top

Add a connection factory

1. In the Deploy Tool, click on the deployment task button. This will take you to the RAR configuration panel.
2. Select blackbox-tx.rar file and click Configuration.


Connection factory for embedded RAR. Click to enlarge.

3. Enter jcademo as the JNDI name that is bound to the connection factory.
4. Enter the maximum size of the connection pool as 40.
5. Specify if the authorization of the connection factory is application or container managed. Enter user name and password, if it is container managed. However, for this sample, you need not specify these details.
6. Specify the value of the ConnectionURL properties as jdbc:cloudscape:<install_dir>\server\samples\sample_db. By changing the value of this property, you can connect to different EIS.

7. Click Add.

   The connection factory is defined and bound for the blackbox-tx.rar. All the tasks are now resolved.

8. Click Archive > Deploy

The resource adapter is deployed along with the application and the connection factory is bound to the application.

Back to Top

Access the Application

To access the deployed application:

1. Open a browser and enter http://localhost:8181/ConnectorWeb/index.jsp, where ConnectorWeb is the context root for the application.

   The Pramati JCA Sample page appears.

2. To add a customer, click Add Customer.
3. Return to the Main page and click View to see the new customer details.

Back to Top

Deploying a Resource Adapter on a Cluster Node

On Pramati Server, deploying a resource adapter on a Cluster Node is the same as deploying on a Standalone Server. However, these additional factors are valid:

• A resource adapter deployed on one node is available to all the nodes of the cluster.
• Even if a Cluster Node (say N2) is shutdown when the resource adapter is deployed on another cluster node (say N1), the resource adapter is available on N2 after you start it.
• Connection factories are available on all the nodes of a cluster.

Back to Top

Connecting to Other Databases

To use this sample application and resource adapter, and connect to a database other than Cloudscape:

1. Use the SQL script init.sql in the samples directory to create the customer data table.
2. Register the database driver that is specific to the database when you start the server. For an Oracle database, it is java -Djdbc.drivers=oracle.jdbc.driver.OracleDriver com.pramati.J2eeServer -shell -verbose
3. When you add the connection factory, specify the appropriate value for the ConnectionURL property. For an Oracle database, it is jdbc:oracle:thin:@[hostname]:1521:SID

Back to Top