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

Generating a Servlet-Only Application

A JAM servlet-only 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 COBOL Code Generator are intended for testing purposes and are not easily customized to provide a more aesthetically pleasing interface.

Action List

Before you generate a servlet-only 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 servlet-only application. | Writing an eGen COBOL Servlet Script
4 | Review script processing and sample script commands. | Processing a Script to Generate Your Application Source Files
5 | Review the generated files. | Reviewing the Generated Files
6 | Customize the application. | Customizing a Servlet-Only JAM Application
7 | Proceed to the next set of instructions. | What Do I Do Next?

Prerequisites

Before you start programming your servlet-only 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

Writing an eGen COBOL Servlet Script

In order to produce a servlet-only application, create an *.egen script file and use the eGen COBOL Code Generator (also called the eGen utility) to generate your typed data record (DataView), and Servlet code. Your DataView files must describe the mainframe services accessed, the browser pages produced, and the servlets that produce them. Service definitions look like the following listing.

Listing 2-1 Sample Service Definition in eGen COBOL Script

>     service sampleCreate
>     	accepts EmployeeRecord
>     	returns EmployeeRecord

Listing 2-1 defines a service named sampleCreate that accepts an input buffer of type EmployeeRecord and returns an output buffer of type EmployeeRecord. This service is configured by an entry in the SERVICES section of the jcrmgw.cfg file. Listing 2-2 provides an example of an entry that configures the service sampleCreate. This example configures the sampleCreate function to run on the CICS410 remote domain (RDOM="CICS410"). The sampleCreate service invokes the CICS program named DPLDEMOC (RNAME="DPLDEMOC"), and it uses the sample.EmployeeRecord schema. The files that actually define the schema are EmployeeRecord.java, EmployeeRecord.xsd and EmployeeRecord.dtd. These files are generated by the eGen utility when support xml is appended on the generate view code line of the script.

Listing 2-2 Sample jcrmgw.cfg Entry for Service sampleCreate

>     sampleCreate		RDOM="CICS410"
>     		RNAME="DPLDEMOC"
>     		TRANTIME=10000
>     		SCHEMA=sample.EmployeeRecord

A browser page that uses this service might be defined as the following.

Listing 2-3 Sample Page Definition

>     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.

The servlet that initiates this page might be defined like the following listing.

Listing 2-4 Sample servlet Definition

>     servlet sample.SampleServlet shows initial

This listing defines an application servlet class named SampleServlet, and specifies that it displays the HTML page named "Initial Page" as its initial display page.

The following listing shows a complete script for defining a servlet application.

Listing 2-5 Sample Servlet-Only Script

>     1  #---------------------------------------------------------
>     2  # empservlet.egen
>     3  #	JAM script for a servlet-only application.
>     4  #
>     5  #  $Id: empservlet.egen,v 1.2 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 support xml
>     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  # Servlet HTML pages
>     32
>     33  page initial "Initial page" (Comment 3)
>     34  {
>     35	view EmployeeRecord (Comment 4)
>     36
>     37	buttons
>     38	{
>     39		"Create" (Comment 5)
>     40			service ("sampleCreate")
>     41			shows fullPage
>     42
>     43		"Read" (Comment 5)
>     44			service ("sampleRead")
>     45			shows fullPage
>     46	}
>     47  }
>     48
>     49  page fullPage "Complete page"
>     50  {
>     51	view EmployeeRecord
>     52
>     53	buttons
>     54	{
>     55		"Create"
>     56			service ("sampleCreate")
>     57			shows fullPage
>     58
>     59		"Read"
>     60			service ("sampleRead")
>     61			shows fullpage
>     62
>     63		"Update"
>     64			service ("sampleUpdate")
>     65			shows fullpage
>     66
>     67		"Delete"
>     68			service ("sampleDelete")
>     69			shows fullpage
>     70	}
>     71  }
>     72
>     73  # Servlets
>     74
>     75  servlet sample.SampleServlet (Comment 6)
>     76	shows initial
>     77
>     78  # End

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

Table 2-1 Script Comments

Comment 1

Defines a DataView class, specifying its corresponding copybook source file and its package file.

Comment 2

Defines a service function and its input and output parameter types.

Comment 3

Defines an HTML page to be displayed by the servlet.

Comment 4

Specifies the DataView class to display on the page.

Comment 5

Defines a button and its associated class method.

Comment 6

Defines a servlet class and its initial HTML display page.

