Generating WebSphere Optimized Local Adapters inbound Java session beans

WebSphere Optimized Local Adapters (WebSphere Optimized Local Adapters) inbound Java beans can be called from external applications running in CICS, IMS, batch, and UNIX system services. This topic contains the steps to generate a WebSphere Optimized Local Adapters target Java bean that sets up an object that maps the contents of the passed in byte area over an existing COBOL copy book.

Before you begin

Important: J2C beans are formally supported and tested on WebSphere® Application Servers. Use in other Java™ environments should work, but are not tested extensively. If there are issues with the generated code and it can be isolated as such within a WebSphere Application Server environment, then it will be supported.

About this task

WebSphere Optimized Local Adapter inbound Java beans can be called from external applications running in CICS, IMS, batch, and UNIX System Services. The same Java bean can be developed and called from any of these environments. In addition, the Java bean can also be called by using standard Java remote calling methods, for example RMI over IIOP. The unique feature of the WebSphere Optimized Local Adapters Java bean, which streamlines the execution of the WAS z/OS environment when called from external address spaces, is that it is an implementation of the com.ibm.websphere.ola.ExecuteHome home interface and the com.ibm.websphere.ola.Execute remote interface. It must contain a method called execute() that receives a byte array as input and returns a byte array as its response.

Use the workbench to generate a WebSphere Optimized Local Adapters target Java bean. The workbench generates an Java 3.1 style target Java bean. The generated source contains an @RemoteHome(com.ibm.websphere.ola.ExecuteHome.class) annotation above the Java class name. The workbench also generates the Java name using the @Stateless(mappedName="<Java JNDI name>") annotation. It is this Java home name that the calling application in CICS, IMS, or batch environments need to pass as the WebSphere Optimized Local Adapters service name on the WebSphere Optimized Local Adapters Invoke or Send Request APIs.

You can also use the workbench to generate a WebSphere Optimized Local Adapters target Java bean and helper classes that aid in working with the passed-in byte array and returned byte array. The COBOL copy book, PL/I structure, or C structure can be passed as inputs during the creation process of the WebSphere Optimized Local Adapters Java bean. The workbench will generate code to inflate an object that provides simple access to the various parts of the copy book or structure.

Procedure

  1. Select File > New > Other > J2C.
  2. Click WebSphere Optimized Local Adapter (IBM:2), and click Next.
  3. On the Connector Import page, in the Connector Project field, accept the default value of ola; in the Target Server field, select the WebSphere Application Server version to use, and click Next.
  4. On the Adapter Style page, select Inbound, and click Next.
  5. On the Connection Properties page, type the JNDI name for the target Java bean. This name is used in the @Stateless(mappedName="#Java JNDI name>") annotation. Click Next.
  6. On the J2C Java Bean Output Properties page, type a name for the Java project, and click New.
    1. On the Java Project page, the name that was entered for the project in the New J2C Java Bean page is displayed in the Name field. Ensure that it is correct. If the project name is not displayed, type the project name in the Name field.
    2. In the Name field, type a name for the Java project. To change the default Project location, click the Browse button to select a new location.
    3. In the Target runtime field, select the version of WebSphere Application Server to deploy to. This selection affects the compilation and runtime settings by modifying the class path entries for the project.
      Note: If you specify a new EAR project name, the EAR project is created in the default location with the lowest compatible Java EE version based on the version of the project being created. To specify a different version or a different location for the enterprise application, use the New Enterprise Application Project wizard.
    4. Accept the default Java Module version, or select a different version from the list. If you are creating J2C inbound applications, you must select Java 3.0.
      Important: If you select Java 3.0, the Java 3.0 wizard by default creates a local interface. To create a remote interface, create it manually by adding the @Remote(class= interface.java) annotation to the J2C bean.
    5. In the Configuration field, accept the default configuration, or click Modify and change the project facets for the project.
    6. To add the Java project to an EAR project, select Add project to an EAR.
    7. Choose the EAR project to add the Java module to, or type the name of a new EAR project in the EAR Project Name field, and click Next.
    8. On the Java Module page, in the Source folder field, accept the default for the source folder, ejbModule, or type a different source folder name for the Java project, and click Next.
    9. On the Configure Java module settings page, do these tasks:
      1. To keep the client interface classes for the enterprise beans in a separate Java client JAR file, click the Create an Java Client JAR module to hold the client interfaces and classes. This Java client JAR file is added to the enterprise application as a project utility JAR file.
      2. In the Name field, accept the default name of the Client JAR module, or type a different name.
      3. In the Client JAR URI field, accept the default name of the Client JAR file, or type a different name.
    10. Click Finish.
  7. In the J2C Java Bean Output Properties page,
    1. in the Java Project name field, ensure that the project name is correct or type the correct project name.
    2. in the Packkage name field, type your package name.
    3. in the Stateless Session Java name field, type your stateless session Java name.
    and click Next.
  8. In the Java Methods page, click Add... to create a Java method.
  9. On the Java Method page,
    1. in the Input Type field, click Browse to find an input or click New to create a new one.
      1. On the Data Import page, in the Choose mapping field, select COBOL to Java.
      2. in the COBOL file field, click Browse to locate your COBOL file, and click Next.
      3. On the Importer page, in the Platform field, select z/OS, in the Code page field, select IBM-1047, and in the Data structures field, select the data structure that you want to use, and click Next.
    2. On the Saving Properties page, ensure that the values you want for the helper class appear, and click Finish.
  10. Click Finish and then click Finish once more. The target WebSphere Optimized Local Adapters inbound Java session bean has is generated along with the associated helper class, to assist your implementation with accessing the passed in byte array.

