bea.com | products | dev2dev | support | askBEA

Download Docs
Search

Programming Guide

Basic Programming Techniques

This section discusses the following topics:

- Choosing an eGen Java Application Model

- General Form of an eGen Script

- Mainframe to WebLogic Server Application Models

- WebLogic Server to Mainframe Application Models

- WebLogic JAM to JMS

Choosing an eGen Java Application Model

There are four different types or models of Java applications that can be generated by the eGen utility. These models, which can be classified as either Mainframe to WebLogic Server or WebLogic Server to Mainframe, are described below.

Mainframe to WebLogic Server (request originates on the mainframe and is serviced by WebLogic):

- Server EJB. The server EJB is a Stateless Session EJB that provides a service to the mainframe.

WebLogic Server to Mainframe (request originates on the WebLogic client or server and is serviced by the mainframe):

- Client Class. The client class is a stand-alone Java class that invokes mainframe services. This class may be built into your own EJB or utilized in some other way within your code.

- Client EJB. The client EJB is a Stateless Session EJB that invokes mainframe services. It may be called by a servlet or other client programs. This is the normal model for building a production application with access to mainframe services. A servlet that invokes the EJB's methods may be added for testing or demonstration purposes.

- Servlet Only. The servlet-only application is a servlet that presents a simple form and invokes mainframe services directly. This is the simplest model, but it may not be suitable for production applications.

Choose one of these four model types to use as the basis for your Java application. Once you have chosen a model type, refer to the section from the following list for instructions on writing the script and implementing the model you have chosen:

- Generating a Server Enterprise Java Bean-Based Application

- Generating a Stand-Alone Client Application

- Generating a Client Enterprise Java Bean-Based Application

- Generating a Servlet Application

For all of the applications you generate, you must provide a script file containing definitions for the application, including the COBOL copybook file name and the DataView class names.

Generating the Java Application Code

The Java application code can be generated at the same time that you generate the Java DataView code. To generate Java application code, the eGen script that you process must contain instructions for generating the Java application along with the instructions for generating the DataView code.

Referring to the sample files in samples\verify\gateway\outbound, the following command generates Chardata.java and BaseClient.java. The DataView file is Chardata.java, and the application file is BaseClient.java.

>     > egencobol baseClient.egen

General Form of an eGen Script

As previously stated, most eGen scripts consist of two major sections:

- The DataView section described in Writing an eGen Script.

- The Application section, which defines the Java application code that the eGen utility is to generate (described in Writing the Application Section of an eGen Script).

Writing the Application Section of an eGen Script

The application section of an eGen script contains the information about the Java class files that the eGen utility is to generate for a particular application. The application section is divided into two distinct subsections, which are actually lists. The two lists are:

- List of Services -- Describes the remote services that are configured for JAM and are called by the classes that the eGen script defines. This list is not present in the script if the classes to be generated by the eGen utility are all server EJB's.

- List of Application Components -- Components for which the eGen utility is to generate the class files. This list contains one or more definitions of stand alone clients, client EJB's, servlets, or server EJB's.

List of Services

Scripts that are used to define the application components that the eGen utility is to generate usually contain a list of one or more service definitions. If the application components are all server or Mainframe to WebLogic Server EJB's, this list of services is not present. This is because this list of service definitions describes remote services configured in JAM; server EJB's do not call remote services since the requests are flowing outward from the mainframe.

The general form of a service definition is as follows (keywords are in bold):

>     service servicename accepts inputViewname returns outputViewname

Table 3-1 describes the service definition parameters.

Table 3-1 Service Definition Parameters

Parameter | Definition
--- | ---
servicename | Must match the name of a remote service that is defined in the WebLogic JAM configuration (see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide).
inputViewname | The name of a DataView that will be the input or request data for the service.
outputViewname | The name of the DataView that is the output or response from the service.

Note: The inputViewname and outputViewname do not have to be the same; however, due to the way many applications are written, they often are the same.

Following is an example of a service definition:

>     service TOUPPER accepts Chardata returns Chardata

In this example, the service TOUPPER is a configured remote service. As far as the Java application making the request for a mainframe service through WebLogic JAM is concerned, this service accepts as input a Chardata DataView. The actual mainframe server application accepts as input the COBOL copybook which corresponds to a Chardata DataView. As far as the Java application is concerned, the output or response from the mainframe service is a Chardata DataView.

