Generating a Client Enterprise Java Bean-based Application

 

This type of application produces Java classes that comprise an EJB application. The class methods are invoked from requests originating from other EJB classes and transfer data records to and from the mainframe (remote system). From the viewpoint of the mainframe, the Java classes act as a remote DTP or IMS client. From the viewpoint of the EJB classes, they act as regular EJB classes.

 

---

Action List

Before you build a Client Enterprise Java Bean-based application, see the following action list and refer to the appropriate information sources.

	Your action...	Refer to...
1	Complete all prerequisite tasks.	Prerequisites
2	Review the general steps for building a Java application	Generating a Java Application with the eGen COBOL Code Generator
3	Review an example of a script for generating a client EJB application	Components of an eGen COBOL Client EJB Script
4	Review script processing and sample script commands	Processing the Script
5	Review the generated files	Working with Generated Files
6	Customize the application	Customizing an Enterprise Java Bean-Based Application
7	Proceed to the next set of instructions.	What Do I Do Next?

 

 

---

Prerequisites

Before you start programming your Client Enterprise Java Bean-based application, you should complete the following tasks:

	Your action...	Refer to...
1	Install your computer systems, Windows/UNIX and mainframe, to meet your requirements.	BEA WebLogic Java Adapter for Mainframe Installation Guide
2	Configure your computer systems, Windows/UNIX and mainframe, to meet your requirements.	BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide

 

 

---

Components of an eGen COBOL Client EJB Script

In order to produce an EJB-based application, the script file that defines your DataViews must be edited to describe both the mainframe services accessed and the EJB that will access them. A service description might look like the listing in Listing 3-1.

Listing 3-1 Sample service Description

service sampleCreate

	accepts EmployeeRecord
	returns EmployeeRecord

This sample listing defines a service named sampleCreate that accepts an input buffer of type EmployeeRecord and returns an output buffer of type EmployeeRecord. It is this service name that also requires an entry in the jcrmgw.cfg file.

An EJB that uses this service might be defined like the following listing.

Listing 3-2 Sample getSalary Service Definition

client ejb MyEJBName MyEJBHome
{
	method newEmployee is service sampleCreate
}

This listing defines a Java bean class named MyEJBName with a method named newEmployee. The method corresponds to service name sampleCreate. The EJB home will be registered in Java Naming and Directory Interface (JNDI) under the name MyEJBHome.

The following listing shows the contents of a complete script file for defining a client EJB application.

Listing 3-3 Sample Client EJB Script

1  #---------------------------------------------------------
2  # empclient.egen
3  #	JAM script for an employee record.
4  #
5  #  $Id: empclient.egen,v 1.1 2000/01/25  18:34:14 david Exp$
6  #--------------------------------------------------------------
7
8  # DataViews (typed data records)
9
10  view sample.EmployeeRecord (Comment 1)
11	from emprec.cpy
12
13  # Services
14
15  service sampleCreate (Comment 2)
16	accepts EmployeeRecord
17	returns EmployeeRecord
18
19  service sampleRead (Comment 2)
20	accepts EmployeeRecord
21	returns EmployeeRecord
22
23  # Clients and servers
24
25  client ejb sample.SampleClient my.sampleBean (Comment 3)
26  {
27	method newEmployee (Comment 4)
28		is service sampleCreate
29	
30	method readEmployee (Comment 4)
31		is service sampleRead
32  }
33
34  # End

Table 3-1 refers to the numbered comments in Listing 3-3.

Table 3-1 Script Comments

Comment 1	Defines a DataView class, specifying its corresponding copybook source file and its package name.
Comment 2	Defines a service function and its input and output parameter types.
Comment 3	Defines a client EJB class and its home name.
Comment 4	Defines a client class method and its service name.

 

---

Processing the Script

Issue the following command to process the script.

Listing 3-4 Sample Script Process Command

egencobol empclient.egen
emprec.cpy, Lines: 21, Errors: 0, Warnings: 0
Generating sample.EmployeeRecord...
Generating group emp-name
Generating group emp-addr
Generating SampleClient...

 

---

Working with Generated Files

The empclient.egen script command generates the following files.

Table 3-2 Sample Script Generated Files

File	Content
SampleClient.java	Source for the EJB remote interface.
SampleClientBean.java	Source for the EJB implementation.
SampleClientHome.java	Source for the EJB home interface.
EmployeeRecord.java	Source for the DataView object.
SampleClient-jar.xml	Sample deployment descriptor
wl-SampleClient-jar.xml	Sample WebLogic deployment information

SampleClient.java Source File

The following listing shows the contents of the generated SampleClient.java source file.

Listing 3-5 Sample SampleClient.java Contents