Processing a Script to Generate Your Application Source Files

To process the script, issue the command in Listing 2-6. The egencobol command involves the JVM and is equivalent to java com.bea.jam.egen.EgenCobol empservlet.egen.

Listing 2-6 Sample Script Process Command

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

Reviewing the Generated Files

The empservlet.egen script command generates the following files.

Table 2-2 Sample Script Generated Files

Files

Content

>     SampleServlet.java

Servlet source code

>     EmployeeRecord.java

Source for the DataView object

>     EmployeeRecord.dtd

Generated DTD

>     EmployeeRecord.xsd

Generated XML/Schema

The following listing illustrates the contents of the generated SampleServlet.java source file (with some parts omitted).

Listing 2-7 Sample SampleServlet.java Contents

>     //  SampleServlet.java
>     //
>     //  Servlet class generated by eGencobol on 25-Jan-2000.

>     package sample;

>     //  Imports

>     import javax.servlet.http.HttpServlet;
>     import com.bea.dmd.DataView.DataView;
>     import com.bea.jam.egen.EgenServlet;
>     ...

>     /** servlet class for EmployeeRecord buffers. */

>     public class SampleServlet
>     	extends EgenServlet
>     {
>     	/** Create a new servlet. */
>     	public SampleServlet()
>     	{
>     	   ...
>     	}

>     	/** Get an instance of the initial DataView for this
>     	Servlet.*/
>     	protected DataView initialDataView()
>     	{
>     	   ...
>     	}

>     	...
>     }

>     //End SampleServlet.java

Customizing a Servlet-Only JAM Application

The generated Java classes produced for servlet applications are intended for proof of concept and prototypes, and 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.

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

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

Figure 2-1 The JAM Servlet Class Hierarchy

The generated Java code for a servlet application Sample Servlet is a class that inherits class EgenServlet. Class EgenServlet is provided in the JAM distribution jar file.

The base class illustrated in the following listing provides the basic framework for a servlet.

Listing 2-8 EgenServlet.java Base Class

>     //==========================================================
>     // EgenServlet.java
>     //	The base class for generated servlets.
>     //===============================================================

>     package bea.jam.egen;

>     //Imports

>     ...

>     /****************************************************************
>     * The base class for generated servlets
>     */

>     abstract public class EgenServlet
>     	extends HttpServlet
>     {
>        /** Perform an HTTP Get operation. */
>        public void doGet(HttpServletRequest req,HttpServletResponse
>        resp)
>         throws ServletException, IOException
>        {
>         DataView dv;
>         HttpSession session=reqgetSession(true);

>         ...

>         // Get the initial DataView data record
>         dv = initialDataView();

>         // Invoke the user-defined callback
>         dv = doGetSetup(dv,session);

>         // Convert the DataView into an HTML form
>         ...
>        }

>        /** Perform a HTTP Post operation. */
>        public void doPost(HttpServletRequest req,HttpServletResponse
>        resp)
>         throws ServletException, IOException
>        {
>          DataView dv;
>          HttpSession session=reqgetSession(true);

>         // Move the HTML form data into a DataView
>         ...

>         // Invoke the user-defined callback
>         dv = doPostSetup(dv, session);

>         // Execute the form button
>         ...

>         //Invoke the user-defined callback
>         dv = doPostFinal(dv, session);

>         // Convert the DataView into an HTML form
>         ...
>        }

>        /** User exit for pre-presentation processing for a GET request.
>        */
>        public DataView doGetSetup (DataView in, HttpSession session)
>        {
>         // Default behavior may be overridden
>         return in;
>        }

>        /**User exit for before business logic processing for a POST
>        request. */
>        public DataView doPostSetup (DataView in, HttpSession session)
>        {
>          // Default behavior, may be overridden
>         return in;
>        }

>        /** User exit for after business logic processing for a POST
>         request. */
>        public DataView doPostFinal (DataView in, HttpSession session)
>        {
>         // Default behavior, may be overridden
>         return in;
>        }

>        /** Get an instance of the initial DataView for this servlet. */
>        protected abstract DataView initialDataView();

>        /**
>          * The title for the initial page.
>          * This should be initialized in the subclass constructor.
>          */
>          protected String  m_initialTitle;

>        /**
>          * The buttons for the initial page.
>          * This should be initialized in the subclass constructor.
>          */
>         protected Button[] m_initialButtons;
>      }

>     // End EgenServlet.java

