IBM WebSphere Developer Technical Journal: Using EGL and Struts with WebSphere Studio Enterprise Developer Version 5.0 -- Part 1

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Introductory

Reginaldo Barosa, Certified IT Specialist, IBM Boston

21 Apr 2003

This tutorial describes the architecture that WebSphere Studio Enterprise Developer Version 5.0 uses to deploy applications written with Enterprise Generation Language (EGL) to WebSphere Application Server V5. It describes how to code, test, generate, and deploy a three-tier application consisting of a Web interface, WebSphere Application Server V5, and a server program that performs a DB2 query to access a database.

Introduction

This tutorial describes the architecture that WebSphere Studio Enterprise Developer Version 5.0 uses to deploy applications written with Enterprise Generation Language (EGL) to WebSphere Application Server V5. It will describe in detail the process of coding, testing, generating, and deploying a three-tier application consisting of a Web interface, WebSphere Application Server V5, and a server program that performs a DB2^TM query to access a database.

This tutorial is divided into two parts. Part 1 will explain this process, using WebSphere Studio Enterprise Developer to generate the server program in Java^TM. Part 2 will explain how to generate the server program in COBOL/CICS to run under z/OS, and will describe how to configure the necessary Java Connectors for z/OS execution.

This simple program will be implemented using the standard WebSphere model: servlet => JSPs => Java bean => server. WebSphere Studio Enterprise Developer (hereafter called Enterprise Developer) uses the Struts framework to implement that model. In addition, we will also use EGL to implement this model, which means you won't need Java skills, since all Java and JSP code will be generated by Enterprise Developer.

This tutorial will not focus on the actual coding of the program. Rather, it will describe the production process of coding and testing using Enterprise Developer to deploy to WebSphere Application Server 5.0 (hereafter called Application Server).

If you wish, you may load the included sample program into Enterprise Developer, instead of starting from scratch. See the Download section for more details.

This article applies to WebSphere Studio Enterprise Developer Version 5.0x only. Subsequent versions of Enterprise Developer (such as Versions 5.1, 5.1.2, and so on) have a different EGL syntax, and this tutorial will not work properly with these versions. An article addressing EGL and subsequent versions of WebSphere Studio is planned.

Back to top

What is EGL?

Enterprise Generation Language (EGL) is a development technology that lets you to quickly write full-function programs, evolving from a procedural language that was used in VisualAge^TM Generator. The initial release of EGL lets you use a simple procedural language to create programs of the following types:

• COBOL programs that run as called programs on CICS for MVS.
• Java programs that run on z/OS UNIX^TM System Services, Windows^TM 2000, Windows NT, or Windows XP and iSeries. You can deploy the Java program in the context of any of the J2EE containers:
  • J2EE application client
  • J2EE Web application
  • EJB container; in this case, you also generate an EJB session bean.

There are several benefits to coding with EGL:

• You can quickly implement business logic by using a procedural scripting language and a language-specific debugger, increasing your productivity.
• You can generate Java and COBOL code without having Java or COBOL skills.
• You can focus on the business problem your code is addressing rather than on the technical complexities of CICS, MQSeries, and SQL; for example, you can use similar I/O statements to access different types of external data stores.
• You can produce multiple parts of an application system from the same source. After developing an EGL program, for example, you can generate a Java wrapper, an EJB session bean, and a back-end program. This increased efficiency comes into play when you, say, develop software to give users access to a servlet, which in turn passes data to a generated Java wrapper, which in turn accesses either a generated program on CICS or an EJB Server.
• You can code in response to current platform requirements without worrying about future migration.
• You can produce Java applications and servlets without learning object-oriented programming.
• You avoid having to code a Java connector to communicate between a Web application server and a generated program that runs on CICS for MVS. A generated Java wrapper will marshal the data to be passed between the two.
• You can generate Java and COBOL from the EGL and make it available as a Web service with no additional specialized coding.
• And the biggest benefit: you never need to worry about the level of the generated code. For instance, the generated EJB code will be based on the last supported EJB level, whatever it is, so you don't have to be conscious of EJB specifications for levels like 1.1, 2.0 and so on.

Back to top

What is Struts?

Struts is a set of Java classes and JSP tag libraries that provide a framework for developing Web applications. The Struts technology is open source and was developed as part of the Apache Software Foundation's Jakarta project.

You can use Struts to help you develop applications that are divided into three functional layers:

• Model
  The business logic, which, in most cases, involves access of data stores like relational databases. The development team that handles the model may be expert at writing DB2 COBOL programs, or EJB entity beans, or some other technology appropriate for storing and manipulating enterprise data.
• View
  The code responsible for the presentation layer. The code is composed of JSPs and the Java beans that store data for use by the JSPs.
• Controller
  The code that determines the overall flow of events.

This model-view-controller division (sometimes called model 2) has many inherent benefits, and is often considered a best practice for developing Web applications. For more information on Struts, see the Apache Jakarta Project Web site .

The Struts application development tools that are provided by Enterprise Developer make it easy for you to build and manage a Struts-based Web application. Enterprise Developer acts as follows:

• Lets you set up a Struts project so that taglibs and other Struts-related resources are properly located; as a result, you can reference those resources without fail as you develop your application.
• Provides wizards to create form beans and action classes, giving you have a head start in developing the logic that is specific to your application.
• Includes a specialized editor to create and modify the Struts configuration file.
• Provides Struts support for validation and editing; for example, helping you to use Struts taglibs.
• Provides a visual assembly tool, which has these benefits:
  • helps architects design the flow of a Struts-based Web application
  • embeds Struts code in several components
  • provides quick access to resource-appropriate editors and wizards
  • separates team responsibilities for greater productivity and focus.

Back to top

Solution architecture using Struts and Enterprise Developer