// SampleClient.java
//
// EJB Remote Interface generated by eGenCobol on 24-Jan-2000.

package sample;

// Imports

import javax.ejb.EJBObject;
...

/** Remote Interface for SampleClient EJB. */

public interface SampleClient (Comment 1)
	extends EJBObject
{
	// newEmployee (Comment 2)
	EmployeeRecord newEmployee (EmployeeRecord commarea)
		throws RemoteException, UnexpectedException;

	readEmployee (Comment 2)
	EmployeeRecord readEmployee (EmploymentRecord commarea)
		throws RemoteException, UnexpectedException;
}

// End SampleClient.java

Table 3-3 refers to the numbered comments in Listing 3-5.

Table 3-3 Script Comments

Comment 1	Defines an EJB interface.
Comment 2	Methods to convert a raw COMMAREA into a Java DataView object.

SampleClientBean.java Source File

Listing 3-6 shows the contents of the generated SampleClientBean.java source file.

Listing 3-6 Sample SampleClientBean.java Contents

// SampleClientBean.java
//
// EJB generated by eGenCobol on 24-Jan-2000.

package sample;

//Imports

import com.bea.jam.egen.egenClientBean;
...

/** EJB implementation. */

public class SampleClientBean (Comment 1)
	extends egenClientBean
{
	// newEmployee

	public EmployeeRecord newEmployee (EmployeeRecord commarea)
		throws IOException, snaException (Comment 2)
	{
		...
	}

	//readEmployee

	public EmployeeRecord readEmployee (EmployeeRecord commarea)
		throws IOException, snaException (Comment 2)
	{
		...
	}	

}

// End SampleClientBean.java

Table 3-4 refers to the numbered comments in Listing 3-6.

Table 3-4 Script Comments

Comment 1	Defines an EJB client bean.
Comment 2	The methods convert a raw COMMAREA into a Java DataView object.

SampleClientHome.java Source File

Listing 3-7 shows the contents of the generated SampleClientHome.java deployment descriptor file.

Listing 3-7 Sample SampleClientHome.java Contents

// SampleClientHome.java
//
// EJB Home interface generated by eGenCobol on 24-Jan-2000.

package sample;

// Imports

import javax.ejb.EJBHome;
...

/** Home interface for SampleClient EJB. */

public interface SampleClientHome (Comment 1)
	extends EJBHome
{
	// create

	SampleClient create()
		throws CreateException, remoteException;
}

// End SampleClientHome.java

Table 3-5 refers to the numbered comments in Listing 3-7.

Table 3-5 Script Comments

Comment 1

Defines an EJB home interface.

SampleClient-jar.xml Source File

Listing 3-8 shows the contents of the generated SampleClient-jar.xml deployment descriptor file.

Listing 3-8 Sample SampleClient-jar.xml Contents

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN''http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
<ejb-jar>
    <enterprise-beans>
      <session>
        <ejb-name>SampleClient</ejb-name>
        <home>sample.SampleClientHome</home>
        <remote>sample.SampleClient</remote>
        <ejb-class>sample.SampleClientBean</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Container</transaction-type>
      </session>
    </enterprise-beans>
    <assembly-descriptor>
      <container-transaction>
        <method>
          <ejb-name>SampleClient</ejb-name>
          <method-intf>Remote</method-intf>
          <method-name>*</method-name>
        </method>
        <trans-attribute>NotSupported</trans-attribute>
      </container-transaction>
    </assembly-descriptor>
</ejb-jar>

wl-SampleClient-jar.xml Source File

Listing 3-9 shows the contents of the wl-SampleClient-jar.xml source file. To use this file, copy it to weblogic-ejb-jar.xml.

Listing 3-9 Sample wl-SampleClient-jar.xml Contents

<?xml version="1.0"?>
<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN' 'http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
    <weblogic-enterprise-bean>
      <ejb-name>SampleClient</ejb-name>
      <caching-descriptor>
         <max-beans-in-free-pool>50</max-beans-in-free-pool>
      </caching-descriptor>
      <jndi-name>my.sampleBean</jndi-name>
    </weblogic-enterprise-bean>
</weblogic-ejb-jar>

 

---

Customizing an Enterprise Java Bean-Based Application

Unlike the servlet applications, the generated Java classes produced for EJB applications are intended for customization.

This section describes the way that generated client EJB code can be customized.

The following figure illustrates the relationships and inheritance hierarchy between the JAM classes comprising the application.

Figure 3-1 The JAM Client EJB Class Hierarchy

 

The generated Java code for a client EJB application is a class that inherits class egenClientBean. The egenClientBean class is provided in the JAM distribution jar file.

