BEA Logo BEA WebLogic Java Adapter for Mainframe Release 5.0

  BEA Home  |  Events  |  Solutions  |  Partners  |  Products  |  Services  |  Download  |  Developer Center  |  WebSUPPORT

   http://www.oracle.com/technology/documentation/index.html   |  

 

   WebLogic Java Adapter for Mainframe Documentation   |   JCA Adapter Guide   |   Previous Topic   |  

BEA WebLogic JAM JCA Adapter Guide

 

BEA WebLogic JAM 5.0
Date: April 2002

The WebLogic JAM JCA Adapter 5.0 is a JCA 1.0 compliant adapter which installs into the Connector Container of WebLogic Server 6.1 and provides a standard API interface to WebLogic JAM services.

The WebLogic JAM JCA Adapter implements all functionality documented in the J2EE Connector Architecture Specification Version 1.0 (JSR 016) including support for:

In addition, the following extensions are supported:

 

Pre-requisites

The following software must be installed prior to installing the WebLogic JAM JCA Adapter:

 

Installation

The WebLogic JAM JCA Adapter is delivered from the BEA Download site. The following files are installed:

Installation of the WebLogic JAM JCA Adapter is accomplished by running the installation script using one of the following methods:

Running the GUI-Mode Installation

  1. Download the WebLogic JAM JCA Adapter for the platform you need.

  2. Run the installation program as follows:

  3. A prompt displays for the BEA Home directory. You must install the WebLogic JAM JCA Adapter in a BEA Home directory where WebLogic JAM 5.0 is installed or the installation aborts.

Running the Console-Mode Installation

  1. Download the WebLogic JAM JCA Adapter for the Unix platform you need.

  2. Invoke the following command: 
    sh wljamjca_Unix.bin -i console

  3. A prompt displays for the BEA Home directory. You must install the WebLogic JAM JCA Adapter in a BEA Home directory where WebLogic JAM 5.0 is installed or the installation aborts.

Install and Define the jamjca.jar

The jamjca.jar file must be defined in the WebLogic system CLASSPATH so that WebLogic JAM JCA clients running under the control of the WebLogic Connector Container have access to the classes which are not defined by standard J2EE JCA interfaces.

In addition, many of the features of the WebLogic JAM JCA Adapter require access to DataViews generated using the eGen utility. These DataViews describe the contents of a mainframe data record. It is recommended that a new directory be created in the <JAM_INSTALL_DIR> to contain these classes and that this directory be added to the system CLASSPATH.

For Windows Systems

To accomplish these changes edit the startWebLogic.cmd and make the following changes:

  1. Add the following lines to the script: 
    set JAM_HOME=<Install Directory for WebLogic JAM 5.0>
    set DATAVIEW_DIR=%JAM_HOME%/DataView
    set JAMJCA_JAR=%JAM_HOME%/lib/jamjca.jar

  2. Locate the following line in the script: 
    set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar;<JAM_INSTALL_DIR>\lib\jamjca.jar

    Append this line of code to it.

     
    set CLASSPATH=%CLASSPATH%;%JAMJCA_JAR%;%DATAVIEW_DIR%

For Unix Systems

To accomplish these changes edit the startWebLogic.sh and make the following changes:

  1. Add the following lines to the script: 
    export JAM_HOME=<JAM_INSTALL_DIR>
    export DATAVIEW_DIR=$JAM_HOME/DataView
    export JAMJCA_JAR=$JAM_HOME/lib/jamjca.jar

  2. Locate the following line in the script: 
    CLASSPATH=.:./lib/weblogic_sp.jar:./lib/weblogic.jar;<JAM_INSTALL_DIR>/lib/jamjca.jar

    Append this line of code to it.

     
    CLASSPATH=$CLASSPATH:$JAMJCA_JAR:$DATAVIEW_DIR

Deploying the WebLogic JAM JCA Adapter via the WebLogic Console

Deployment of the WebLogic JAM JCA Adapter via the WebLogic Administration Console is accomplished as follows:

  1. Select the Connectors item in the console tree and then click on Install a new Connector Component in the right hand pane of the WebLogic Administration Console:


     

  2. Enter the path and filename of the jamjca.rar file or use the Browse button to locate the file in the <JAM_INSTALL_DIR>/lib directory and then click on the Upload button:


     

     

  3. The WebLogic JAM JCA Adapter is now deployed:

     

 

Using the WebLogic JAM JCA Adapter

WebLogic JAM JCA Adapter provides a client interface using standard JCA system contracts to access WebLogic JAM services. The following sections provide guidelines for configuration and programming with the WebLogic JAM JCA Adapter.

Configuring the JCA Adapter

After installing the WebLogic JAM JCA Adapter, you may configure it using the Edit Connector Descriptor link of the WebLogic Administration Console. For more information on the Connector Container options in WebLogic Server, refer to the WebLogic Server documentation.
 

Programming Client Applications

Creating client applications which make use of the WebLogic JAM JCA Adapter follows the standard practices for all Connector clients. The general steps are:

  1. Obtain a JAM JCA Connection Factory. In the Managed case this factory is obtained from a Pool maintained by the WebLogic Connector Container. In the Non-managed (stand-alone) case the ConnectionFactory is directly instantiated by the client.

  2. Use the ConnectionFactory to obtain a Connection object.

  3. Using the Connection object, request an Interaction object.

  4. Instantiate an InteractionSpec object used to identify the mainframe service to be invoked.

  5. Create a Record object for the input data to the service and for the response.

  6. Use the Interaction object to execute the mainframe service passing the InteractionSpec, Input Record, and Output Record.

  7. Close the connection.

Example Code

The following listing is simple example code which outlines the previous programming steps for a non-managed (standalone) invocation:

Listing 1 Example Programming Code

 
1. import javax.resource.cci.*;
2. import com.bea.jam.jca.*;
3. String url = "t3://localhost:7001";
4. ConnectionFactory fact = new ConnectionfactoryImpl(url);
5. Connection conn = fact.getConnection();
6. Interaction action = conn.createInteraction();
7. InteractionSpecImpl actionSpec = new InteractionSpecImpl();
8. actionSpec.setFunctionName("sampleRead");
9. actionSpec.setInteractionVerb(InteractionSpec.SYNC_SEND_RECEIVE);
10. RecordFactory rfact = fact.getRecordFactory();
11. XmlRecord input = new XmlRecord("EmployeeRecord");
12. MappedRecord output = rfact.createMappedRecord("EmployeeRecord");
13. String xml = "<?xml version='1.0'?><empRecord><empName><empLastName>Smith
</empLastName></empName></empRecord>";
14. input.setData(xml);
15. action.execute(actionSpec, input, output);
16. conn.close();

Line Number

Description

1 and 2

Import the packages for the J2EE Connector CCI and the WebLogic JAM implementation of these interfaces.

3 and 4

Obtain a connection factory using the URL of the WebLogic Server which is hosting the WebLogic JAM Gateway.

5

Obtain a connection from the connection factory.

6

Use the connection to obtain an Interaction object.

7-9

Create an InteractionSpec object and the following properties:

10

Obtain a record factory which can be used for the creation of Indexed and Mapped Records.

11

Create an instance of an XmlRecord. This is a WebLogic JAM JCA extension which provides support for conforming XML data. This Record object will contain data translation code to convert the XML data to mainframe data.

12

Create an instance of a MappedRecord which will be used to receive the response from the mainframe service.

13 and 14

Set the value of the input XmlRecord to the requested employee last name.

15

Invoke the mainframe service. On successful return the MappedRecord we passed in as output will contain the service response data.

16

Close the connection.

 

Record Types

The WebLogic JAM JCA Adapter supports four types of records for input and/or output when executing mainframe services:

Record Type

Description

Record Name Definition

IndexedRecord

This record always contains a single entry which is a byte array containing the binary data record.

An arbitrary name.

MappedRecord

This record contains a Java Map of name/value pairs.

This Map is created using the WebLogic JAM HashtableLoader and HashtableUnloader classes.

Note: Refer to the WebLogic Java Adpater for Mainframe Programming Guide for more information about these classes.

Must match the name of the DataView class for the record.

DataViewRecord

This record is a wrapper around the WebLogic JAM DataView class.

Must match the name of the DataView class for the record.

XmlRecord

This record converts an XML document to a binary data record using a WebLogic JAM generated DataView class.

Note: Refer to the "Understanding How WebLogic JAM Uses XML" section in the WebLogic Java Adpater for Mainframe Programming Guide for more information about these classes.

Must match the name of the DataView class for the record.

 

 

Samples

The WebLogic JAM JCA Adapter provides two samples: a container-managed connection sample and a non-managed connection sample. These samples are in the following locations:

Container Managed Connections

The Container Managed sample is a simple JSP page that accesses the readSample mainframe service using the EmployeeRecord which ships as a WebLogic JAM 5.0 sample.

Building the Sample

To build the Container Managed sample using ant:

  1. Make sure that the WebLogic bin directory is in your PATH.

  2. Enter the following command to start ant passing the directory where WebLogic is installed. For example: 
    ant -DWLSDIR=d:/bea/wlserver6.1

  3. Copy the generated EmployeeRecord DataView to your DataView directory. For example: 
    copy EmployeeRecord*.class d:\bea\wljam5.0\DataView\.

  4. Install the managedjca.war file.

Running the Sample

After installing the managedjca.war file, use the following HTTP URL to launch the JSP in a browser:

 
http://localhost:7001/managedjca/DisplayEmployee.jsp

The following page displays.
 

Enter a name in the Last Name field and click Submit to access the mainframe and display the returned data.

Non-Managed Connections

The non-managed JCA sample is a command line application, which runs the readSample service and displays results in various formats.

Building the Sample

To build this sample using ant:

  1. Make sure the WebLogic bin directory is in your PATH.

  2. Enter the command to start ant passing the directory where WebLogic is installed. For example: 
    ant -DWLSDIR=d:/bea/wlserver6.1

  3. Copy the generated EmployeeRecord DataView to your DataView directory. For example: 
    copy EmployeeRecord*.class d:\bea\wljam5.0\DataView\.

  4. Make sure the weblogic.jar, jam.jar, and jamjca.jar files are in your CLASSPATH. Also include the current directory in the CLASSPATH.

Running the Sample

Run the sample with the following command line format:

 
java DisplayEmployee <URL of WLS> <Last Name of Employee>

Running this sample does the following:

1. Obtains the JAM JCA metadata classes and displays product name, version, etc.

2. Executes the readSample service returning a MappedRecord. The first and last names are displayed from this response.

3. Executes the readSample service returning an XmlRecord. The resulting XML document displays.

Listing 2 Running Non-managed Connection Sample

 
java DisplayEmployee t3://localhost:7001 Last-1

Product Name: WebLogic Java Adapter for Mainframe
Product Version: 5.0
Support for J2EE Connector Version 1.0

First Name:   New-First
Last Name:    Last-1

<?xml version="1.0"?>
<empRecord>
<empSsn>1</empSsn>
<empName>
<empNameLast>Last-1</empNameLast>
<empNameFirst>New-First</empNameFirst>
<empNameMi>M</empNameMi>
</empName>
<empAddr>
<empAddrStreet>123 Main St.</empAddrStreet>
<empAddrSt>TX</empAddrSt>
<empAddrZip>775550000</empAddrZip>
</empAddr>
</empRecord>


 

Copyright © 2001 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.