Enterprise Developer uses the Struts architecture shown in Figure 1. At run time, the Application Server contains both the view and controller components of a model 2 Web application, while a third tier (which is usually outside of the Application Server) contains the model.

Back to top

Struts data flow: component details

Struts contributions to the view:

• Struts provides the Java class org.apache.struts.action.ActionForm , which a Java developer subclasses to create a form bean. At run time, the bean is used in two ways:
  • When a JSP prepares the related HTML form for display, the JSP accesses the bean, which holds values to be placed into the form. Those values are provided from business logic or from previous user input.
  • When user input is returned from a Web browser, the bean validates and holds that input either for use by business logic or, if validation failed, for subsequent redisplay.
• Struts provides numerous custom JSP tags that are simple to use but are powerful, in the sense that they hide complexity. The page designer does not need to know much about form beans, for example, beyond the bean names and the names of each field in a given bean.

Struts contributions to the controller:

• The Struts controller servlet handles run time events in accordance with a set of rules that are provided at deployment time. Those rules are contained in a Struts configuration file and specify how the servlet responds to every outcome received from the business logic. Changes to the flow of control require changes only to the configuration file. The controller servlet is an instantiation of class org.apache.struts.action.ActionServlet (hereafter called ActionServlet).
• Struts also provides the Java class org.apache.struts.action.Action , which a Java developer subclasses to create an action class. At run time, the ActionServlet is said to perform actions, meaning that the servlet invokes the perform method of each of the instantiated action classes. The object returned from the perform method directs ActionServlet as to what action or JSP to access next. To promote reuse, invoke business logic from the action class rather than including business logic in that class.

Struts does not contribute directly to model development, but the Struts configuration file provides an elegant way to control the circumstances under which the model components are invoked. But here, Enterprise Developer helps a lot for the model, since it generates the necessary code.

You may notice that this Struts model is very similar to the model used by VisualAge Generator. Since these two models have very similar implementations (Gateway Servlet versus ActionServlet, etc.), a future migration between VisualAge Generator and Enterprise Developer will be that much easier. See Related information for more details.

Back to top

Implementing a simple application using EGL

To better understand Enterprise Developer and its model, we will implement a very simple application using a Web interface. In this application:

• The user types an ID and presses a button to invoke the server program.
• The server program will read a DB2 database to check the ID.
• If found, the server program returns its name. If not found, it will return a message.

The database to be used is the SAMPLE database, and the table to be used is the STAFF table. The flow is shown in Figure 2.

The next steps will guide you through the creation, testing and deployment of the application shown above. To complete this application you will need:

• IBM WebSphere Studio Enterprise Developer Version 5.0
• IBM DB2 UDB Version 7 (although this will probably work with previous versions as well), with the database SAMPLE created.

The examples shown here are using DB2 Version 7.2. Before adding the DB2 JAR file to your environment, be sure that you are using the correct JDBC (JDBC2). One easy way to check is to go to the directory C:\SQLLIB\java12 and check if the file inuse is there. If it is not, you will need to execute the command usejdbc2.bat (refer to the appropriate DB2 documentation for assistance).

If you prefer, you may import the complete solution instead, following the instructions in the Download section.

Back to top

Building an EGL server program

It's a good practice to start coding a program from the back end, defining first the database layouts and fields. The first steps, then, will be to define the variables and record layouts, with the program logic coming later.

Again, the EGL server program will do a simple inquiry in the STAFF table (part of the SAMPLE database), and if the userid is found the server program will get the name; if not, then a message will be moved to indicate an invalid userid. If an error occurs connecting to the database, a message will be shown on another Web page.

The EGL source code under Enterprise Developer could be stored in a variety of locations, but for the purposes of this tutorial, all EGL components will be created under the folder EGLWeb/Java Source .

The following tasks need to be performed to implement this example:

1. Set Enterprise Edition EGL preferences to enable DB2 access
2. Create the EGL components
3. Interpretive Debug an EGL program
4. Generate EGL Java code

1. Set Enterprise Edition EGL preferences to enable DB2 access

Using Enterprise Developer, prepare your workspace with the appropriate DB2 settings. This activity is usually done once, and is necessary since it provides the required defaults.

1.1 Set EGL Interpretive Debugger preferences

Enterprise Developer lets you debug EGL programs with the EGL Java debugger or with the EGL Interpretive Debugger. To use the EGL Java debugger, you must first generate all the EGL programs that you want to be included in the debugging session. When using the EGL Interpretive Debugger, you do not need to generate your EGL programs first. You simply write your program and start debugging.

To set the EGL Interpretive Debugger preferences, select Windows => Preferences => EGL => Interpretive Debugger. Our example will run under Windows, and we will be logged in as db2admin , which is also our SQL userid. Therefore, as shown in Figure 3, the following values are specified:

• EZESYS: WIN (other alternatives are: ISERIESJ , MVSCICS , or USS )
• EZExxx special worlds: db2admin
• Class Path Order: Indicate where the required DB2 classes ( db2java.zip ) are.

1.2 Set default database connection

To set the default data base connection, select SQL Database Connections and check the selections as shown in Figure 4. Be sure that the correct DB2 JAR file is specified in the Class location field.

2. Create the EGL components

The EGL definitions are stored in one of three file types:

• Program file:
  • Extension: .eglpgm
  • Contains a program part. The name of the program file must match the name of the program part. In our example, the program will be named TE01A .
  • Can import any number of definitions files.
  • Written in EGL source format.
  • What you test or generate.
• Definitions file:
  • Extension: .egldef
  • Can contain any number of functions and data parts.
  • Can be imported by program files or by other definition files.
  • Written in EGL source format.
• Build file:
  • Extension: .eglbld
  • Can contain any number of build parts, which determine how a program is generated and prepared.
  • Can import other build files.

You will create an EGL definitions file, called SAMPLE, which will contain:

• a DB2 record definition (STAFF) to use when accessing the staff table
• a record definition (TE01W01) to use when communicating with the EGL server program.