Results

Sample Java class
Here is a sample RAD generated WebSphere Optimized Local Adapter Java called CustomerGet created with a JNDI name of CustomerGetDetails and that has a helper class called CUSTOMER that was generated form a COBOL copy book that had a Level 01 mapping called CUSTOMER:
      package com.ibm.rad.ola.test;
      import javax.annotation.Generated;
      import javax.ejb.RemoteHome;
      import javax.ejb.Stateless;
      import com.ibm.xmlns.prod.websphere.j2ca.sap.sappeaddress1139792376.SapPeAddress;
      import com.ibm.xmlns.prod.websphere.j2ca.sap.sapreturn468436650.SapReturn;
      
      @Generated(comments = "This code should not be modified directly with the exception of the business method bodies. To change annotation value use the Annotation View. To regenerate re-run J2C Bean wizard flow. Please save business methods implementations before regenerating.", date = "Tuesday, November 5, 2013 6:55:10 PM EST", value = { "This code is generated by Rational J2EE Connector Tools code generator." })
      @Stateless(mappedName = "CustomerGetDetails")
      @RemoteHome(com.ibm.websphere.ola.ExecuteHome.class)
      public class CustomerGet {
      	public CustomerGet() {
      	}
      
      	public byte[] execute(byte[] theBytes) {
      		com.ibm.rad.ola.test.CUSTOMER input = new com.ibm.rad.ola.test.CUSTOMER();
      		input.setBytes(theBytes);
      		com.ibm.rad.ola.test.CUSTOMER output = execute(input);
      		return (output.getBytes());
      	}
      
      	public com.ibm.rad.ola.test.CUSTOMER execute(
      			com.ibm.rad.ola.test.CUSTOMER input) {
      		com.ibm.rad.ola.test.CUSTOMER output = new com.ibm.rad.ola.test.CUSTOMER();

      		// TODO - Need to implement business logic here. 

      		return (output);
	}
      }

The // TODO comment above is where you need to add implementation code. The workspace generated the code that generates an instance of the CUSTOMER class and loads it with the contents of the input byte array. This means the getter methods associated with the CUSTOMER class can be invoked to extract parts of the input byte array. The getter methods handle the code page translation so this application does not need to be concerned with this.

The external application that calls this Java needs to specify a WebSphere Optimized Local Adapter service name ofCustomerGetDetails to call this Java over a WebSphere Optimized Local Adapter Invoke (BBOA1INV) or Send Request (BBOA1SRQ) API.


Feedback