onjava-jca

Overview

This example demonstrates how JCA can be used to integrate with legacy applications. Specifically, this example demonstrates a J2EE application accessing an application running on Tuxedo.

A servlet invokes an EJB which issues an JCA interaction to the Attunity resource adapter. The Attunity resource adapter sends the interaction call to the Attunity Connect Adapter server which repackages the data into the appropriate Tuxedo format and invokes the Tuxedo service using Tuxedo's proprietary API. Once the response is received back from Tuxedo, it is reformated and sent back to the EJB through the Attunity resource adapter. The servlet then displays that response.

Preparing Tuxedo for this example

BEA Tuxedo 8.1 should be installed on a machine (called host1 in this example) with the STOCKQUOTE sample service running. The stock quote sample service is shipped with Tuxedo 8.1 distrubution and can be found under the samples/xmlstockquote directory. Follow the README file found in that directory to set up the STOCKQUOTE sample service. In addition, you have to configure the Tuxedo Workstation Listener Server (WSL) to listen on port 8090.

Make sure you have the following entries in your ubbsimple file before you do the tmloadcf step.

...


*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

...

Setting up Attunity Connect Server for Tuxedo

Download Attunity Connect Server for Tuxedo version 4.1 from Attunity.

Install Attunity Connect Adapter for Tuxedo. This should be installed on the same machine where the Tuxedo service is run. The directory where Attunity Connect is installed is referred to as navroot in this document. Please refer to the installation instructions that comes with Attunity Connect for details.

After installation, modify the nav_login.bat script in the Attunity bin directory as follows:

Setting up Attunity Studio

Download and install Attunity Studio version 1.3 from Attunity. This application is available on the Windows platform only.

Defining data structures and interaction

Start up Attunity Studio. The steps below are performed on version 1.3 of Attunity Studio. The steps and screens may be different in differents versions of Attunity Studio.

Step 1: Create a new machine entry for your Attunity Connect server machine

Right click on “Machines” in the Configuration Explorer, and select “Add Machine”.

Enter the physical address, port (enter 2552). Enter proper user name and password for the user that have access to the Tuxedo service. You can log in as anonymous user depending on how the Tuxedo service is configured. Click “Finish”.

Add new machine

Enter new machine details

Step 2: Create a new adapter

Expand the "NAV" Binding. Right click on “Adapters”. Select “New Adapter”. Give it a name and note it down – this would be the name you will use to configure the eisName configuration property in OC4J later when you deploy the Attunity JCA resource adapter. We pick the name "tux" in this example. Select “Tuxedo” as the type. Click on “Finish”.

Add new adapter

Define details of new adapter

Step 3: Define interaction

Right click on your new adapter. Select “Open Import Perspective”. This brings you to the “Metadata Import Explorer”.

Right click on your adapter. Select “New Import”. Enter any import name. Choose “Tuxedo Import Manager Using VIEW Files”. Click “Finish”.

Import meta-data for new adapter

This brings up step 1 of the import process. Click “Next”.

In step 2 of the import process, click “Add Record”. A record with name "Record1" is created. Modify the Field type from "String" to "XML". Leave the "size" field blank. Then hit “Next”.

Define Tuxedo records

Simply hit “Next” in step 3.

In Step 4, you have to define an Interaction. Click “Add”, and fill in “STOCKQUOTE” as name, “sync-send-receive” as mode, “Record1” as both input and output, “XML” as both input and output buffer type. Click the “No Transaction” checkbox. Hit “Next” to go to the next step.

Define an interaction for the Tuxedo example

Hit “Next” in steps 5 and 6.

In step 7, select “Yes” when asked whether you want to transfer the metadata to the server. Then hit “Finish”.

Step 4: Reload configuration for the Attunity Connect daemon

Go to “Runtime Manager” (pulldown menu Window -> open perspective -> runtime manager). Highlight your server and right click. Choose “Reload Configuration”.

Reload the server with the new configuration

Step 5: Test your new interaction