By having these records in a separate file from the program, one definition can be easily maintained and still shared by multiple programs. Also, by storing all of the record definitions for the SAMPLE database in a separate file, the database administrator could be given the responsibility of creating and maintaining this file for developers to use.

Where is the EGL source stored in the Enterprise Developer project? You must define where to store an EGL file. Within a Web application, you can place EGL source folders in three locations:

• under Java source
• under Web content
• directly under any project.

There are advantages and disadvantages to each of those locations. To make our code easier to import and export, we will store the EGL files under the Java source. This way, if we export a WAR or EAR file with source, the EGL source will be included. There is still one disadvantage: the EGL files are copied to Web Content\WEB-INF\classes . This creates duplicates that appear when selecting a build descriptor to generate Java or COBOL code. A developer could also inadvertently make changes in the duplicated version in WEB-INF . Those copies are recreated at each project build.

Please refer to Chapter 8 of the IBM Redbook Legacy Modernization with WebSphere Studio Enterprise Developer for more information.

2.1 Create the Web project

The Web project is a container for resources, such as source files and metadata that correspond to the hierarchy of files necessary to deploy a Web page or Web application. To create a Web project:

1. Start Enterprise Edition.
2. Open the EGL Perspective.
3. In the Navigator view, select Ctrl+N => Web => Web Project to create a Web project.
4. In the "Define the Web Project" dialog, enter the following values:
   • Name of the Web project: EGLWeb
   • Web project features: select Add Struts support
   • Select Next .
5. In "J2EE Settings" dialog, set the value of New project name to: EGLEAR . Select Finish .

The wizard will create an empty project container primed with the appropriate content folder structure. The folders created will have files that are part of the Struts framework, as illustrated by the red boxes in Figure 5. You can now begin creating the content.

2.2 Create SQL record

In this step, you will perform the following tasks:

1. Using the EGL Perspective in the Navigator view, select EGLWeb/Java Source , then Ctrl+N .
2. Using the wizard, select EGL from the list on the left, then double-click on EGL Definitions File in the list on the right.
3. Select the EGLWeb/Java Source folder. Set the value of File name to: SAMPLE . Select Next .
4. In the "Add Import Statements" dialog, select Next .
5. In the "Select Type of Part to Add" dialog, select Record , then Next .
6. In the "Enter Record Name..." dialog, set the value of Name to: STAFF . Select Next .
7. In the "Select Record Organization" dialog, select SQL Record , then Next .
8. In the "Enter SQL Properties" dialog, select Add . Set the value of Name to: db2admin.staff . Keep the value of Label as T1 . Select Finish . (If your STAFF table was created with a qualifier other than db2admin , you must change it or the table will not be found.)
9. The editor is opened with SAMPLE.egldef . Right click in the editor area, and from the context menu select Retrieve SQL . The result of this operation is shown in Figure 6.

1. Save your changes using Ctrl+S , but do not close the editor.

2.3 Create a working area (working storage)

TE01W01 is our working storage record, a temporary data area defined for a program. Later, you will declare TE01W01 to be the parameter data area in our server program. This will be used when the client that calls the server program passes the userid. On return, the server program passes the name and a message (if the userid is invalid) in TE01W01.

You can use the EGL Source Editor to define the TE01W01 record:

1. To add a record definition, place the cursor on the last line of code in the editor. Type Ctrl+Space , then double-click on Record .
2. Create the data items ID and NAME for record TE01W01 . You can copy ID and NAME definitions from the STAFF record.
3. Close the file. The results are shown in Figure 7.

2.4 Create an EGL Program file

By having the data areas above defined first, code assist can help when inserting data references into a program's or into a function's logic. This is generally faster and more accurate than doing so by hand. Data areas must be both defined and declared in a program or function before any reference to them becomes valid.

Since the STAFF and TE01W01 records are defined in another file, named SAMPLE.egldef , the IMPORT statement will link those definitions to our program. These records can be declared as parameters or as variables. Parameters are passed to a program or function from an external source, whereas variables are data areas internal to a program or function. In our EGL server program, the TE01W01 record will be declared as a parameter, and the STAFF record will declared as a variable:

1. Using the EGL Perspective in the Navigator view, select EGLWeb , then Ctrl+N .
2. Using the wizard, select EGL from the list on the left, then double click on EGL Program File in the list on the right.
3. Select the EGLWeb/Java Source folder. Set the value of File name to: TE01A . Select Next .
4. In the "Create EGL Program File - Add Import Statements" dialog, select Add... .
5. In the "Add Import" dialog, expand EGLWeb and select SAMPLE.egldef .
6. Select Next twice.
7. In the "Add a Program Part - Enter Program Parameters..." dialog, select Add... .
8. In the "Add Parameter" dialog, set the value of Parameter name to: TE01W01 , then select Next .
9. In the "Add a Program Part - Enter Program Variables..." dialog, select Add... .
10. In the "Add Variable" dialog, set the value of Variable name to: STAFF .
11. Select Finish .
12. Add the code as shown in Figure 8.

1. Save and close the editor.

2.5 Edit SQL default select conditions

SQL default select conditions are stored in the declaration of an SQL record. The conditions define part of the criteria by which rows are selected in default SQL statements. To edit SQL default select conditions:

1. Open a record definitions file with the EGL part editor by right-clicking on SAMPLE.egldef and selecting Open With => EGL Part Editor . The editor displays the SQL structure.
2. Select Show SQL Default Select Conditions on the EGL part editor toolbar ( ).
3. Set the Default select conditions field by by entering select conditions without the WHERE keyword, for example: ID = :ID . See Figure 9.
4. In the Default select conditions field, right-click and select Check SQL Statement to perform a syntax check on your SQL statement. If an error is detected, the SQL Errors view is displayed with information about the error.

1. Save and close the editor.