List of Application Components

In order for the eGen utility to generate code for Java applications, the eGen script must contain a list of one or more definitions of the application components that are to be generated. This list of definitions of application components can contain definitions of stand-alone clients, client or server EJB's, and servlets. This list of definitions also contains the definition of any HTML pages that are used by servlets defined in the list.

Note: The definition of an HTML page appearing in this list by itself will not cause any code to be generated.

The general form of an application component definition is as follows:

>     model identifier [model-dependent-parameters]
>     { details }

Table 3-2 describes the application component definition parameters.

Table 3-2 Application Component Definition Parameters

Parameter | Definition
--- | ---
model | Indicates to the eGen utility the type of application component that is to be generated. The possible values of this identifier are: client class client ejb server ejb servlet page
identifier | This is generally the class name (or class name stem for EJB's) for the application component that is to be generated. The identifier includes the package name. For an HTML page, the identifier is the page name.
model-dependent- parameters | These further describe the application component to the eGen utility and can vary a great deal depending on the model. For a stand-alone client, there would be no model-dependent-parameters given. For an EJB (client or server), the home interface identifier for the bean must be given. For a servlet, the initial HTML page that is to be displayed is given. For an HTML page, the title of the page is given.
details | These give details about the code for the application component. For a stand-alone client, as well as an EJB, these details would include the definitions of class methods that will call services defined in the script. For a servlet, there usually will not be any details given. For an HTML page, these details include the DataView that is to be displayed and any buttons that will be displayed on the page.

Following is an example of an application component definition:

>     client ejb sample.SampleClient my.sampleBean
>      {
>             method newEmployee
>                     is service sampleCreate
>      }

The example states the following:

- This is the definition for a client or EJB.

- The classname for this EJB is SampleClient. That is, the eGen utility will generate files named SampleClient.java, SampleClientBean.java, and SampleClientHome.java.

- The package name is sample.

- The home interface identifier for this bean is my.sampleBean.

- The bean will have a method called newEmployee that calls the sampleCreate service. The sampleCreate service is defined elsewhere in the file.

Specific details about the application component definitions for each application model, as well as the files that the eGen utility generates for each model, are discussed in the following sections.

Mainframe to WebLogic Server Application Models

In a Mainframe to WebLogic Server application, a request originates on a mainframe and is serviced by an EJB invoked by a WebLogic JAM Gateway.

Generating a Server Enterprise Java Bean-Based Application

This type of application produces Java classes that comprise an EJB application acting as a remote server from the viewpoint of the mainframe. The classes process service requests originating from the mainframe (remote) system and transfer data records to and from the mainframe. From the viewpoint of the Java classes, they receive EJB method requests. From the viewpoint of the mainframe application, it invokes remote CICS or IMS programs.

Components of an eGen Server EJB Script

The general form of a definition of a server (Mainframe to WebLogic Server) EJB that appears in an eGen script is as follows (keywords are in bold):

>     server ejb classname ejbregistration transaction
>        transaction-attribute
>     {servermethod}

Table 3-3 describes the server EJB definition keywords and parameters.

Table 3-3 Service EJB Definition Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
server ejb | Indicates to the eGen utility the type of application component that is to be generated.
classname | Indicates the class name stem for the EJB. For example, if the classname is SampleServer, then the following files are generated by the eGen utility: SampleServer.java SampleServerBean.java SampleServerHome.java Note: The package name should be included in the classname.
ejbregistration | The name that will be used to register the home interface for the EJB.
transaction transaction- attribute | This keyword and parameter are optional. They are used to manage the level of transaction demarcation. The possible values of the transaction-attribute are: NotSupported Required Supports RequiresNew Mandatory Never Note: If the transaction keyword is not present in the definition, the default value of the transaction-attribute is Supports. For a detailed explanation of how the WebLogic Server EJB container responds to the transaction-attribute setting, see the section on Transaction Attributes in the EJB 2.0 Specification.
servermethod | Method that appears in the EJB implementation (must be in braces). The general form of a servermethod definition is as follows (keywords are in bold): method methodname (inputDataView) returns outputDataView Table 3-4 describes the parameters of a servermethod definition.

Table 3-4 Parameters for the servermethod

Parameter | Definition
--- | ---
methodname | The name of the method.
inputDataView | The name of the DataView that is the type of the input parameter for the method (must be in parenthesis).
outputDataView | The name of the DataView that is the type returned from the method.

Following is an example of a server (Mainframe to WebLogic Server) EJB definition that appears in an eGen script:

>     server ejb sample.SampleServer my.sampleServer
>     {
>     	method newEmployee (EmployeeRecord)
>     		returns EmployeeRecord
>     }

The example states the following:

- This is the definition for a server EJB class. The generated EJB class files are defined in the Generated Files section that follows.

- The my.sampleServer is the home interface identifier for this bean in the WebLogic deployment description.

- The transaction keyword is not present in this example, so it defaults to Supports.

- The server class method newEmployee takes its input from the DataView EmployeeRecord and writes its output to an EmployeeRecord output DataView.

Generated Files

Table 3-5 lists the files generated from the example server (Mainframe to WebLogic Server) EJB described in Components of an eGen Server EJB Script. These files are described in the sections following the table.

Table 3-5 Sample Script Generated Files

File | Content
--- | ---
>     SampleServer.java
| Source for the EJB remote interface.
>     SampleServerBean.java
| Source for the EJB implementation.
>     SampleServerHome.java
| Source for the EJB home interface.
>     SampleServer-jar.xml
| Deployment descriptor.
>     wl-SampleServer-jar.xml
| WebLogic deployment information.

SampleServer.java Source File

Listing 3-1 shows the partial contents of the generated remote interface SampleServer.java source file.

Listing 3-1 Sample SampleServer.java Contents

SampleServerBean.java Source File

Listing 3-2 shows the partial contents of the generated EJB implementation SampleServerBean.java source file.

Listing 3-2 Sample SampleServerBean.java Contents

SampleServerHome.java Source File

The eGen utility generates a standard home interface class for the server EJB.

SampleServer-jar.xml Source File

The following line from the deployment descriptor file results from the transaction attribute in the definition in the eGen script.

>           <trans-attribute>Supports</trans-attribute>

As described in Components of an eGen Server EJB Script, this element indicates the level of transaction demarcation. If the transaction-attribute is not present in the definition, the default value is Supports. So, in this example, the transaction attribute was not listed in the script definition.

wl-SampleServer-jar.xml Source File

The following line from the WebLogic deployment information file results from the home interface name in the eGen script.

>           <jndi-name>my.sampleServer</jndi-name>

As described in Components of an eGen Server EJB Script, my.sampleServer is the home interface identifier for this bean in the WebLogic deployment description.

Customizing a Server Enterprise Java Bean-Based Application

The generated server enterprise Java bean-based applications are only intended for customizing, since they perform no real work without customization. This section describes the way generated server EJB code can be customized.

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

Figure 3-1 The WebLogic JAM Server EJB Class Hierarchy

The generated Java code for a server EJB application is a class that inherits the class EgenServerBean. The EgenServerBean class is provided in the WebLogic JAM distribution jar file. This base class provides the basic framework for an EJB. It provides the required methods for a Stateless Session EJB.

The following listing shows an example ExtSampleServerBean class that extends the generated SampleServerBean class, providing an implementation of the newEmployee() method. The example method prints a message indicating that a newEmployee request has been received.

Listing 3-3 Sample ExtSampleServerBean.java Contents

>     package sample;

>     public class ExtSampleServerBean extends SampleServerBean
>     {
>     	public EmployeeRecord newEmployee (EmployeeRecord in)
>     	{
>     	  System.out.println("New Employee: " +
>     		+in.getEmpRecord().getEmpName().getEmpNameFirst()
>     		+ " "
>     		+ in.getEmpRecord().getEmpname().getEmpNameLast());
>     	  return in;
>     	}
>     }

Once it has been written, the ExtSampleServerBean class and the other EJB Java source files must be compiled and deployed in the same manner as other EJBs. Before deploying, the deployment descriptor must be modified; the ejb-class must be set to the name of your extended EJB implementation class (see Deploying a WebLogic JAM eGen EJB).

Compiling and Deploying

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

WebLogic Server to Mainframe Application Models

In a WebLogic Server to Mainframe application, a request originates on a WebLogic client or server, and is serviced by a mainframe program invoked by the WebLogic JAM Gateway in cooperation with the CRM.

Generating a Stand-Alone Client Application

This type of application produces simple Java classes that perform the appropriate conversions of data records sent between Java and the mainframe and call mainframe services, but without all of the EJB support methods. These classes are intended to be lower-level components upon which more complicated applications are built.

Components of an eGen Stand-Alone Application Script

The general form of a definition of a stand-alone client class that appears in an eGen script is as follows (keywords are in bold):

>     client class classname
>     { clientmethods }

Table 3-6 describes the stand-alone client class definition keywords and parameters.

Table 3-6 Stand-Alone Client Class Definition Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
client class | Indicates to the eGen utility the type of application component that is to be generated.
classname | Indicates the class name for the client class. Note: The package name should be included in the classname.
clientmethods | List of methods that appear in the client class implementation (must be in braces). These methods are wrappers for calls to services that are defined in the services section of the eGen script. The general form of the definition for a clientmethod in an eGen script is as follows: method methodname is service servicename Table 3-7 describes the parameters of a clientmethod definition.

Table 3-7 Parameters for the clientmethod

Parameter | Definition
--- | ---
methodname | The name of the method.
servicename | Indicates the remote service for which this method acts as a wrapper for a WebLogic JAM call. This service must be defined in the same eGen script.

Following is an example of a stand-alone client class definition that appears in an eGen script:

>     client class sample.SampleClass
>     {
>     	method newEmployee
>     	is service sampleCreate
>     }

The example states the following:

- This is the definition of a simple client class.

- The package name is sample and SampleClass is the class name.

- The method newEmployee acts as a wrapper for a WebLogic JAM call to the remote service sampleCreate.

- This service must be defined in the same eGen script as the client class.

Generated Files

The file SampleClass.java, containing the source for the sample class, is generated.

Listing 3-4 shows the partial contents of the SampleClass.java source file.

Listing 3-4 Sample SampleClass.java Source File

Customizing a Stand-Alone Java Application

The following figure illustrates the relationships and inheritance hierarchy between the WebLogic JAM classes comprising the stand-alone java application.

Figure 3-2 The WebLogic JAM Client Class Hierarchy

The generated Java code for a client class application is a class that inherits class EgenClient. The EgenClient class is provided in the WebLogic JAM distribution jam.jar file. This base class provides the basic framework for a client to the WebLogic JAM Gateway, as well as the required methods for accessing the gateway.

Your class, which extends or uses the SampleClient class, simply overrides or calls these methods to provide additional business logic, modifying the contents of the DataView. Your class may also add additional methods.

The following listing shows an example ExtSampleClass class that extends the generated SampleClient class.

Listing 3-5 Sample ExtSampleClient.java Contents

>     package sample;

>     public class ExtSampleClient extends SampleClass
>     {
>     	// createEmployee
>     	//
>     	public EmployeeRecord newEmployee(EmployeeRecord
>     		commarea)
>     	throws IOException, snaException
>     	{
>     	  if (!isSsnValid(commarea.getEmpRecord().getEmpSsn()))
>     	  {
>     	  // The SSN is not valid
>     	  throw new Error("Invalid Social Security Number:"+
>     		commarea.getEmpRecord().getEmpSsn());
>     	  }
>     	return super.newEmployee(commarea);
>     	}
>     	.
>     	.
>     	.
>     // Private functions

>     	/*******************************************************
>     	* Validates an SSN field.
>     	*/

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

Once it has been written, the ExtSampleClient class and the other Java source files must be compiled and placed in your CLASSPATH.

Instead of extending the generated client, you can also write classes that have the generated client as a member. This is an especially useful alternative if the class you write must extend some other class.

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 or other WebLogic Server client 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 CICS or IMS client. From the viewpoint of the WebLogic Server client classes, they act as regular EJB classes.

Components of an eGen 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.

The general form of a definition of a client (WebLogic Server to Mainframe) EJB that appears in an eGen script is as follows (keywords are in bold):

>     client ejb classname ejbregistration transaction
>        transaction-attribute
>     {clientmethods}

Table 3-8 describes the client EJB script keywords and parameters.

Table 3-8 Client EJB Script Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
client ejb | Indicates to the eGen utility the type of application component that is to be generated.
classname | Indicates the class name stem for the EJB. For example, if the classname is SampleClient, the following files are generated by the eGen utility: SampleClient.java SampleClientBean.java SampleClientHome.java Note: The package name should be included in the classname.
ejbregistration | The name that will be used to register the home interface for the EJB.
transaction transaction- attribute | This keyword and parameter are optional. They indicate the level of transaction demarcation. The possible values of transaction-attribute are: NotSupported Required Supports RequiresNew Mandatory Never Note: If the transaction keyword is not present in the definition, the default value of the transaction-attribute is Supports. For a detailed explanation of how the WebLogic Server EJB container responds to the transaction-attribute setting, see the section on Transaction Attributes in the EJB 2.0 Specification.
clientmethods | List of methods that appear in the EJB implementation. These methods are wrappers for calls to remote services that are defined in the services section of the eGen script. The general form of a clientmethod definition is as follows (keywords are in bold): method methodname is service servicename Table 3-9 describes the parameters of a client method definition.

Table 3-9 Client Method Definition Parameters

Parameter | Definition
--- | ---
methodname | The name of the method.
servicename | Indicates the remote service for which this method acts as a wrapper for a WebLogic JAM call. This service must be defined in the same eGen script.

Following is an example of a client (WebLogic Server to Mainframe) EJB definition that appears in an eGen script:

>     client ejb sample.SampleClient my.sampleBean
>     {
>     	method newEmployee
>     	is service sampleCreate
>     }

The example states the following:

- This listing defines a Java bean class named SampleClient in the package sample 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 my.sampleBean.

Generated Files

Table 3-10 lists the files generated from the client (WebLogic Server to Mainframe) EJB described in Components of an eGen Client EJB Script. These files are described in the sections following the table.

.

Table 3-10 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.
>     SampleClient-jar.xml
| Deployment descriptor.
>     wl-SampleClient-jar.xml
| WebLogic deployment information.

SampleClient.java Source File

Listing 3-6 shows the partial contents of the generated remote interface SampleClient.java source file. Following the listing are descriptions of the elements in this file.

Listing 3-6 Sample SampleClient.java Contents

SampleClientBean.java Source File

Listing 3-7 shows the partial contents of the generated EJB implementation SampleClientBean.java source file. Following the listing are descriptions of the elements in this file.

Listing 3-7 Sample SampleClientBean.java Contents

SampleClientHome.java Source File

The eGen utility generates a standard home interface class for the client EJB.

SampleClient-jar.xml Source File

The following line from the deployment descriptor file results from the transaction demarcation listed in the definition in the eGen script.

>           <trans-attribute>Supports</trans-attribute>

As described in Components of an eGen Client EJB Script, this element indicates the level of transaction demarcation. If the transaction-attribute is not present in the definition, the default value is Supports. In this example, the transaction-attribute was not listed in the script definition.

wl-SampleServer-jar.xml Source File

The following line from the WebLogic deployment information file results from the Home Interface name in the eGen script.

>           <jndi-name>my.sampleBean</jndi-name>

As described in Components of an eGen Client EJB Script, my.sampleBean is the home interface identifier for this bean in the WebLogic deployment description.

Note: You can edit the deployment descriptor to change the pool size, etc.

Customizing an Enterprise Java Bean-Based Application

The generated client enterprise Java bean-based applications are generally intended for customizing. Without customization, the only function they perform is communication with the mainframe. This section describes the way generated client EJB code can be customized.

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

Figure 3-3 The WebLogic 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 WebLogic JAM distribution jar file.

Listing 3-8 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. If the emp-ssn field is determined to be invalid, an exception occurs. Otherwise, the original function is called to perform the mainframe operation.

Listing 3-8 Example ExtSampleClientBean.java Class

>     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 SampleCientBean EJB class, adding additional business logic.
>     */

>     public class ExtSampleClientBean
>     	extends SampleClientBean
>     {
>     //Public functions

>     ...

>     /****************************************************************
>      * Create a new employee record.
>      */

>      public EmployeeRecord newEmployee (EmployeeRecord commarea)
>     	  throws IOException, snaException
>     {
>     	if (!isSsnValid (commarea.getEmpRecord().getEmpSsn()))
>     	{
>     	// The SSN is not valid.
>     	throw new Error ("Invalid Social Security Number:"
>     		+ commarea.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;
>     }
>     }

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 (see Deploying a WebLogic JAM eGen EJB).

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.

Generating a Servlet Application

A WebLogic JAM servlet application is a Java servlet that executes within BEA WebLogic Server. The application is started from a web browser when the user enters a URL that is configured to invoke the servlet. The servlet presents an HTML form containing data fields and buttons. The buttons can be configured to invoke:

- EJB methods

- Remote gateway services (via the JAM Gateway)

In general, servlets generated by the eGen utility are intended for testing purposes and are not easily customized to provide a more aesthetically pleasing interface.

In order to produce a servlet application, create an eGen script file and use the eGen utility to generate your typed data record (DataView), and Servlet code.

In order to define a servlet application using an eGen script, you must define the following:

- HTML pages displayed by the servlet

- The servlet itself

Components of an eGen HTML Page Definition

The general form of an HTML page that appears in an eGen script is as follows (keywords are in bold):

>     page pagename title
>     { view viewname
>       buttons {buttonlist}
>     }

Table 3-11 describes the HTML page definition keywords and parameters.

Table 3-11 HTML Page Definition Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
page | Indicates to the eGen utility the type of application component that is to be generated.
pagename | Indicates the name of the page so it can be referenced by the servlet and other page definitions in the script.
title | The title that will be displayed on the HTML page.
viewname | Indicates the name of the DataView that is to be displayed on the page. This DataView must be defined elsewhere in the eGen script.
buttonlist | List of buttons that are displayed on the page. The buttons can either call EJB methods or remote services that are defined elsewhere in the eGen script. The general form of the definition for a button in the buttonlist depends on whether it is a remote service button or an EJB.

The general syntax for a remote service button in an eGen script is as follows (keywords are in bold):

>     buttonname service (servicename) shows pagename

Table 3-12 describes the remote service button definition keywords and parameters.

Table 3-12 Remote Service Button Definition Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
buttonname | The label that appears on the button.
servicename | The name of the remote service (must be in parenthesis).
pagename | The page used to display the results.

The general syntax for an EJB button in an eGen script is as follows (keywords are in bold):

>     buttonname ejbmethod () shows pagename

Note: Empty parenthesis must follow ejbmethod.

Table 3-13 describes the EJB button definition keywords and parameters.

Table 3-13 EJB Button Definition Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
buttonname | The label that appears on the button.
ejbmethod | The name of the EJB method that is to be called. This method should be specified in the following form: packagename.EJBclass.method
pagename | The page used to display the results.

Following is an example of an HTML page that appears in an eGen script:

>     page initial "Initial Page"
>     {
>     	view EmployeeRecord

>     	buttons
>     	{
>     		"Create"
>     			service ("sampleCreate")
>     			shows fullPage
>     	}
>     }

This listing defines an HTML page named initial, with a text title of Initial Page, that displays an EmployeeRecord record object as an HTML form. It also specifies that the form has a button labeled Create. When the button is pressed, the service sampleCreate is invoked and is passed the contents of the browser page as an EmployeeRecord object (the fields of which may have been modified by the user). Afterwards, the fullPage page is used to display the results.

Components of an eGen Servlet Definition

The general form of a servlet definition that appears in an eGen script is as follows (keywords are in bold):

>     servlet classname shows pagename

Table 3-14 describes the servlet definition keywords and parameters.

Table 3-14 Servlet Definition Keywords and Parameters

Keyword/Parameter | Definition
--- | ---
servlet | Indicates the type of application component that is to be generated.
classname | Indicates the class name for the servlet. Note: The package name should be included in the classname.
pagename | The name of the page that is initially displayed by the servlet. This page must be defined elsewhere in the script.

Following is an example of a servlet definition that appears in an eGen script:

>     servlet sample.SampleServlet shows initial

The example states the following:

- This is the definition of an application servlet class named SampleServlet in the package sample.

- The servlet is to be displayed in the HTML page named initial.

Generated Files

The eGen servlet definition described in Components of an eGen Servlet Definition generates a servlet source code file called SampleServlet.java.

Customizing a Servlet WebLogic JAM Application

The generated Java classes produced for servlet applications are intended for proof of concept and prototypes. They can be customized in limited ways. It is presumed that some other development tool will be used to develop a servlet or other user interface on top of the generated EJBs or client classes.

Supplying Security Credentials

WebLogic JAM has the capability to accept user ID and password information from a Java client program, and apply that information to access a secure service on the mainframe.

Note: When security information is transmitted via the connection between the WebLogic JAM Gateway and the CRM, it is sent in clear text (not encrypted). You should not send this information over a network that can be read by unauthorized parties.

Security Levels

There are three levels of security that are supported by WebLogic JAM.

- Local -- No user information from the Java client is required to access a mainframe service. Use of this security level implies that any user with access to execute the Java client program should have access to a mainframe service.

- Identify -- A user ID specified by the Java client is required to access a mainframe service. This user ID is passed to the mainframe to verify that it is a valid user ID. Use of this security level implies that there is a trusted relationship between the Java and mainframe environments, since there is no re-verification of the user's identity in the mainframe environment.

- Verify -- A user ID and password specified by the Java client are required to access a mainframe service. The password is used to re-verify the user's identity in the mainframe environment.

Notes: Refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide for information on setting the security level for a CRM link and using a default user ID.

Refer to your mainframe security documentation for more specific information about establishing and administrating mainframe security.

Supplying Security Credentials in a WebLogic JAM Client Program

User security information can be supplied in a WebLogic JAM stand-alone client or client EJB. There are two methods in the EgenClient object that support this operation:

- EgenClient.setUserId(String)

This method sets the user ID to the value specified in the String argument.

- EgenClient.setPassword(String)

This method sets the user password to the value specified in the String argument.

These methods can be called on any sub-class of EgenClient, such as the client classes generated by the eGen utility. The methods are not inserted automatically by the eGen utility; they must be manually added to the client program source, and should be called prior to the any calls to EgenClient.callService().

The methods setUserID and setPassword can be called on any subclass of EgenClientBean, such as the client EJBs generated by the eGen utility. EgenClientBean has methods by the same name that act as wrappers for calls to methods of the EgenClient member of the EgenClientBean class.

Calls to the EgenClient.setUserId() method within a WebLogic JAM client will override any default user ID value configured for the CRM link the client is using.

These methods cannot be used with the servlet-only applications, since they do not use the EgenClient object directly. Servlet-only applications can make use of the default user ID to support security level Identify.

Listing 3-9 illustrates a class that extends the generated EJB implementation to provide security credentials to the Gateway during these operations.

Listing 3-9 Example of Class with Security Credentials

>     // ExtSampleClientBean.java
>     //

>     package sample;

>     // Imports
>     //
>     import java.io.IOException;
>     import com.bea.sna.jcrmgw.snaException;

>     /**
>      * EJB implementation.
>      */
>     public class ExtSampleClientBean extends SampleClientBean
>     {
>         protected byte[] callService(String svc, byte[] input)
>                 throws snaException, IOException
>         {
>                 setUserid("JAMUSER");
>                 setPassword("JAMPASS");

>                 return super.callService(svc, input);
>         }
>     }

>     // END ExtSampleClientBean.java

Note: WebLogic JAM will return an SNANotAuthorized exception if the credentials are rejected by the mainframe security package.

WebLogic JAM to JMS

WebLogic JAM includes an EJB that has two major functions:

- Inserts request data into JMS topics or queues

- Converts EBCDIC data into an ASCII XML document for use with custom applications

WebLogic JAM to JMS is a utility stateless session EJB that uses a DataView generated by the eGen utility to convert the data. The EJB is contained in the jam.ear file with a default JNDI name of JAMToJMS.

The general process for this insertion and conversion is described in the following sections.

1. Obtain a COBOL Copybook.

   The mainframe client application must have a COBOL record layout (copybook) to describe the message comprising the request. This layout is used to generate Java classes that can be used for data transformation. Refer to Obtaining a COBOL Copybook for more information.

2. Generate a DataView with XML Support.

   Make sure that your eGen script is written to generate DataViews that support XML, as shown in the following code example:

   >     generate view empRecData from emprec support xml

   For more information on DataViews, refer to Writing the DataView Section of an eGen Script. For more information on generating the DataView source files, see Processing eGen Scripts with the eGen Utility. These files can be compiled for deployment. The schema and DTD can be made available to the XML application as necessary.

3. Compile the DataView .java files (see Creating an Environment for Generating and Compiling the Java Code).

4. Copy the DataView class files created by the eGen utility to a directory in the WebLogic Server CLASSPATH.

5. Create a JMS Event definition. For specific instructions, refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

   For an example of how to use the WebLogic JAM to JMS feature, refer to the BEA WebLogic Java Adapter for Mainframe Samples Guide.