HomeDigital EditionSys-Con RadioSearch Java Cd
Advanced Java AWT Book Reviews/Excerpts Client Server Corba Editorials Embedded Java Enterprise Java IDE's Industry Watch Integration Interviews Java Applet Java & Databases Java & Web Services Java Fundamentals Java Native Interface Java Servlets Java Beans J2ME Libraries .NET Object Orientation Observations/IMHO Product Reviews Scalability & Performance Security Server Side Source Code Straight Talking Swing Threads Using Java with others Wireless XML

WebSphere Column, by Brady Flowers

Last month in JDJ (Vol. 6, issue 5) we looked at the Java 2 Platform, Enterprise Edition (J2EE) connector architecture (JCA) and its common client interface (CCI). To recap, JCA is the part of the J2EE 1.3 specification that facilitates the integration of Java applications with Enterprise Information Systems (EISs). The term EIS refers to a number of systems such as ERP, legacy databases, or transaction processing systems.

As we saw in the last issue, integrating these systems into a modern e-business architecture is complicated, to say the least. The APIs that these systems provide, if they provide one at all, are in general proprietary and require the developer to reinvent the process for each and every system that needs integration. JCA is Sun's proposed solution to this problem. It should do for EIS integration what JDBC did for relational database access.

As the vendor of CICS, MQSeries, Encina, IMS, and Host on-Demand, IBM has a vested interest in EISs. Since 1998 they've delivered a framework for accessing them (and SAP R/3) in VisualAge for Java. That product's Enterprise Access Builder for Transactions (EAB) feature and the common connector framework (CCF) bear a striking resemblance to JCA and CCI and it's easy to see why; IBM is a member of the expert group conferring with Sun on JCA.

Both JCA and CCF define abstract objects for connections, interactions, transaction management, and input and output structures. They both assist the application server to better manage resources, such as connection pools for the EIS connections.

At present there's one big difference. JCA isn't formally released yet and it's not implemented by any application server or tool vendor. EAB and CCF are available now, robust and mature. If you need to integrate any of the EAB-supported EISs, you can leverage the power of this framework now. Of course, since JCA is still a draft specification, you may need to make some changes to your applications when the architecture is finalized.

The ADDER Example
To illustrate EAB we'll use it to develop a set of classes in VisualAge for Java. These classes will encapsulate a single back-end transaction. For simplicity, we'll use a sample CICS transaction that comes bundled with VisualAge for Java. If you have a CICS host available, you can actually compile and link the transaction into the CICS subsystem to try it out.

The name of the CICS program is ADDER. It accepts two integer values for input and returns their sum. The COBOL source, located in the file <VAJavaRoot>\eab\samples\com\ibm\ivj\examples\eab\adder\adder.ccp, defines this record structure:

02   op1     PIC   S99999   DISPLAY.
02   op2     PIC   S99999   DISPLAY.
02   res     PIC   S99999   DISPLAY.
02   keyNum     PIC   X(5)   DISPLAY.

To make sure that the required features are installed into your workspace, start VisualAge for Java and press F2 to open the Quick Start dialog. Select "Features->Add Feature" and then select "IBM Enterprise Access Builder Library" and "CICS Connector." If you don't see one or both of these, the feature is already installed and you can move to the next step. If you're using a different example, make sure you install the connector for your EIS.

Create a project and package for the generated code. I called my package jdj.june01.eab. From the package's pop-up menu select "Tools->Enterprise Access Builder->Import COBOL to Record Type." Figure 1 shows a page from this dialog. Use the Browse button to navigate to the adder.ccp file. On the last page of the dialog make sure that "Create record from record type" is selected, name the output class "AdderRecordType", and click Finish. This will generate your AdderRecordType and AdderRecord.

Figure 1

To create the command bean, select "Tools->Enterprise Access Builder->Create Command". Name the class EABAdderCommand, select "Edit when finished", and click Finish. This creates the command class and immediately starts the Command Editor as shown in Figure 2.

Figure 2

We must specify connection information. Right-click on "Connector" and select "Add ConnectionSpec". Use the Browse button to list all available connection specs for the connectors you've installed. Select "CICSConnectionSpec". When you highlight CICSConnectionSpec in the top-right window, its properties appear in the bottom window. In the URL field, enter the name of the gateway used to connect to the server. In the CICSServer field enter the name of the CICS server.

To specify the interaction right-click on "Connector" and select "Add InteractionSpec". This time select "ECIInteractionSpec" and, in its properties, enter "ADDER" for the programName property.