2.6 Create Build Descriptors for the EGL program

EGL will generate code such as Java or COBOL, but the user still needs to provide information like the java package name to be generated, the target operating system, database name, etc. These specifications are stored in the build descriptor part controls. The parts contain several kinds of information:

• Build descriptor options
  Specifies how to generate and prepare EGL output. A subset of the build descriptor options can cause other build parts to be included in the generation process.
• User-defined substitution parameters
  Allows you to establish qualifiers for use in specific directory names.
• Java runtime properties
  Assigns values to some specific "eze" terms like ezedtelc, ezedaylc and ezeconct. Java runtime properties have no effect when you generate COBOL.

2.6.1 Create Build Descriptor for debugging

Before generating the code for production, it's a good idea to debug the EGL code. You must create a build descriptor for that; we will name it intdebug . To create the descriptor:

1. Select the project EGLWeb , then Ctrl+N .
2. In the "New - Select" dialog, select EGL from the list on the left, then double click on EGL Build File in the list on the right.
3. In the" Create EGL Build File - Select Container" dialog:
   • Select the folder EGLWeb/Java Source .
   • Set the value of File name to: TE01ABuild .
4. Select Next twice.
5. Using the "Add EGL Build Part - Select Type..." wizard, select Build Descriptor , then select Next .
6. In the "Add a Build Descriptor Part - Enter Build Descriptor Name..." dialog, set the value of Name to: intdebug , and select Finish . TE01ABuild.eglbld is opened for editing.
7. intdebug is added to the Outline view, and the part opens ready for editing. In the editor, from the Build option filter drop down list, select Java Debugging (Basic) . The table of build options changes to show only those relevant for debugging. Use the following table for the specifications:
   
   

   Options	Value
   debug	yes
   J2EE	no
   package name	EGL
   sqIDB	jdbc:db2:SAMPLE
   sqlJDBCDriverClass	COM.ibm.db2.jdbc.app.DB2Driver
   system	WIN

8. Save your changes using Ctrl+S .
9. Select Show only specified options and compare to Figure 10:

1. Save and Close the editor.

3. Debug an EGL program interpretively

As mentioned earlier, you do not need to first generate your EGL program to use the EGL Interpretive Debugger . You simply write your program and start debugging. The debugger and the EGL part editor (or source editor) together let you do the following tasks:

• Set and remove breakpoints in code where you want the debugger to stop.
• Step through EGL code statement-by-statement. You can step into called functions or programs, or just treat the calls as part of running the current statement.
• Run from the current statement until a breakpoint (or the end of the program) is reached.
• Examine variable values defined in the current EGL program and in the functions invoked when the debugger is stopped.
• Change variable values when the debugger is stopped. You can sometimes temporarily adjust to code problems by changing incorrect values to those that would have been produced by correct code. This lets you continue the debugging session, and avoid having to regenerate and restart the debug session at each error or breakpoint.
• Display the current call stack of programs and functions. Entries on the call stack can be selected, causing variables at the time of invocation to be displayed.

3.1. Set a breakpoint in account.eglpgm

In our example, let's set a simple breakpoint for examining and modifying variable contents:

1. In the Navigator view, double-click on TE01A.eglpgm .
2. In the editor, double-click in the left margin of the line: staff.ID = TE01W01.ID . A blue sphere appears indicating a breakpoint is set for this line. See Figure 11.

1. Close TE01A.eglpgm

3.2 Create interpretive debug launch definition for account.eglpgm

1. Open a Debug Perspective. From the menu bar, select Run => Debug...
2. When the "Launch Configurations" window opens, right-click on Debug an EGL Program Interpretively , then select New .
3. Set the value of Name to: TE01A .
4. Using the Browse button, set the value of Project to: EGLWeb .
5. Using the Browse button, set the value of EGL Program name to: Java Source/TE01A.eglpgm .
6. Select Debug .
7. When the "Select a Build Descriptor" window displays, select the already defined intdebug build descriptor, then OK .
8. A warning will display, since TE01A expects one parameter. Select Yes to continue.

3.3 Debug the EGL program

1. The debugger stops on the first line of the code in TE01A.eglpgm . In the Variables view (upper right corner), expand the structure STAFF => TE01W01 => ID .
2. Under TE01W01, set ID=30 (you only need to double-click).
3. Step through the program, observing the changes to the account variable (select Run => Step Over from the menu bar, or select Step Over in the tool bar, or press F6 ).
4. Check that the program is accessing the table and retrieving the name. After the program has terminated, close the Debug Perspective. Figure 11 shows the contents of the variables when the program is running fine:

1. Close TE01A.eglpgm editor.

4. Generate EGL Java code

After the interpretive debug test results are fine, it is then time to generate the Java code to be used later. You will create two build descriptors now that will be used to generate the Java Server components:

• win-java
  This build descriptor will define how to create a set of Java class files to perform the EGL logic.
• wrapper
This build descriptor will define how to create a Java wrapper file which will provide a connector to our EGL server program.

4.1. Create a build descriptor for Java code generation

1. In the Navigator view, double-click on TE01ABuild.eglbld .
2. In the Outline view, right-click on the TE01ABuild , then select Add part= .
3. The "Add EGL Build Part" wizard appears. Select Build Descriptor, and click Next.
4. In the "Add EGL Build Part - Enter Build Descriptor Name" dialog, set the value of Name to: win-java , then select Finish .
5. The win-java part is added to the Outline view, and the part opens ready for editing. From the Build option filter drop-down, select Java Target System (All) . The table of build options changes to show only those relevant for generating Java code.
6. Enter the following values:
   • debug drop down: select YES
   • genProject: select EGLWeb
   • genProperties: Yes
   • J2EE: select YES
   • packageName: eglweb.java
   • sqlDB: jdbc/SAMPLE
   • system: select WIN