This base class, illustrated in Listing 3-10, is provided in the jam.jar file and provides the basic framework for an EJB. It provides the required methods for a Stateless Session EJB.

Listing 3-10 EgenClientBean.java Base Class

//=========================================================
// egenClientBean.java
//   The base class for generated client EJB's.
//
//---------------------------------------------------------------

package com.bea.jam.egen;

abstract public class EgenClientBean
	implements SessionBean
{
	//Implementation of ejbActivate(), ejbRemove(),
	// ejbPassiveate(), ejbCreate() and setSessionContext()
	...

	/**
	 * Call a service by name through the jcrmgw.
	 *
	 * @exception bea.sna.jcrmgw.snaException For Gateway errors
	 * @exception java.io.IOException For data translation
	   errors.
	 */
	protected byte[] callService(String service, byte[] in)
	 throws snaException, IOException
	{
	  // Low level gateway access code
	      ...
	}

	// Variables

	  protected SessionContext m_context;
	  protected transient Properties        m_properties;
}

// End EgenClientBean.java

The generated class, illustrated in Listing 3-11, adds the methods specific to this EJB.

Listing 3-11 Generated SampleClientBean.java Class

// SampleClientBean.java
//
// EJB generated by eGenCobol on Feb 2, 2000.
//

package Sample;

...

/**
 * EJB implementation.
 */
public class SampleClientBean extends EgenClientBean
{
	// readEmployee
	//
	public EmployeeRecord readEmployee (EmployeeRecord commarea)
	  throws IOException, snaException
	{
		// Make the remote call.
		//
		...
	}

	// newEmployee
	//
	public EmployeeRecord newEmployee (EmployeeRecord commarea)
	  throws IOException, snaException
	{
	  // Make the remote call.
	  //
	  ...
	}
}

// END SampleClientBean.java

Listing 3-12 illustrates an example ExtSampleClientBean class that extends the generated SampleClientBean class, adding a validation function (isSsnValid()) for the emp-ssn (m_empSsn) field of the DataView EmployeeRecord class. The four methods are overridden by the methods in the extended class. If the emp-ssn field is determined to be invalid, an exception is thrown. Otherwise, the original function is called to perform the mainframe operation.

Listing 3-12 Example ExtSampleClientBean.java Class

//============================================================================
// ExtSampleClientBean.java
//      Example class that extends a generated JAM client EJB application.
//----------------------------------------------------------------------------

package sample;

// Imports

import java.math.BigDecimal;
import java.io.IOException;

import com.bea.sna.jcrmgw.snaException;

// Local imports

import sample.EmployeeRecord;
import sample.SampleClientBean;

/*****************************************************************************
* Extends the SampleClientBean EJB class, adding additional business logic.
*/

public class ExtSampleClientBean
    extends SampleClientBean
{
// Public functions

    /*************************************************************************
    * Read an employee record.
    */

    public EmployeeRecord readEmployee(EmployeeRecord commarea)
        throws RemoteException, UnexpectedException, IOException, snaException
    {
        EmployeeRecord  erec = (EmployeeRecord) commarea;

        if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
        {
            // The SSN is not valid.
            throw new Error("Invalid Social Security Number: "
                + erec.getEmpRecord().getEmpSsn());
        }

        // Make the remote call.
        return super.readEmployee(commarea);
    }

    /*************************************************************************

    * Create a new employee record.
    */

    public EmployeeRecord newEmployee(EmployeeRecord commarea)
        throws IOException, snaException
    {
        EmployeeRecord  erec = (EmployeeRecord) commarea;

        if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
        {
            // The SSN is not valid.
            throw new Error("Invalid Social Security Number:"
                + erec.getEmpRecord().getEmpSsn());
        }

        // Make the remote call.
        return super.newEmployee(commarea);
    }

// Private Functions

    /*************************************************************************
    * Validate an SSN field.
    *
    * @return
    * True if the SSN is valid, otherwise false.
    */

    private boolean isSsnValid(final BigDecimal ssn)
    {
        if (ssn.longValue() < 100000000)
        {
            // Oops, appears to be less than 9 digits
            return false;
        }
        return true;
    }
}

// End ExtSampleClientBean.java

When it has been written, the ExtSampleClientBean class and the other EJB Java source files must be compiled and deployed in the same manner as other EJBs. Prior to deploying, the deployment descriptor must be modified; the ejb-class property must be set to the name of your extended EJB implementation class.

 

---

Compiling and Deploying

Refer to the BEA WebLogic server documentation for more information. The sample file provided with WebLogic Server contains a build script for reference.

 

---

What Do I Do Next?

Refer to BEA Java Adapter for Mainframe Scenarios for detailed examples of some of the application models discussed in this guide.