To test your set up. Go back to the “Configuration Explorer”. Open up your host -> Bindings -> your binding name -> Adapters. Right click on your new adapter. Select “Test”. Click “Next” and do the same on the next dialog box. This does a ping test on your new adapter definition.

We are ready to test our new interaction. First save the following test script to a text file, for example, test.xml. An example can be found here.

<?xml version="1.0" encoding="UTF-8"?>
<acx>
  <connect adapter="tux"/>
  <execute interactionName="STOCKQUOTE">
    <Record1>
      <Record1_data>
        &lt;stock_quote&gt;&lt;symbol&gt;ORCL&lt;/symbol&gt;&lt;/stock_quote&gt;
      </Record1_data>
    </Record1>
  </execute>
</acx>

Replace "tux" in the <connect> element with the name of your adapter defined in step 2. On a command line with all the Attunity Connect environment variable set, run nav_util XML. When prompted with an XML input file name, enter test.xml. You should see the following output when your interaction is defined properly:

Installing OC4J 10g (9.0.4)

If you do not already have OC4J 10g (9.0.4) running, please follow these steps to install OC4J 10g (9.0.4) on to your machine.

Download the OC4J 10g (9.0.4) oc4j_extended.zip distribution from http://otn.oracle.com/tech/java/oc4j

Create a new directory for OC4J.

Unzip oc4j_extended_904.zip into the new directory.

Set the J2EE_HOME environment variable to point to the j2ee/home sub-directory in the unzip directory.

Install OC4J by typing

Here is an example showing the configured values in an oc4j-ra.xml file:

<connector-factory location="eis/attunityForTuxedo" connector-name="Attunity Connect Legacy Adapter">
  <config-property name="userName" value=""/>
  <config-property name="password" value=""/>
  <config-property name="eisName" value="tux"/>
  <config-property name="serverName" value="localhost"/>
  <config-property name="workspace" value="Navigator"/>
  <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=""/>
  <config-property name="fakeXA" value="false"/>
</connector-factory>

Restart OC4J for the new configuration to take effect.

Deploying and running the sample application

Download xmlStockAppClient.zip and unzip it into a directory of your choice.

Find the attunityResourceAdapter.jar file. It can be found from the Attunity zip file that contains the resource adapter, or by extracting the Attunity JCA resource adapter archive. Copy attunityResourceAdapater.jar and attunityCoreResourceAdapter.jar to the lib subdirectory under the sample application.

If you do not already have ant, the Java-based build tool from Apache, you will need to download it from http://ant.apache.org and have it installed on your machine.

Set the J2EE_HOME environment variable to point to the j2ee/home directory in your OC4J installation.

Set the JAVA_HOME environment variable to point to a JDK 1.4 installation.

Use ant to build the sample application by typing ant on the directory where you have the sample application tar file extracted. The will build an application archive, attunityClient.ear, under the lib directory.

Deploy the application, attunityClient.ear, and bind the sample application to /jcaTest. You may use the deploy.bat and bindwebapp.bat scripts provided with the example if you wish.

You may use admin.jar to deploy attunityClient.ear and bind it to the /jcaTest name as follows:

Now, you are ready to run the application.

Open a browser and go to http://<your_oc4j machine>:8888/jcaTest/stockAppTest

Enter some string as stock symbol and hit “Submit Query”. The servlet will then invoke an EJB, StockQuote. The StockQuote EJB will issue an JCA interaction to the Attunity resource adapter, which sends the interaction call to the Attunity Connect Adapter server. The Attunity Connect Adapter server then repackages the data into the appropriate Tuxedo format, and invokes the Tuxedo service using Tuxedo’s proprietary API.

Once the Attunity Connect Adapter server receive a response back from Tuxedo, it reformats the Tuxedo response into the return data structure type defined in Attunity Studio, and sends the response back to the EJB through the Attunity resource adapter. The servlet then displays that response on to your browser.

Summary

In this example, you have seen how a J2EE application can utilize JCA to integrate with legacy applications running on Tuxedo.

Example - Integrating with Tuxedo using JCA

Table of Contents

Pre-Requisites