7. Save your changes using Ctrl+S .
8. Check Show only specified options to reduce the list of options to only those entered. Compare to the list in Figure 13.

4.2. Create a build descriptor for Java wrapper generation

An EGL-generated Java wrapper is a set of classes that acts as an interface between a servlet or Java program and an EGL-generated program. A java wrapper makes calling our EGL server quick and easy for a Java programmer by providing methods to call the server, and methods to get and set the parameter values. The Java wrapper will marshal parameter data between Java objects and record structures (for generated COBOL programs), convert data between ASCII and EBCDIC, and handle all communications.

When you request that a program part be generated as a Java wrapper, EGL produces a wrapper class for:

• the generated program
• each record or structure that is declared as a parameter in that program.

The Java wrapper build descriptor will have these options set:

• linkage : points to a set of options that describe how to call the EGL server program.
• nextBuildDescriptor : adds the option settings from another build descriptor to the options defined in this build descriptor, such as genProject , genProperties , and packageName .
• system=JAVAWRAPPER : causes the Java wrapper classes to be generated.

To create the Java wrapper build descriptor:

1. In the Outline view, right-click on TE01ABuild , then select Add part= .
2. The "Add EGL Build Part" wizard appears. Select Build Descriptor , then Next .
3. On the "Add EGL Build Part - Enter Build Descriptor Name" dialog, set the value of Name to: wrapper , then select Finish .
4. The wrapper part is added to the Outline view, and the part opens ready for editing. From the Build option filter drop-down, select Java Wrapper (All) . The table of build options changes to show only those relevant for generating Java code.
5. Enter the following values:
   • linkage: linkageTE01A
   • nextBuildDescriptor: select win-java
   • system: JAVAWRAPPER
6. Save changes using Ctrl+S .
7. Check Show only specified options to reduce the list of options to only those entered. Compare to the list in Figure 14.

4.3. Create linkage part

A linkage part defines how the generated Java wrapper should invoke a called EGL program.

1. In the Outline view, right-click on TE01ABuild , then select Add part= .
2. The "Add EGL Build Part" wizard appears. Select Linkage Options , then Next .
3. In the "Add EGL Build Part - Enter Build Descriptor Name" dialog, set the value of Name to: linkageTE01A , then select Finish .
4. The linkageTE01A part is added to the Outline view, and the part opens ready for editing. In the editor, select Add... at the bottom of the callLink elements table.
5. Enter the following values:
   • Program Name: TE01A
   • Type: select remoteCall
6. Save your changes using Ctrl+S .
7. In the "Properties of selected callLink elements" box, enter the following values:
   • location: localhost
   • package: eglweb.java
   • remoteBind: select GENERATION
   • remotePgmType: select EGL
8. Save your changes using Ctrl+S . Your linkage should look like Figure 15.

1. Close the TE01ABuild.eglbld file.

A brief description of the options you specified:

4.4. Set EGL default build descriptors

When default build descriptors are set within the properties for a project, folder, or individual EGL program, a build descriptor does not have to be specified for each generation request. To set default build descriptors (Figure 16):

1. In Navigator view, right-click on EGLWeb , then select Properties from the context menu.
2. In the "Properties" dialog, select EGL Default Build Descriptors from the list on the left.
3. Enter the following values:
   • Target system build descriptor: win-java (EGLWeb/Java Source/TE01ABuild.eglbld)
   • Java debugging build descriptor: intdebug (EGLWeb/Java Source/TE01ABuild.eglbld)
   • Java wrapper build descriptor: wrapper (EGLWeb/Java Source/TE01ABuild.eglbld)
4. Select OK .

4.5. Generate a Java EGL server program

To invoke the generation wizard, right-click on a resource name in the Navigator view and select Generate EGL.... All of the program parts that are at the top level in all the files nested within that resource are generated. The wizard presents you with all the top-level EGL programs, and you select which ones you want to be generated. For example, if you select a project resource, each program part that is at the top level of an .eglbld file stored in the project is presented for you to select. Since we specified the default build descriptors earlier, the generation will be easier.

To generate the Java EGL server program:

1. Switch to the EGL perspective.
2. In the Navigator view, right-click on TE01A.eglpgm in the EGLWeb project. Then, select Generate EGL with => Target System and Java Wrapper Build Descriptors from the context menu.
3. The Generate wizard appears. Make sure that TE01A is selected in the list of parts to generate. Since the project property EGL Default Build Descriptors was already set, nothing more needs to be done. Select Finish
4. EGL generation will now begin. When finished, check for messages in the Generation Results view for both TE01A(wrapper ) and TE01A(win-java) that indicate generation completed with no errors.

Observe that multiple files, such as TE01A.java and Te01aWrapper.java , have been generated into the EGLWeb/Java Source/eglweb/java folder, as shown in Figure 17.

Notice also that since the server program is Java, some environment variables will be added in the deployment descriptor ( web.xml ) that are specific to the generated EGL Java program. These variables reflect those that you specified at the win-java deployment descriptor. Figure 18 shows web.xml file being edited with the deployment descriptor editor.

At this point, we now have all the Java server code and the Java wrappers ready to be used by the client side of the application.

Back to top

Building the client side of the application

The Struts framework will be used to code this example. The Struts tools in WebSphere Studio Enterprise Developer provides the following wizards:

It is now time to use these wizards so that we can perform the next series of tasks. To help out, Enterprise Developer provides a new super wizard, called Cheat Sheets, (sort of a wizard of the wizards) to guide users through the development process with a sequence of steps to build a Struts-based Web project.

Back to top

Using Struts EGL Cheat Sheets

A Cheat Sheet is a program that helps you accomplish a complex task that involves a variable series of subtasks. The Struts EGL Cheat Sheet creates a Struts-based Web application that uses EGL. It's a good advisor for beginners or anyone who would like the added guidance.