The EgenServlet base class provides functions for the GET and POST operations for the servlet's HTML page.

Both of these operations invoke the following default callback functions:

- doGetSetup() - invoked before the GET operation.

This function occurs prior to the presentation of the HTML page to the user's browser. Any changes made to the DataView object will be reflected in the contents of the HTML page.

- doPostSetup() - invoked before the POST operation.

This function occurs after the HTML page is presented and the user activates a form button. The DataView is sent to the doPostSetup() function, which operates on its contents. For example, validating the contents of the fields.

- doPostFinal() - invoked after the POST operation.

This function occurs prior to the presentation of the HTML page to the user's browser after activating a form button. Any changes made to the DataView object will be reflected in the contents of the HTML page.

Your class (ExtSampleServlet.java), which indirectly extends the EgenServlet base class, overrides these functions and provides additional business logic to modify the contents of the DataView. Each of these functions is passed to the DataView object containing the current record data. Each is expected to return a (potentially modified) DataView object.

Note: The overriding functions must have exactly the same signature as the functions in the base class.

The following illustration shows the sequence of operations that occur during the course of a user's browser session. For example, the series of events that occur within the EgenServlet class.

Figure 2-2 User Browser-Session Flowchart

Example ExtSampleServlet.java Class

The following listing shows an sample ExtSampleServlet class that extends the generated SampleServlet class, and adds a validation function (isSsnValid()) for the emp-ssn (m_empSsn) field of the DataView EmployeeRecord class. The three callback functions are overridden by the functions in the extended class. If the emp-ssn field is determined to be invalid, an exception is thrown.

Exceptions are caught by the Java server (BEA WebLogic Server) and cause a simple informational text page to be presented to the user's browser. Any string text associated with the exception is displayed, along with a trace of the execution stack that was in effect at the time that the exception was thrown.

Listing 2-9 Sample ExtSampleServlet.java Contents

>     //==========================================================
>     // ExtSampleServlet.java
>     // Example class that extends a generated JAM servlet application.
>     //===============================================================

>     package Sample;

>     // System imports

>     import java.math.BigDecimal;

>     import javax.servlet.http.HttpSession;
>     import com.bea.dmd.DataView.DataView;
>     import com.bea.jam.egen.EgenServlet;

>     // Local Imports

>     import sample.EmployeeRecord;
>     import sample.SampleServlet;

>     /***************************************************************
>     */ Extends the SampleServlet class, adding additional business logic

>     */

>     public class ExtSampleServlet
>     	extends SampleServlet
>     {
>     // Public functions

>     	/********************************************************
>     	* User exit for pre-presentation processing for a GET

>     	* request. This is called prior to the presentation of the
>     	* first HTML page to the user's browser.
>     	*/

>     	public DataView doGetSetup (DataView in,
>     					HttpSession session)
>     	{
>     	  EmployeeRecord erec;

>     	  // Overrides the default behavior

>     	  // Load default data into the empty DataView
>     	  erec = (EmployeeRecord) in;
>     	  erec.getEmprecord().setEmpSsn(BigDecimal.valueOf(99999));

>     	  return (erec);
>     	}

>     	/********************************************************
>     	* User exit for before business logic processing for a POST
>     	* request. This is called after the user activates a button
>     	* on the HTMl form, but before the action associated with the
>     	* button is performed.
>     	*/

>             public DataView doPostSetup (DataView in,
>     						HttpSession session)
>     	{
>     	  EmployeeRecord erec;

>     	  // Overrides the default behavior

>     	  // validate the Social Security Number field
>     	  erec = (Employeerecord) in;

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

>     	  return (erec);
>     	}

>     	/*********************************************************
>     	* User exit for after business logic processing for a POST
>     	* request. This is called after the action is performed for
>     	* the button on the HTML form is activated by the user.
>     	*/

>     	public DataView doPostFinal(DataView in HttpSession session)
>     	}
>     		// Overrides the default behavior

>     		// Nothing to do here

>     		return (in);
>     	}

>      // Private functions

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

>     	private boolean isSsnValid(final BigDecimal ssn)
>     	{
>     		if (ssn.longValue() < 100000000)
>     		{
>     			// Oops, the SSN should not have a leading zero
>     			return (false);
>     		}
>     		else
>     			return (true);
>     	}
>      }

>      //End ExtSampleServlet.java

Once it has been written, the ExtSampleServlet class and the other servlet Java source files must be compiled and deployed in the same manner as other servlets.

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.