BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
JAM Documentation | JAM Programming Guide | Previous Topic | Next Topic | Contents | Index

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, but without all of the EJB support methods. These classes are intended to be lower-level components upon which more complicated applications are built.

Action List

Before you build a stand-alone 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 stand-alone Java application | Components of an eGen COBOL Stand-alone Application Script
4 | Review script processing and sample script commands | Processing a Script
5 | Review the generated files | Working with Generated Files
6 | Customize the application | Customizing a Stand-Alone Java Application
7 | Proceed to the next set of instructions. | What Do I Do Next?

Prerequisites

Before you start programming your stand-alone 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 Stand-alone Application Script

The following listing shows the contents of a complete script for defining a stand-alone client class with multiple services.

Listing 5-1 Sample Stand-Alone Client Class Script

>     1  #--------------------------------------------------------
>     2  # empclass.egen
>     3  #	JAM script for an employee record.
>     4  #
>     5  # $Id: empclass.egen, v 1.1 2000/01/21 23:20:40
>     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  service sampleUpdate (Comment 2)
>     24	accepts EmployeeRecord
>     25	returns EmployeeRecord
>     26
>     27  service sampleDelete (Comment 2)
>     28	accepts EmployeeRecord
>     29	returns EmployeeRecord
>     30
>     31  # Clients and servers
>     32
>     33  client class sample.SampleClass (Comment 3)
>     34  {
>     35	method newEmployee (Comment 4)
>     36		is service sampleCreate
>     37
>     38	method readEmployee (Comment 4)
>     39		is service sampleRead
>     40  }
>     41
>     42  # End

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

Table 5-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 simple client class.

Comment 4

Defines a client class method and its parameter types.

Processing a Script

Issue the following command to process the script.

Listing 5-2 Sample Script Process Command

>     egencobol empclass.egen
>     emprec.cpy, Lines: 21, Errors: 0, warnings: 0
>     Generating sample.EmployeeRecord...
>     Generating group emp-name
>     Generating group emp-addr
>     Generating SampleClass...

Working with Generated Files

This script command generates the following files.

Table 5-2 Sample Script Generated Files

File

Content

SampleClass.java

Source for the sample class.

EmployeeRecord.java

Source for the DataView class.

SampleClass.java Source File

The following listing contains the generated SampleClass.java source file.

Listing 5-3 Sample SampleClass.java Source File

>     // SampleClass.java
>     //
>     // Client class generated by eGenCobol on 24-Jan-2000.

>     package sample;(Comment 1)

>     // Imports

>     import com.bea.jam.egen.EgenClient;
>     ...

>     /* Mainframe client class. */

>     public class SampleClass (Comment 2)
>     	extends EgenClient
>     {
>     	// newEmployee
>     	public EmployeeRecord newEmployee (EmployeeRecord commarea)
>     		throws IOException, snaException (Comment 3)
>     	{
>     		...
>     	}

>     	// readEmployee
>     	public EmployeeRecord readEmployee (EmployeeRecord commarea)
>     		throws IOException, snaException (Comment 3)
>     	{
>     		...
>     	}
>     }

>     // End SampleClass.java

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

Table 5-3 Script Comments

Comment 1

The package name is defined in the eGen script.

Comment 2

The data record is encapsulated in a class that extends the EgenClient class.

Comment 3

The methods convert a raw COMMAREA into a Java DataView object.

Customizing a Stand-Alone Java Application

The stand-alone client class model is the simplest JAM code generation model both in terms of the code generated and customizing the generated code.

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

Figure 5-1 The JAM Client EJB 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 JAM distribution jar file. This base class, illustrated in the following listing provides the basic framework for a client to the jcrmgw. It provides the required methods for accessing the gateway.

Listing 5-4 Generated EgenClient.java Class

>     //==========================================================
>     // EgenClient.java
>     //	Basic functionality for clients of the jcrmgw
>     //
>     //---------------------------------------------------------------

>     package com.bea.jam.egen;

