|
|
|
|
|
|
Developing a Multi-Service Data Entry Servlet
This section contains a scenario that shows how to develop a multi-service application, as opposed to the single-service application presented in Generating a Servlet-Only JAM Application. This scenario is based on the general procedures presented in Developing Java Applications, It gives you practical examples for using JAM tools, presented as tasks with step-by-step procedures. This scenario depicts the development of a new application and the updating of existing applications. WebLogic Server samples are used to illustrate any existing applications. All discussions are from the application developer's point of view, presume a properly installed and configured environment, and presume an appropriate mainframe application is available.
Note: Although the sample code in this section represents typical applications, it is intended for example only and is not supported for actual use.
The following tasks are required to develop a multi-service application:
The following section describes the sample programs required for the multi-service application:
Task 1: Use eGen COBOL to Create a Base Application
You must first identify the mainframe application and obtain its COBOL copybook. This is typically a CICS DFHCOMAREA or the user data portion of an IMS queue record layout. The copybook's name in this discussion is emprec.cbl, as shown in Listing 9-1.
Listing 9-1 Mainframe Application COBOL Copybook emprec.cbl
02 emp-record.
05 emp-ssn pic 9(9) comp-3.
05 emp-name.
10 emp-name-last pic x(15).
10 emp-name-first pic x(15).
10 emp-name-mi pic x.
05 emp-addr.
10 emp-addr-street pic x(30).
10 emp-addr-st pic x(2).
10 emp-addr-zip pic x(9).
Step 1: Prepare eGen COBOL Script
In Listing 9-2, the data view emprecData is generated from the copybook named emprec.cbl.
Listing 9-2 Basic eGen COBOL script
view emprecData from emprec.cbl
Step 2: Add Service Entries
Add the single line service entries in Listing 9-3 for create, read, update, and delete operations. They all use empRecData as input and return emprecData as output. In this example, a single data view is used; however, the input and output data views could be different.
Listing 9-3 Service Names Associated with Input and Output Views
service empRecCreate accepts empRecData returns empRecData
service empRecRead accepts empRecData returns empRecData
service empRecUpdate accepts empRecData returns empRecData
service empRecDelete accepts empRecData returns empRecData
Step 3: Add Page Declaration in eGen COBOL Script
Multiple pages can be chained together. Any service entries should match services defined elsewhere in the script. The page declarations shown in Listing 9-4 associate buttons on the HTML display with services declared in the previous step.
Listing 9-4 Page Declaration Associating Display Buttons with Services
page empRecPage "Employee Record" {
view empRecData
buttons {
"Create" service(empRecCreate) shows empRecPage
"Read" service(empRecRead) shows empRecPage
"Update" service(empRecUpdate) shows empRecPage
"Delete" service(empRecDelete) shows empRecPage
}
}Step 4: Add Servlet Name
As shown in Listing 9-5, empRecServlet is the servlet name to be registered as a URL in the WLS properties file. (Every servlet requires a URL to be registered this way. Refer to WLS documentation about deploying servlets for more specific information.) Here, the empRecPage is to be displayed when the empRecServlet is invoked.
Listing 9-5 Add Servlet Name
servlet empRecServlet shows empRecPage
The script is then saved as emprec.egen.
Step 5: Generate the Java Source Code
In Listing 9-6, invoke the eGen COBOL code generator to create the base application that is then compiled. This makes class files (*.class) available for servlet customizing. The empRecData.java is the data view object for emprec.cbl.
Warning: CLASSPATH should include the WLS subdirectories and the jam.jar file; otherwise, the compile fails.
Note: You can create a script file containing the eGen COBOL command line, along with the javac command to make the invocation easier.
Listing 9-6 Generating the Java Source Code
egencobol emprec.egen
ls emp*.java
empRecData.java empRecServlet.java
javac emp*.java
Step 6: Review the Java Source Code
It is a good idea to obtain a list of accessors for use later. In general, you should look at the eGen COBOL output to become familiar with each of the scenarios presented in this section.
The entire method of customizing the generated output is predicated on derivation from generated code. The base application can be regenerated without destroying the custom code.
Note: Each COBOL group item has its own accessor. This is important because the group name represents a nested inner class that must be accessed in order to retrieve the members.
In the Listing 9-7, the output from the grep command shows the relationships in reverse order, for example:
getEmpRecord().getEmpAddr().getEmpAddrSt()
This is illustrated in the actual code example shown subsequently in this scenario.
Listing 9-7 Review the Java Source Code
grep get emp*.java
empRecData.java: public BigDecimal getEmpSsn()
empRecData.java: public String getEmpNameLast()
empRecData.java: public String getEmpNameFirst()
empRecData.java: public String getEmpNameMi()
empRecData.java: public EmpNameV getEmpName()
empRecData.java: public String getEmpAddrStreet()
empRecData.java: public String getEmpAddrSt()
empRecData.java: public String getEmpAddrZip()
empRecData.java: public EmpAddrV getEmpAddr()
empRecData.java: public EmpRecordV getEmpRecord()
Task 2: Create Your Custom Application from the Base Application
The preferred customizing method is to derive a custom class from the generated base application.
Step 1: Start with Imports
In Listing 9-8, BigDecimal supports COMP-3 packed data. HttpSession is available for saving limited state. DataView is the base for emprecData. The empRecData and empRecServlet were generated from the COBOL copybook.
Listing 9-8 Using Imports to Start Creating the Custom Application
import java.math.BigDecimal;
import javax.servlet.http.HttpSession;
import bea.dmd.dataview.DataView;
import empRecData;
import empRecServlet;
Step 2: Declare the New Custom Class
Listing 9-9 shows how to extend the generated servlet. This enables regeneration of the base application without destroying customized code. Fields can be added to the copybook without disrupting the customized code.
Listing 9-9 Declaring the New Custom Class
public class customCrud
extends empRecServlet
{
:
:
Step 3: Add Implementation for doGetSetup
In Listing 9-10, you can see how to provide a new data view and the http session. The HttpSession (s) can be used to hold a reference to the data view. This ensures you are actually in the first pass rather than a browser back arrow. The data view provided (dv) is a fresh instance of the empRecData data view.
Listing 9-10 Add Implementation for doGetSetup
public DataView doGetSetup(DataView dv, HttpSession s){
empRecData erd = (empRecData)s.getValue("customCrud");
if (erd == null)
erd = (empRecData)dv; // use new dataviewStep 4: Continue Implementation for doGetSetup
In Listing 9-11, note the use of group level accessors to obtain fields. This code pre-fills fields with data entry hints as to what fields are required, or how numeric values should be entered. You can fill form data in any manner required prior to displaying.
Listing 9-11 Continue Implementation for doGetSetup
if(erd.getEmpRecord().getEmpSsn().compareTo(BigDecimal.valueOf(0L)) == 0)
erd.getEmpRecord().setEmpSsn(BigDecimal.valueOf(123121234L));
if (erd.getEmpRecord().getEmpName().getEmpNameLast().length() == 0)
erd.getEmpRecord().getEmpName().setEmpNameLast("Entry Required");
if (erd.getEmpRecord().getEmpName().getEmpNameFirst().trim().length() == 0)
erd.getEmpRecord().getEmpName().setEmpNameFirst("Entry Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrStreet().trim().length() == 0)
erd.getEmpRecord().getEmpAddr().setEmpAddrStreet("Entry Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrSt().trim().length() == 0)
erd.getEmpRecord().getEmpAddr().setEmpAddrSt("TX");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrZip().trim().length() == 0)
erd.getEmpRecord().getEmpAddr().setEmpAddrZip("123451234");
Step 5: Finish Implementation for doGetSetup
In Listing 9-12, note the use of the http session putValue to save a reference to the data view. The doGet() processing continues on return. This data will be presented in the displayed form.
Listing 9-12 Finish Implementation for doGetSetup
s.putValue("customCrud",(Object)erd);
return erd;
}Step 6: Create Implementation for doPostSetup
In Listing 9-13, the data view passed in contains values entered into the form by the application user. (The HttpSession is also available for use at this point, if required.)
Listing 9-13 Create Implementation for doPostSetup
public DataView doPostSetup(DataView dv, HttpSession s)
{
empRecData erd = (empRecData)dv;
Step 7: Continue Implementation for doPostSetup
In Listing 9-14, note the use of group-level accessors to obtain fields. This code checks for original defaults, as well as missing data. The SocialSecurity is a BigDecimal object. Validation can be simple or complex as necessary.
Listing 9-14 Continue implementation for doPostSetup
if(erd.getEmpRecord().getEmpSsn().compareTo(BigDecimal.valueOf(0L)) == 0)
throw new Error("Social Security Number Is Required");
if(erd.getEmpRecord().getEmpSsn().compareTo(BigDecimal.valueOf(123121234L)) == 0)
throw new Error("Social Security Number Is Required");
if (erd.getEmpRecord().getEmpName().getEmpNameLast() == null)
throw new Error("Last Name Is Required");
if (erd.getEmpRecord().getEmpName().getEmpNameLast().trim().length() == 0)
throw new Error("Last Name Is Required");
if (erd.getEmpRecord().getEmpName().getEmpNameLast().trim().compareTo("Entry
Required") == 0)
throw new Error("Last Name Is Required");
Step 8: Continue Implementation of doPostSetup
In Listing 9-15, note the use of group-level accessors to obtain fields. This code checks for original defaults, as well as missing data. (Validation routines could have been split out by field.)
Listing 9-15 Continue Implementation of doPostSetup
if (erd.getEmpRecord().getEmpName().getEmpNameFirst() == null)
throw new Error("First Name Is Required");
if (erd.getEmpRecord().getEmpName().getEmpNameFirst().trim().length() == 0)
throw new Error("First Name Is Required");
if (erd.getEmpRecord().getEmpName().getEmpNameFirst()
.trim().compareTo("Entry Required") == 0)
throw new Error("First Name Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrStreet() == null)
throw new Error("Street Address Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrStreet().trim().length() == 0)
throw new Error("Street Address Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrStreet()
.trim().compareTo("Entry Required") == 0)
throw new Error("Street Address Is Required");
Step 9: Continue Implementation for doPostSetup
In Listing 9-16, notice the use of group-level accessors to obtain fields. This code checks for original defaults, as well as missing data. Depending on the application, it may be more advantageous to develop validations as separate methods. This enables routines to be developed and tested with a servlet and easily re-used in an EJB.
Listing 9-16 Continue Implementation for doPostSetup
if (erd.getEmpRecord().getEmpAddr().getEmpAddrSt() == null)
throw new Error("State Abreviation Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrSt().trim().length() == 0)
throw new Error("State Abreviation Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrSt()
.trim().compareTo("TX") != 0)
throw new Error("Texas Employees ONLY");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrZip() == null)
throw new Error("ZipCode Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrZip().trim().length() == 0)
throw new Error("ZipCode Is Required");
if (erd.getEmpRecord().getEmpAddr().getEmpAddrZip()
.trim().compareTo("123451234") == 0)
throw new Error("ZipCode Is Required");
Step 10: Finish Implementation of doPostSetup
In Listing 9-17, the http session getValue is used to remove a reference to the data view. This prevents re-posting the same data twice. The doPost processing continues on return. This data is now passed to the mainframe.
Listing 9-17 Finish Implementation for doPostSetup
else
s.removeValue("customCrud");
return erd;
}
Step 11: Create Implementation for doPostFinal
In Listing 9-18, the doPostFinal occurs after mainframe transmission, but prior to re-display in the browser. This example clears entered data after it is sent to the mainframe. This step completes the custom servlet.
Listing 9-18 Create Implementation for doPostFinal
public DataView doPostFinal(DataView dv, HttpSession s){
empRecData erd = (empRecData)dv;
erd.getEmpRecord().setEmpSsn(BigDecimal.valueOf(0L));
erd.getEmpRecord().getEmpName().setEmpNameLast("");
erd.getEmpRecord().getEmpName().setEmpNameFirst("");
erd.getEmpRecord().getEmpName().setEmpNameMi("");
erd.getEmpRecord().getEmpAddr().setEmpAddrStreet("");
erd.getEmpRecord().getEmpAddr().setEmpAddrSt("");
erd.getEmpRecord().getEmpAddr().setEmpAddrZip("");
return erd; }Step 12: Update the jcrmgw.cfg File with Service Entries
Listing 9-19 defines the entries that are used when the corresponding Create/Read/Update/Delete form buttons are pushed; for example, the Create button triggers empRecCreate which invokes DPLDEMOC. The gateway must be restarted for the new services to take effect.
Listing 9-19 Update jcrmgw.cfg File
empRecCreate RDOM="CICS410"
RNAME="DPLDEMOC"
empRecRead RDOM="CICS410"
RNAME="DPLDEMOR"
empRecUpdate RDOM="CICS410"
RNAME="DPLDEMOU"
empRecDelete RDOM="CICS410"
RNAME="DPLDEMOD"
Step 13: Create Basic Three-Part HTML Frame
In Listing 9-20, the primary frame (identified as "main" in the HTML code) displays the servlet, while an auxiliary frame provides links to HELP pages. The "Built on BEA WebLogic" logo is also displayed. A single line of Java script is used to ensure the window displays in the foreground.
Listing 9-20 Create Basic Three-Part HTML Frame
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>eGen</title>
</head>
<script language="javascript">
<!--
if (window.focus) {self.focus();} // -->
</script>
<FRAMESET cols="20%, 80%">
<FRAMESET rows="20%, 80%">
<FRAME src="bea_built_on_wl.gif" name="logo">
<FRAME src="panel.html" name="aux">
</FRAMESET>
<FRAME src="http://machine.domain.com:7001/empRec" name="main">
</FRAMESET>
</html>
Step 14: Create a Series of Links to HELP Pages
Listing 9-21 shows how the HTML can display as a sidebar frame. The intro.html, emprec.html, and create.html can display inside the "main" frame to provide basic HELP.
Listing 9-21 Creating a Series of HELP Page Links
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head> <title>eGen help</title> </head>
<script language="javascript">
<!--
if (window.focus) {self.focus();} // -->
</script>
<body>
<TABLE summary="This table contains links to help pages.">
<TR> <TH>empRec Info</TH>
<TR> <TD><a href="intro.html" target="help">Introduction </a>
<TR> <TD><a href="emprec.html" target="help">EmpRec </a>
<TR> <TD><a href="create.html" target="help">Create </a>
<TR> <TD><a href="read.html" target="help">Read </a>
<TR> <TD><a href="update.html" target="help">Update </a>
<TR> <TD><a href="delete.html" target="help">Delete </a>
</TABLE>
</body>
</html>
Task 3: Update the JAM Configurations and Update BEA WebLogic Server Properties
Update the jcrmgw.cfg file with the remote service entries shown in Listing 9-22. The Java gateway must be restarted for new services. The entries are used when the corresponding form button is pushed. The Create button triggers empRecCreate, which invokes DPLDEMOC. The service name must match values in the eGen COBOL script. In this example, the RNAME must match an actual CICS program name.
Listing 9-22 Remote Service Entries for Create/Read/Update/Delete
empRecCreate RDOM="CICS410"
RNAME="DPLDEMOC"
empRecRead RDOM="CICS410"
RNAME="DPLDEMOR"
empRecUpdate RDOM="CICS410"
RNAME="DPLDEMOU"
empRecDelete RDOM="CICS410"
RNAME="DPLDEMOD"
Update the weblogic.properties file with the entries shown in the Listing 9-23.
Listing 9-23 Update WLS Properties File
weblogic.httpd.register.customEmpRec=customCrud
Task 4: Deploy Your Application
At this point, you have a basic form capable of receiving data entry, along with some static HTML code for display. The following are standard WLS servlet deployment steps:
Task 5: Use the Application
Figure 9-1 shows the default servlet with customized code displayed in an HTML facade. This type of servlet is useful for presentation, proof-of-concept, and as a test bed for development.
Figure 9-1 New Data Entry Servlet Display
Figure 9-2 shows the servlet with the Create HELP page displayed in a new window over the application.
Figure 9-2 Servlet with HELP Page Displayed
Figure 9-3 is an example of the page used for the front end of the new custom servlet.
Figure 9-3 New Data Entry Servlet Front End Page
Sample COBOL Programs for the Form Buttons
The following listings show COBOL programs for each of the button and service combinations:
All of these programs make use of a CICS temporary storage queue for data. This is a simple technique that is useful for testing and demonstrations.
Create
The simple program shown in Listing 9-24 writes a temporary storage queue using the first eight characters of the employee name as the QID.
Listing 9-24 COBOL Program for Create (DPLDEMOC)
IDENTIFICATION DIVISION.
PROGRAM-ID. DPLDEMOC.
INSTALLATION.
DATE-COMPILED.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TSQ-DATA-LENGTH PIC S9(4) COMP VALUE ZERO.
01 TSQ-NAME.
05 TSQ-ID PIC X(8) VALUE SPACES.
05 FILLER PIC X(30) VALUE SPACES.
LINKAGE SECTION.
01 DFHCOMMAREA.
COPY EMPREC.
PROCEDURE DIVISION.
MAINLINE SECTION.
MOVE EMP-NAME TO TSQ-NAME
MOVE LENGTH OF EMP-RECORD
TO TSQ-DATA-LENGTH
EXEC CICS WRITEQ TS
QUEUE(TSQ-ID)
FROM(EMP-RECORD)
LENGTH(TSQ-DATA-LENGTH)
END-EXEC.
EXEC CICS RETURN
END-EXEC.
EXIT.
Read
The simple program shown in Listing 9-25 reads a temporary storage queue using the first eight characters of the employee name as the QID. If the read fails, the COMMAREA is reset in consideration of the client application so residual data does not appear as the result of a read.
Listing 9-25 COBOL Program for Read (DPLDEMOR)
IDENTIFICATION DIVISION.
PROGRAM-ID. DPLDEMOR.
INSTALLATION.
DATE-COMPILED.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TSQ-DATA-LENGTH PIC S9(4) COMP VALUE ZERO.
01 TSQ-RESP PIC S9(4) COMP VALUE ZERO.
01 TSQ-NAME.
05 TSQ-ID PIC X(8) VALUE SPACES.
05 FILLER PIC X(30) VALUE SPACES.
LINKAGE SECTION.
01 DFHCOMMAREA.
COPY EMPREC.
PROCEDURE DIVISION.
MAINLINE SECTION.
MOVE EMP-NAME TO TSQ-NAME
MOVE LENGTH OF EMP-RECORD
TO TSQ-DATA-LENGTH
EXEC CICS READQ TS
ITEM(1)
INTO(EMP-RECORD)
QUEUE(TSQ-ID)
LENGTH(TSQ-DATA-LENGTH)
RESP(TSQ-RESP)
END-EXEC.
IF TSQ-RESP NOT EQUAL ZERO
MOVE ZEROS TO EMP-SSN
MOVE SPACES TO EMP-NAME-FIRST
MOVE SPACES TO EMP-NAME-MI
MOVE SPACES TO EMP-ADDR
END-IF
EXEC CICS RETURN
END-EXEC.
Update
The simple program shown in Listing 9-26 deletes a temporary storage queue using the first eight characters of the employee name as the QID. It then creates a new queue with the COMMAREA provided.
Listing 9-26 COBOL Program for Update (DPLDEMOU)
IDENTIFICATION DIVISION.
PROGRAM-ID. DPLDEMOU.
INSTALLATION.
DATE-COMPILED.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TSQ-DATA-LENGTH PIC S9(4) COMP VALUE ZERO.
01 TSQ-NAME.
05 TSQ-ID PIC X(8) VALUE SPACES.
05 FILLER PIC X(30) VALUE SPACES.
LINKAGE SECTION.
01 DFHCOMMAREA.
COPY EMPREC.
PROCEDURE DIVISION.
MAINLINE SECTION.
MOVE EMP-NAME TO TSQ-NAME
MOVE LENGTH OF EMP-RECORD
TO TSQ-DATA-LENGTH
EXEC CICS DELETEQ TS
QUEUE(TSQ-ID)
END-EXEC.
EXEC CICS WRITEQ TS
QUEUE(TSQ-ID)
FROM(EMP-RECORD)
LENGTH(TSQ-DATA-LENGTH)
END-EXEC.
EXEC CICS RETURN
END-EXEC.
EXIT.
Delete
This simple program shown in Listing 9-27 deletes a temporary storage queue using the first eight characters of the employee name as the QID. The COMMAREA is reset in consideration of the client application so residual data does not remain after the delete.
Listing 9-27 COBOL Program for Delete (DPLDEMOD)
IDENTIFICATION DIVISION.
PROGRAM-ID. DPLDEMOD.
INSTALLATION.
DATE-COMPILED.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TSQ-DATA-LENGTH PIC S9(4) COMP VALUE ZERO.
01 TSQ-NAME.
05 TSQ-ID PIC X(8) VALUE SPACES.
05 FILLER PIC X(30) VALUE SPACES.
LINKAGE SECTION.
01 DFHCOMMAREA.
COPY EMPREC.
PROCEDURE DIVISION.
MAINLINE SECTION.
MOVE EMP-NAME TO TSQ-NAME
MOVE LENGTH OF EMP-RECORD
TO TSQ-DATA-LENGTH
EXEC CICS DELETEQ TS
QUEUE(TSQ-ID)
END-EXEC.
MOVE SPACES
TO DFHCOMMAREA
MOVE ZEROS TO EMP-SSN
EXEC CICS RETURN
END-EXEC.
EXIT.
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|