Next we specify the input and output beans. Right-click on "Input" and select "Add Input Bean". Make sure "Implements IByteBuffer" is selected and use the "Browse" button to select AdderRecord. IByteBuffer is a special superclass that knows how to parse COBOL COMMAREAs and other byte-buffer types of data records. Specify an AdderRecord for "Output" as well. Now, select the input bean from the upper-right pane so its properties appear in the bottom pane. Right-click the "op1" property and select "Promote property". This causes the code generator to create getOp1() and setOp1() methods, which delegate to the input bean methods. Likewise promote the "op2" property of the input bean and the "res" property of the output bean.

Test the EAB Command
Normally we'd have to write a class to test our code. The Enterprise Access Builder relieves us of this task, not to mention the chore of debugging the test code. It has a built-in test client that we can execute from the Command Editor or from the Enterprise Access Builder menu. After launching the test client, select "Command->Create new instance" to get a list of all classes in our workspace that inherit from com.ibm.ivj.eab.command.CommunicationCommand. Pick EABAdderCommand from the list. The test client instantiates the class and displays the dialog you see in Figure 3. From here you can inspect and adjust any of the properties of EABAdderCommand. Set the inputs op1 and op2 to some values and invoke the command from the "Selected" menu. Assuming all goes well and you have your CICS gateway set up correctly, you should see the results in "res".

Figure 3

After only a few minutes of work and with no handwritten code, we now have a command object that can be used from client Java code with just a couple lines of setup:

EABAdderCommand cmd = new EABAdderCommand();
cmd.getCeConnectionSpec().set... // set any required properties
cmd.getCeInteractionSpec().set... // set any required properties
try {
System.out.println("Result = " + cmd.getRes());
catch (Exception e) {}

What can we do now to leverage the power of EAB and still be able to migrate to a JCA implementation later? In addition to different class and package names, we have architectural and philosophical differences that are nontrivial:

  • JCA connections are created by a ConnectionFactory that was obtained via a JNDI lookup, while EAB handles connections via the com.ibm.connector.Communication class.
  • The JCA interaction behaves like a combination of the EAB interaction and the EAB command.
  • In JCA, local transactions are accessed and controlled through a LocalTransaction object obtained from the connection; in EAB the RuntimeContext handles transactional boundaries and scope.
  • Unlike EAB, JCA has the notion of result sets.

Reprising a Command Performance
We could write all the code to implement the CCI classes with the EAB code providing the "plumbing." We could, but we won't because:

  1. It's a lot of work and hard to do, not to mention hard to do correctly.
  2. JCA isn't finalized; our code may become obsolete at any moment.
  3. The vendor or another party will provide a cleaner, more robust JCA implementation for us sooner or later.
  4. Did I mention it's a lot of work and hard to do?
One solution would be to reuse the notion of command. The command pattern characterizes any activity by wrapping it in a straightforward interface. We have "setters" for input values to the command, an execute() method, and "getters" for resulting values.

In the example code (listings are located below) we've defined a command interface and an associated CommandException class in its own package. The command interface is intended to be generic, to serve as a front end for both our EAB-generated classes and any future JCA-based implementations. We'll address only those features we need right now: the ability to set input parameters, to execute the EIS transaction, to read output results, and to handle exceptions if they occur. Our design is generic so we can add other JCA features when we need them.

The command interface and CommandException are located in the jdj.june01.command package in the code listings. We've written jdj.jun01.eab.AdderCommand to implement the command interface. It contains an EABAdderCommand to do the work and "promotes" the relevant properties of the input and output records, making them accessible to the client code, and implements the execute() method and exception handling. We've included a main() method for testing; all you need to do is fill in the server properties for your system and execute it.

When it's time to make our sample work with a JCA infrastructure, we need to create only an AdderCommand that uses JCA. The client code won't have to change. In the package jdj.june01jca there's an AdderCommand that shows what this would look like.


  1. The JCA specification and information on CCI: http://java.sun.com/j2ee/connector/
  2. IBM documentation for the Enterprise Access Builder for Transactions: www7.software.ibm.com/vad.nsf/Data/Document3852
  3. Gamma, E., Helm, R., Johnson, R., and Vlissides, J. (1995). Design Patterns. Addison-Wesley.
Author Bio
Brady Flowers is a software IT architect with IBM's WebSpeed team specializing in WebSphere, Java, and the rest of IBM's suite of e-business applications.
[email protected]

Download Assoicated Source Files (Zip format ~ 12.1 KB)

All Rights Reserved
Copyright ©  2004 SYS-CON Media, Inc.
  E-mail: [email protected]

Java and Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. SYS-CON Publications, Inc. is independent of Sun Microsystems, Inc.