>     public class EgenClient
>      {

>     	public byte[] callService(String service, byte[] in)
>     		throws snaException, IOException
>     	{
>     		// make a mainframe request through the gateway.
>     		...
>     	}
>     }

>     // End egenClientBean.java

The generated class, illustrated in the following listing, adds the methods specific to the users application

Listing 5-5 Sample SampleClient.java Class

>     // SampleClass.java
>     //
>     // Client class generated by eGenCobol on 02-Feb-00.
>     //

>     package sample;

>     // Imports
>     //
>     import java.io.IOException;
>     import com.bea.jam.egen.EgenClient;
>     import com.bea.sna.jcrmgw.snaException;
>     import com.bea.base.io.MainframeWriter;
>     import com.bea.base.io.MainframeReader;

>     /**
>      * Mainframe client class.
>      */
>     public class SampleClass extends EgenClient
>      {
>     	// newEmployee
>     	//
>     	public EmployeeRecord newEmployee(EmployeeRecord commarea)
>     		throws IOException, snaException
>     	{
>     	  // Make the remote call.
>     	  //
>     	  byte[]  inputBuffer = commarea.toByteArray(new
>     		MainframeWriter());
>     	  byte[] rawResult = callService("sampleCreate",
>     		inputBuffer);
>     	  EmployeeRecord   result =
>     			new EmployeeRecord(new
>     			   MainframeReader(rawResult));
>     	  return result;
>     	}

>     	// readEmployee
>     	//
>     	public EmployeeRecord readEmployee(EmployeeRecord commarea)
>     		throws IOException, snaException
>     	{
>     	  // Make the remote call.
>     	  //
>     	  byte[]  inputBuffer = commarea.toButeArray(new
>     		MainframeWriter());
>     	  byte[] rawResult = callService("sampleRead", inputBuffer);
>     	  EmployeeRecord  result =
>     		new EmployeeRecord(new MainframeReader(rawResult)):
>              return result
>     	}
>     ]

>     // End SampleClass.java

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, if desired.

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

Listing 5-6 Sample ExtSampleClient.java Contents

>     // ExtSampleClient.java
>     //

>     package sample;

>     // Imports
>     //
>     import java.io.IOException;
>     import com.bea.jam.egen.egenClientBean;
>     import com.bea.sna.jcrmgw.snaException;
>     import com.bea.base.io.MainframeWriter;
>     import com.bea.base.io.MainframeReader;

>     /**
>      * Extended Sample Class
>      */
>     public class ExtSampleClient extends SampleClass
>     {
>     	// deleteEmployee
>     	//
>     	public EmployeeRecord deleteEmployee(EmployeeRecord
>     		commarea)
>     	throws IOException, snaException
>     	{
>     	  EmployeeRecord erec=(EmployeeRecord) in;
>     	  if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
>     	{
>     	  // The SSN is not valid.
>     	  throw new Error)"Invalid Social Security Number:"+
>     		erec.getEmpRecord().getEmpSsm());
>     	}

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

>     	//updateEmployee
>     	//
>     	public EmployeeRecord updateEmployee(EmployeeRecord
>     		commarea)
>     		throws IOException, snaException
>     	{
>     	  EmployeeRecord erec = (EmployeeRecord) in;
>     	  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.updateEmployee(commarea);
>     	}

>     	// readEmployee
>     	//
>     	public EmployeeRecord readEmployee(EmployeeRecord commarea)
>     		throws IOException, snaException
>     	{
>     		EmployeeRecord erec = )EmployeeRecord)in;
>     		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);
>     	}

>     	//newEmployee
>     	//
>     	public EmployeeRecord newEmployee(EmployeeRecord commarea)
>     		throws IOException, snaException
>     	{
>     	  EmployeeRecord erec = (EmployeeRecord) in;
>     	  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

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

>     	private boolean isSsnValid(BigDecimal ssn)
>     	{
>     	  if (ssn.longValue() < 100000000)
>     	  {
>     	    // Ops, should not have a leading zero.
>     	    return false;
>     	  }

>              return (true);
>     	}
>     ]

>     // END ExtSampleClient.java

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

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.

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