To launch a Cheat Sheet, click Help => Cheat Sheets from the menu bar. The five Cheat Sheets that were used most recently are listed in the cascade menu. You can also select Other... to open a dialog to let you choose another Cheat Sheet. The Cheat Sheet opens as a view. Only one Cheat Sheet can be open and active at any given time, so any open Cheat Sheet will be closed before a new one is opened. The completion status of a closed cheat sheet is saved.

Generally speaking, to create a Struts-based Web project using a Cheat Sheet:

• Select Help => Cheat Sheets => Other... => Web Application With EGL Cheat Sheet .
• The "Cheat Sheet" dialog opens, and you follow the steps.
• When selected, the Click to perform button launches a tool (which can be a wizard), and you will be required to work with that tool. When you finish working with that tool, the next step is automatically highlighted and it becomes the current step.
• When the current step is a manual task, you will need to perform the work and select the Click to complete button to move to the next step.
• A check mark appears in the left margin of each completed step.

The sequence of steps that we will execute, guided by Cheat Sheets, are listed below, and also in the Cheat Sheet shown in Figure 19.

1. Create a Web project
2. Create a Web diagram
3. Create the JSPs (Web pages) and beans
4. Create the Struts actions
5. Implement the business logic components
6. Generate and compile EGL components
7. Run the Web application .

1. Create a Web project

2. Create a Web diagram

The Web diagram is a file that helps you visualize the flow structure of a Struts-based Web application. The table below shows the fields you need to enter values for, in the dialog's sequence:

The Web diagram editor will be opened. A useful feature of the Web diagram editor is the ability to reflect any changes of the underlying resources in real time. In our example, on the editor's free-form surface (FFS) you will create nodes for a Web page named index.jsp , result.jsp and error.jsp that do not yet exist. A node that appears on the FFS before being implemented is called unrealized. After creating the JSP outside of the diagram editor, the diagram editor will be informed of the JSP creation and reflect the change in its diagram.

Similarly, if a realized part shown in the diagram has its underlying resource deleted, the diagram editor will be informed of this deletion and reflect the change in the diagram. You can use the diagram editor to show all or part of a Struts application. You can also interact directly with the parts that are represented within a diagram. For example, you can invoke the JSP editor directly from the diagram editor.

Using the diagram editor:

1. Drop and name the icons as follows:

1. Now, drop and connect the icons as shown:

1. Save the diagram using Ctrl+S .
2. Return to the "Cheat Sheet" dialog by selecting the icon located at the left side of the workbench.

3. Create the JSPs (Web pages) and beans

3.1 Create InquiryForm

A form bean, a type of Java bean, is an instance of an ActionForm class subclass that either stores HTML or JSP form data from a submitted client request, or stores input data from a link that a user selected. An HTML or JSP form is made up of fields into which a user can enter information.

When a browser submits an HTML form, the Struts ActionServlet does the following:

• Looks at the field names from the HTML form.
• Matches them to the properties' names in the form bean.
• Automatically calls the setter methods of these variables to enter the values retrieved from the HTML form.

In addition, if you implement a validate method and set the validate flag in the corresponding action mapping entry in the Struts configuration file, the ActionServlet will invoke the validate method.

We could create the JSPs and then later create the form bean, but creating the form bean first helps when the JSP models are generated. To create a form bean:

1. Double click on InquiryForm .
2. In the "NewActionForm Class" dialog, accept all the defaults, then select Next .

1. In the "Choose new accessors" dialog of the wizard, select Next .
2. In the "New ActionForm class - Create new accessors..." dialog, select Add... .
3. Enter values for ID and name, as shown in Figure 23. (Tab out of the Type column to make sure the value is accepted.) By defining the fields now, we can use one of the Struts tooling features to create a JSP with these fields in a default layout.

1. Select Finish to generate InquiryForm .
2. The Java class InquiryForm is created and the editor is opened. Take a look at the generated code, and notice that the getter and setter methods for ID ( getID and setID ) and name ( getName and setName ), as well as a validate method, have been created. The validate method can be used to validate the fields in your form.
3. Close the editor.

Note that:

• struts-config.xml has been updated
• the class is named InquiryForm
• the form bean to Struts is named inquiryForm (with a lowercase i; be careful, this could cause confusion).

The generated xml looks like this:

3.2 Create error.jsp

To create error.jsp :

1. Double click on error.jsp .
2. Accept all the defaults, then select Finish .
3. Using the editor and the Design view, enter the error message: Error! Could be problems with Data Base connection. Check WebSphere Console.
4. Save the data. The results are shown in Figure 24.

3.3 Create index.jsp.

To create index.jsp :

1. Double click on index.jsp .
2. Using the "New JSP File" wizard, accept all the defaults.
3. Select Next (five times) until you reach the "Form Field Selection" dialog.
4. In the "Form Field Selection" dialog, select the following values (Figure 25), then select Finish .
   • Form bean entry: select inquiryForm
   • field: ID

1. Enterprise Developer automatically creates index.jsp with Struts taglib references, and with the selected ID field. The JSP opens ready for editing. Notice that the generated JSP includes the ID field selected, as shown in Figure 26.

1. Change the text as shown in Figure 27.

1. Save your changes using Ctrl+S and close the editor.

3.4 Create result.jsp

To create result.jsp :

1. Double-click on result.jsp .
2. Accept all defaults, then select Finish .
3. Enterprise Developer automatically creates result.jsp with Struts taglib references. The JSP opens ready for editing, displaying the line: "Place result.jsp's content here." Replace this line when following the next steps.
4. Change the attributes of the line to Heading 2 .
5. Press Enter to get a new line inside the form.
6. Select Ctrl+T to insert a table.
7. In the "Insert Table" dialog, select OK .
8. A 2x2 table displays. Place the cursor in the first cell of the first row of the table, and enter USERID .
9. Place the cursor in the second cell of the first row (upper right). From the menu bar, select JSP => Insert Custom... .
10. In the "Insert Custom Tag" dialog, under Tag libraries in document, select /WEB-INF/struts-bean.tld .
11. For Custom tag, select write , then select Insert . Do not close this window, because you will use this window again. Just move it out of the way for now.
12. In the first cell of the second row, enter NAME.
13. Tab to the second cell of the second row.
14. In the "Insert Custom Tag" dialog, under Tag libraries in document, select /WEB-INF/struts-bean.tld .
15. For Custom tag, select write , then select Insert .
16. Select Close.
17. From the menu bar, select JSP => Show Visual Custom Tags . This will uncheck Show Visual Custom Tags , which will cause a button to appear for the bean:write tag.
18. Place the cursor under this table, press Enter , then type Click here to return to the Index Page.
19. Select the text you just entered (highlight the entire line), right-click, then select Insert Link...
20. In the "Insert Link" dialog, enter the following values:
    • Type: File
    • URL: index.jsp
    Select OK . The result are shown in Figure 28.

1. Select the Source tab at the bottom of the editor.
2. Change the struts tags, as follows:
   <bean:write name=" inquiryForm " property=" ID " />
   <bean:write name=" inquiryForm " property=" name " /> Be careful that the form bean name is inquiryForm (first letter lowercase), even though the Java class will be InquiryForm . It's a common mistake to get these two names confused. The results of the coding changes are shown in Figure 29.

1. Save your changes using Ctrl+S .
2. Check the Tasks view. There should be no errors for result.jsp . Resolve any that do appear. Note that /inquiry is still not defined, and there is a warning at the Tasks view. We will solve that in the next step.
3. Close result.jsp editor.

You have now created the three JSPs that you will need. Notice that now the JSP nodes appear in color in EGLflow.gph , indicating that they have been realized. If the "Select Web Pages" window is still open, close it.

4. Create the Struts actions

A Struts action is an instance of an Action class subclass that implements a portion of a Web application and returns a forward. An action mapping is a configuration file entry that associates an action name with an action, a form bean, and a local forward.

During this step you will define and realize the Action inquiry associated with the Web diagram. In the action mapping wizard you will invoke the EGL business logic. Using the Cheat Sheets:

1. Select the perform icon .
2. In the Select Action dialog, double-click on inquiry(Unrealized) .
3. The "New Action Mapping" wizard appears. Enter the following values, as shown in Figure 30:
   • Form Bean Name: select inquiryForm
   • Model: select EGL Struts Action
   Select Next .

1. In the "New Action Mapping - Create a EGL Struts Action" dialog, select EGL Wrapper (Figure 31), then select Next .

1. In the "New Action Mapping - Define data mappings" dialog, enter or alter the following values:
   • in Input Mappings, since we have only one input field in our JSP form:
     • enter (short)iD , using the Add (form bean) button
     • remove name , using the Remove button.
   • in Output Mappings, use the Add (reuse form bean) button:
     • enter (short)id
     • enter (String)name
   This is performed in the "Add a form bean mapping" pop-up, so you can just select ID in Input and Output, select Add , then repeat for name , and select Done . The result is shown in Figure 32.

1. Select Finish .

Notice that a class named InquiryAction.java is created and the editor is opened. If you like, you can take some time to understand the generated Java code. Go to the method perform , which is the method responsible for calling the Java classes generated by the EGL code and passing parameters to it. This might be a good place for a breakpoint, should you want to follow the execution logic. Notice also that the ID field is being passed to the generated EGL Java Wrapper ( Te01aWrapper ) via the working storage using the Te01w01 generated Java bean. See the perform method in Figure 33.

4.1 Check the Struts forwards

A Struts forward is an object that is returned by an action, and that has two fields: a name and a path (typically the URL of a JSP). The path indicates where a request is to be sent, or forwarded. A forward can be local (pertaining to a specific action) or global (available to any action).

Be sure that the forward is defined correctly in the method perform of the InquiryAction class. If there are no errors in the server program, the forward is valid; if there are errors, it will be invalid.

You will need to move the line with the invalid forward to the correct location, shown in Figure 34.

Save and close the editor. The Struts framework is now ready. According to the Cheat Sheets, the next step would be to implement the business logic components (EGL).

5. Implement the business logic components

In this step, you create the EGL program to implement the business logic. We already did this in previous steps , since we found it easier to be able to reuse the field definitions when creating the server program. However, we could have created the EGL source code here using the EGL wizards instead.

6. Generate and compile EGL components

7. Run the Web application

To run the application:

1. Select which WebSphere Application Server the application will run. Click on the perform icon to start the wizards.
2. Set the following values:
   • Folder: select EGLWeb , which was created earlier.
   • application server: WebSphere version 5.0 . Optionally you could use a WebSphere Application Server that you had already defined.
3. The code is published, and WebSphere Application Server is started. When the message WSVR0001I: Server server1 open for e-business displays on the console, the browser is open and the screen shown in Figure 35 displays.

1. Enter the value 30 for Userid, then select Submit .
2. You should have an error (see all red messages) listed on the WebSphere console, and the error.jsp should display, as shown in Figure 36.

1. The messages on the WebSphere console read: VGJ0700E An error occurred during database connection: jdbc/SAMPLE.
   VGJ0005I The error occurred in TE01A.

What's wrong?

The generated EGL Java code uses the WebSphere data source to access the database. When we defined the build descriptors for the EGL, we specified jdbc/SAMPLE , and that JNDI name must be defined for the WebSphere. Be aware that database-related errors could also occur due to WebSphere security issues, or possibly bad configurations.

If the error above is shown, the Struts action actually worked fine, since in this situation the application returned an invalid forward and properly displayed the error.jsp .

7.1 Define a data source to WebSphere test environment

As defined in the Sun JDBC 2.0 Standard Extension specification, data sources allow you to manage a pool of connections to a database. Using connection pools gives you with the following advantages:

• It improves performance. Creating connections is expensive; a data source creates a connection as soon as it is instantiated.
• It simplifies resource allocation. Resources are only allocated from the data sources, and not at arbitrary places in the code.
• It simplifies connection calls compared to JDBC 1.0.

Data sources work as follows:

1. When a servlet, or other client, wants to use a connection, it looks up a data source by name from a JNDI server.
2. The data source then returns a connection to the client.
3. If the data source has no more connections, it may ask the database manager for more connections (as long as it has not exceeded the maximum number of connections).
4. When the client has finished with the connection, it closes the connection.
5. The data source then returns the connection to the available pool.

To define the data source:

1. In the Server Perspective, stop the server if it is running.
2. In the Server Configuration view, expand the Server Configurations folder, then double-click on WebSphere v5.0 Test Environment .
3. Select the Data Source tab at the bottom of the editor.
4. In the "Data sources" dialog, select Default DB2 JDBC provider .
5. In the "Data source defined=" table, select Add... next to the JDBC provider list.
6. In the "Create a Data Source - Select the type..." dialog, set the value of data source type to: Version 5.0 , then select Next .
7. In the "Modify Data Source - Edit the settings..." dialog, enter the following values:
   • Name: sample
   • JNDI name: jdbc/SAMPLE
   Select Next .
8. In the "Create a Data Source - Edit the resource properties..." dialog, enter the following values:
   • Name (in Resource Properties table), select databaseName
   • Value: SAMPLE
   Select Finish . Your changes should look similar to Figure 37.

To run the application again just select EGLWeb/Web Content => index.jsp => Run on Server=. Enter 30 for Userid, then select Submit. If all is fine, you should see Figure 38.

If you enter a userid that is not in the database, such as 31 , you should see Figure 39.

This program could naturally be extended to display an appropriate error message, which is explained next.

7.2 Extending the application: using application resources properties file

Struts applications can optionally use a properties file for holding text. This allows changes to be applied to error messages, buttons, titles, links or any other text field without having to change any of the Java or JSP code. It also facilitates translating the messages into other languages. The wizard creates the properties file as ApplicationResources.properties (you can change the name and the package in the "Struts Settings" dialog, if desired). By default, the wizard places the file into the Java source package specified, in the WEB-INF/classes subdirectory.

1. Edit and change the file EGLWeb/JavaSource/eglweb/resources/ApplicationResources.properties , as shown in Figure 40.

1. Change the hardcoded text in the JSP files and replace them with the Strut tags <bean:message key=" " /> , and include each specific message. This can be done using the source or using the sequence JSP => Insert Custom= > /Web-INF/struts-bean.tld => message => Insert . The files EGLWeb/Web Content/index.jsp , error.jsp and result.jsp are shown in the following figures, after these changes have been made.

1. Execute the tests again. The results will be the same. The advantage now is that if you wanted to translate the application to, say, Brazilian Portuguese, you only need to change the EGLWeb/Java Source/eglweb/resources/ApplicationResources.properties file. This change is reflected in Figures 44 and 45.

Back to top

Conclusion

Congratulations! Without writing a single line of Java code, you implemented a very simple application that uses servlets, JSPs, and Java, where the server is a Java program that does a simple database inquiry. This very simple application could be easily extended to become a very sophisticated and complex one, though the process to code, test and debug it would be similar.

When coding in EGL, the developer doesn't need to deal with all the plumbing, since all the connectors are generated to use the necessary Java classes that are available at generation time. EGL provides an easy way to move programmers into the J2EE world without requiring all of the skills that are typically necessary for such complex implementations.

Part 2 of this tutorial will show the implementation of this application using a COBOL server program. Stay tuned!

Back to top

Acknowledgements

This article was based on material developed by John Casey from the WW Technical Sales Support group for WebSphere Studio Enterprise Developer. The author wishes to thanks Kevin O'Mahony from IBM Canada and Denise Gabardo from IBM Brazil who reviewed and contributed to this article with comments.

Back to top

Download

Name	Size	Download method
EGLEAR.ear	0.1 MB	FTP|HTTP

	Information about download methods

Resources

• Redbook: Legacy Modernization with WebSphere Studio Enterprise Developer , Ueli Wahli ,Masaaki Agatsuma Reginaldo Barosa, Gert Hekkenberg Bob McGoogan and Iwan Winoto
  
  
• White paper: Struts in WebSphere Portal 4.1 , Jim Bonanno, Chris Seekamp and Michelle Wallace
  
  
• Redpiece: EJB 2.0 Development with WebSphere Studio Application Developer , Ueli Wahli, Wouter Denayer, Lars Schunk, Deborah Shaddon and Martin Weiss
  
  
• Redbook: Java Connectors for CICS , Phil Wakelin, Martin Keen, Richard Johnson and Daniel Cerecedo Diaz
  
  
• Redbook: CICS Transaction Gateway V5 - The WebSphere Connector for CICS , Phil Wakelin, John Joro, Kevin Kinney and David Seager
  
  
• Deploying and Testing VisualAge Generator Web Transactions with WebSphere Application Server and WebSphere Studio Application Developer , Reginaldo Barosa
  
  
• Generating Java using EGL and JSF with WebSphere Studio Site Developer V5.1.2 , Reginaldo Barosa
  

About the author

		Reginaldo Barosa is an IBM Certified Application Development Specialist. He provides sales support, helping customers with WebSphere application development tools such as VisualAge Generator and WebSphere Studio. Before joining IBM US two years ago, Reginaldo worked for 27 years in IBM Brazil. He has co-authored IBM Redbooks and has written two books, as well as other articles for WebSphere Developer Domain (WSDD). He holds a degree in Electrotechnic Engineering from Instituto Mau de Technologia, Sro Paulo, Brazil. You may contact Reginaldo at rbarosa@us.ibm.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top