| Download Docs | |
|
| bea.com | products | dev2dev | support | askBEA |
|
|
|
 |
| e-docs > WebLogic Java Adapter for Mainframe > Programming Guide > Basic Programming Techniques |
|
Programming Guide
|
Basic Programming Techniques
This section discusses the following topics:
Choosing an eGen Java Application Model
There are four different types or models of Java applications that can be generated by the eGen utility. These models, which can be classified as either Mainframe to WebLogic Server or WebLogic Server to Mainframe, are described below.
Mainframe to WebLogic Server (request originates on the mainframe and is serviced by WebLogic):
WebLogic Server to Mainframe (request originates on the WebLogic client or server and is serviced by the mainframe):
Choose one of these four model types to use as the basis for your Java application. Once you have chosen a model type, refer to the section from the following list for instructions on writing the script and implementing the model you have chosen:
For all of the applications you generate, you must provide a script file containing definitions for the application, including the COBOL copybook file name and the DataView class names.
Generating the Java Application Code
The Java application code can be generated at the same time that you generate the Java DataView code. To generate Java application code, the eGen script that you process must contain instructions for generating the Java application along with the instructions for generating the DataView code.
Referring to the sample files in samples\verify\gateway\outbound, the following command generates Chardata.java and BaseClient.java. The DataView file is Chardata.java, and the application file is BaseClient.java.
> egencobol baseClient.egen
General Form of an eGen Script
As previously stated, most eGen scripts consist of two major sections:
Writing the Application Section of an eGen Script
The application section of an eGen script contains the information about the Java class files that the eGen utility is to generate for a particular application. The application section is divided into two distinct subsections, which are actually lists. The two lists are:
List of Services
Scripts that are used to define the application components that the eGen utility is to generate usually contain a list of one or more service definitions. If the application components are all server or Mainframe to WebLogic Server EJB's, this list of services is not present. This is because this list of service definitions describes remote services configured in JAM; server EJB's do not call remote services since the requests are flowing outward from the mainframe.
The general form of a service definition is as follows (keywords are in bold):
service servicename accepts inputViewname returns outputViewname
Table 3-1 describes the service definition parameters.
Table 3-1 Service Definition Parameters
Note: The inputViewname and outputViewname do not have to be the same; however, due to the way many applications are written, they often are the same. Following is an example of a service definition: In this example, the service TOUPPER is a configured remote service. As far as the Java application making the request for a mainframe service through WebLogic JAM is concerned, this service accepts as input a Chardata DataView. The actual mainframe server application accepts as input the COBOL copybook which corresponds to a Chardata DataView. As far as the Java application is concerned, the output or response from the mainframe service is a Chardata DataView. List of Application Components In order for the eGen utility to generate code for Java applications, the eGen script must contain a list of one or more definitions of the application components that are to be generated. This list of definitions of application components can contain definitions of stand-alone clients, client or server EJB's, and servlets. This list of definitions also contains the definition of any HTML pages that are used by servlets defined in the list. Note: The definition of an HTML page appearing in this list by itself will not cause any code to be generated. The general form of an application component definition is as follows: Table 3-2 describes the application component definition parameters. Table 3-2 Application Component Definition Parameters
service TOUPPER accepts Chardata returns Chardata
model identifier [model-dependent-parameters]
{ details }
Following is an example of an application component definition: The example states the following:
client ejb sample.SampleClient my.sampleBean
{
method newEmployee
is service sampleCreate
}
Specific details about the application component definitions for each application model, as well as the files that the eGen utility generates for each model, are discussed in the following sections.
Mainframe to WebLogic Server Application Models
In a Mainframe to WebLogic Server application, a request originates on a mainframe and is serviced by an EJB invoked by a WebLogic JAM Gateway.
Generating a Server Enterprise Java Bean-Based Application
This type of application produces Java classes that comprise an EJB application acting as a remote server from the viewpoint of the mainframe. The classes process service requests originating from the mainframe (remote) system and transfer data records to and from the mainframe. From the viewpoint of the Java classes, they receive EJB method requests. From the viewpoint of the mainframe application, it invokes remote CICS or IMS programs.
Components of an eGen Server EJB Script
The general form of a definition of a server (Mainframe to WebLogic Server) EJB that appears in an eGen script is as follows (keywords are in bold):
server ejb classname ejbregistration transaction
transaction-attribute
{servermethod}
Table 3-3 describes the server EJB definition keywords and parameters.
Table 3-3 Service EJB Definition Keywords and Parameters
Table 3-4 Parameters for the servermethod
Following is an example of a server (Mainframe to WebLogic Server) EJB definition that appears in an eGen script: The example states the following:
server ejb sample.SampleServer my.sampleServer
{
method newEmployee (EmployeeRecord)
returns EmployeeRecord
}
Generated Files
Table 3-5 lists the files generated from the example server (Mainframe to WebLogic Server) EJB described in Components of an eGen Server EJB Script. These files are described in the sections following the table.
SampleServer.java Source File Listing 3-1 shows the partial contents of the generated remote interface SampleServer.java source file. Listing 3-1 Sample SampleServer.java Contents
SampleServerBean.java Source File Listing 3-2 shows the partial contents of the generated EJB implementation SampleServerBean.java source file. Listing 3-2 Sample SampleServerBean.java Contents
SampleServerHome.java Source File The eGen utility generates a standard home interface class for the server EJB. SampleServer-jar.xml Source File The following line from the deployment descriptor file results from the transaction attribute in the definition in the eGen script. As described in Components of an eGen Server EJB Script, this element indicates the level of transaction demarcation. If the transaction-attribute is not present in the definition, the default value is Supports. So, in this example, the transaction attribute was not listed in the script definition. wl-SampleServer-jar.xml Source File The following line from the WebLogic deployment information file results from the home interface name in the eGen script. As described in Components of an eGen Server EJB Script, my.sampleServer is the home interface identifier for this bean in the WebLogic deployment description. Customizing a Server Enterprise Java Bean-Based Application The generated server enterprise Java bean-based applications are only intended for customizing, since they perform no real work without customization. This section describes the way generated server EJB code can be customized. The following figure illustrates the relationships and inheritance hierarchy between the WebLogic JAM classes comprising the application. Figure 3-1 The WebLogic JAM Server EJB Class Hierarchy
<trans-attribute>Supports</trans-attribute>
<jndi-name>my.sampleServer</jndi-name>
The generated Java code for a server EJB application is a class that inherits the class EgenServerBean. The EgenServerBean class is provided in the WebLogic JAM distribution jar file. This base class provides the basic framework for an EJB. It provides the required methods for a Stateless Session EJB. The following listing shows an example ExtSampleServerBean class that extends the generated SampleServerBean class, providing an implementation of the newEmployee() method. The example method prints a message indicating that a newEmployee request has been received. Listing 3-3 Sample ExtSampleServerBean.java Contents Once it has been written, the ExtSampleServerBean class and the other EJB Java source files must be compiled and deployed in the same manner as other EJBs. Before deploying, the deployment descriptor must be modified; the ejb-class must be set to the name of your extended EJB implementation class (see Deploying a WebLogic JAM eGen EJB). Compiling and Deploying Refer to the WebLogic Server documentation for more information. The sample file provided with WebLogic Server contains a build script for reference.
package sample;
public class ExtSampleServerBean extends SampleServerBean
{
public EmployeeRecord newEmployee (EmployeeRecord in)
{
System.out.println("New Employee: " +
+in.getEmpRecord().getEmpName().getEmpNameFirst()
+ " "
+ in.getEmpRecord().getEmpname().getEmpNameLast());
return in;
}
}
WebLogic Server to Mainframe Application Models
In a WebLogic Server to Mainframe application, a request originates on a WebLogic client or server, and is serviced by a mainframe program invoked by the WebLogic JAM Gateway in cooperation with the CRM.
Generating a Stand-Alone Client Application
This type of application produces simple Java classes that perform the appropriate conversions of data records sent between Java and the mainframe and call mainframe services, but without all of the EJB support methods. These classes are intended to be lower-level components upon which more complicated applications are built.
Components of an eGen Stand-Alone Application Script The general form of a definition of a stand-alone client class that appears in an eGen script is as follows (keywords are in bold): Table 3-6 describes the stand-alone client class definition keywords and parameters. Table 3-6 Stand-Alone Client Class Definition Keywords and Parameters
client class classname
{ clientmethods }
Table 3-7 Parameters for the clientmethod
Following is an example of a stand-alone client class definition that appears in an eGen script: The example states the following:
client class sample.SampleClass
{
method newEmployee
is service sampleCreate
}
Generated Files
The file SampleClass.java, containing the source for the sample class, is generated.
Listing 3-4 shows the partial contents of the SampleClass.java source file.
Listing 3-4 Sample SampleClass.java Source File
Customizing a Stand-Alone Java Application The following figure illustrates the relationships and inheritance hierarchy between the WebLogic JAM classes comprising the stand-alone java application. Figure 3-2 The WebLogic JAM Client Class Hierarchy
The generated Java code for a client class application is a class that inherits class EgenClient. The EgenClient class is provided in the WebLogic JAM distribution jam.jar file. This base class provides the basic framework for a client to the WebLogic JAM Gateway, as well as the required methods for accessing the gateway. Your class, which extends or uses the SampleClient class, simply overrides or calls these methods to provide additional business logic, modifying the contents of the DataView. Your class may also add additional methods. The following listing shows an example ExtSampleClass class that extends the generated SampleClient class. Listing 3-5 Sample ExtSampleClient.java Contents Once it has been written, the ExtSampleClient class and the other Java source files must be compiled and placed in your CLASSPATH. Instead of extending the generated client, you can also write classes that have the generated client as a member. This is an especially useful alternative if the class you write must extend some other class. Generating a Client Enterprise Java Bean-Based Application This type of application produces Java classes that comprise an EJB application. The class methods are invoked from requests originating from other EJB classes or other WebLogic Server client classes and transfer data records to and from the mainframe (remote system). From the viewpoint of the mainframe, the Java classes act as a remote CICS or IMS client. From the viewpoint of the WebLogic Server client classes, they act as regular EJB classes. Components of an eGen Client EJB Script In order to produce an EJB-based application, the script file that defines your DataViews must be edited to describe both the mainframe services accessed and the EJB that will access them. The general form of a definition of a client (WebLogic Server to Mainframe) EJB that appears in an eGen script is as follows (keywords are in bold): Table 3-8 describes the client EJB script keywords and parameters. Table 3-8 Client EJB Script Keywords and Parameters
package sample;
public class ExtSampleClient extends SampleClass
{
// createEmployee
//
public EmployeeRecord newEmployee(EmployeeRecord
commarea)
throws IOException, snaException
{
if (!isSsnValid(commarea.getEmpRecord().getEmpSsn()))
{
// The SSN is not valid
throw new Error("Invalid Social Security Number:"+
commarea.getEmpRecord().getEmpSsn());
}
return super.newEmployee(commarea);
}
.
.
.
// Private functions /*******************************************************
* Validates an SSN field.
*/ private boolean isSsnValid(BigDecimal ssn)
{
if (ssn.longValue() < 100000000)
{
// Oops, appears to be less than 9 digits.
return false;
}
return (true);
}
}client ejb classname ejbregistration transaction
transaction-attribute
{clientmethods}
Table 3-9 Client Method Definition Parameters
Following is an example of a client (WebLogic Server to Mainframe) EJB definition that appears in an eGen script: The example states the following:
client ejb sample.SampleClient my.sampleBean
{
method newEmployee
is service sampleCreate
}
Generated Files
Table 3-10 lists the files generated from the client (WebLogic Server to Mainframe) EJB described in Components of an eGen Client EJB Script. These files are described in the sections following the table.
. SampleClient.java Source File Listing 3-6 shows the partial contents of the generated remote interface SampleClient.java source file. Following the listing are descriptions of the elements in this file. Listing 3-6 Sample SampleClient.java Contents
SampleClientBean.java Source File Listing 3-7 shows the partial contents of the generated EJB implementation SampleClientBean.java source file. Following the listing are descriptions of the elements in this file. Listing 3-7 Sample SampleClientBean.java Contents
SampleClientHome.java Source File The eGen utility generates a standard home interface class for the client EJB. SampleClient-jar.xml Source File The following line from the deployment descriptor file results from the transaction demarcation listed in the definition in the eGen script. As described in Components of an eGen Client EJB Script, this element indicates the level of transaction demarcation. If the transaction-attribute is not present in the definition, the default value is Supports. In this example, the transaction-attribute was not listed in the script definition. wl-SampleServer-jar.xml Source File The following line from the WebLogic deployment information file results from the Home Interface name in the eGen script. As described in Components of an eGen Client EJB Script, my.sampleBean is the home interface identifier for this bean in the WebLogic deployment description. Note: You can edit the deployment descriptor to change the pool size, etc. Customizing an Enterprise Java Bean-Based Application The generated client enterprise Java bean-based applications are generally intended for customizing. Without customization, the only function they perform is communication with the mainframe. This section describes the way generated client EJB code can be customized. The following figure illustrates the relationships and inheritance hierarchy between the WebLogic JAM classes comprising the application. Figure 3-3 The WebLogic JAM Client EJB Class Hierarchy
<trans-attribute>Supports</trans-attribute>
<jndi-name>my.sampleBean</jndi-name>
The generated Java code for a client EJB application is a class that inherits class egenClientBean. The egenClientBean class is provided in the WebLogic JAM distribution jar file. Listing 3-8 illustrates an example ExtSampleClientBean class that extends the generated SampleClientBean class, adding a validation function (isSsnValid()) for the emp-ssn (m_empSsn) field of the DataView EmployeeRecord class. If the emp-ssn field is determined to be invalid, an exception occurs. Otherwise, the original function is called to perform the mainframe operation. Listing 3-8 Example ExtSampleClientBean.java Class When it has been written, the ExtSampleClientBean class and the other EJB Java source files must be compiled and deployed in the same manner as other EJBs. Prior to deploying, the deployment descriptor must be modified; the ejb-class property must be set to the name of your extended EJB implementation class (see Deploying a WebLogic JAM eGen EJB). Compiling and Deploying Refer to the BEA WebLogic Server documentation for more information. The sample file provided with WebLogic Server contains a build script for reference. Generating a Servlet Application A WebLogic JAM servlet application is a Java servlet that executes within BEA WebLogic Server. The application is started from a web browser when the user enters a URL that is configured to invoke the servlet. The servlet presents an HTML form containing data fields and buttons. The buttons can be configured to invoke:
package Sample;
// Imports
import java.math.BigDecimal;
import java.io.IOException;import com.bea.sna.jcrmgw.snaException;
// Local imports
import sample.EmployeeRecord;
import sample.SampleClientBean;/***************************************************************
* Extends the SampleCientBean EJB class, adding additional business logic.
*/public class ExtSampleClientBean
extends SampleClientBean
{
//Public functions...
/****************************************************************
* Create a new employee record.
*/ public EmployeeRecord newEmployee (EmployeeRecord commarea)
throws IOException, snaException
{
if (!isSsnValid (commarea.getEmpRecord().getEmpSsn()))
{
// The SSN is not valid.
throw new Error ("Invalid Social Security Number:"
+ commarea.getEmpRecord().getEmpSsn()); }
//
// Make the remote call.
return super.newEmployee(commarea);
}
}// Private Functions
/**************************************************************
* Validate an SSN field
*
* @return
* True if the SSN is valid, otherwise false.
*/private boolean isSsnValid(final BigDecimal ssn)
{
if (ssn.longValue() < 100000000)
{
// Oops, appears to be less than 9 digits
return false;
}
return true;
}
}
In general, servlets generated by the eGen utility are intended for testing purposes and are not easily customized to provide a more aesthetically pleasing interface.
In order to produce a servlet application, create an eGen script file and use the eGen utility to generate your typed data record (DataView), and Servlet code.
In order to define a servlet application using an eGen script, you must define the following:
Components of an eGen HTML Page Definition
The general form of an HTML page that appears in an eGen script is as follows (keywords are in bold):
page pagename title
{ view viewname
buttons {buttonlist}
}
Table 3-11 describes the HTML page definition keywords and parameters.
Table 3-11 HTML Page Definition Keywords and Parameters
The general syntax for a remote service button in an eGen script is as follows (keywords are in bold): Table 3-12 describes the remote service button definition keywords and parameters. Table 3-12 Remote Service Button Definition Keywords and Parameters
buttonname service (servicename) shows pagename
The general syntax for an EJB button in an eGen script is as follows (keywords are in bold): Note: Empty parenthesis must follow ejbmethod. Table 3-13 describes the EJB button definition keywords and parameters. Table 3-13 EJB Button Definition Keywords and Parameters
buttonname ejbmethod () shows pagename
Following is an example of an HTML page that appears in an eGen script: This listing defines an HTML page named initial, with a text title of Initial Page, that displays an EmployeeRecord record object as an HTML form. It also specifies that the form has a button labeled Create. When the button is pressed, the service sampleCreate is invoked and is passed the contents of the browser page as an EmployeeRecord object (the fields of which may have been modified by the user). Afterwards, the fullPage page is used to display the results. Components of an eGen Servlet Definition The general form of a servlet definition that appears in an eGen script is as follows (keywords are in bold): Table 3-14 describes the servlet definition keywords and parameters. Table 3-14 Servlet Definition Keywords and Parameters
page initial "Initial Page"
{
view EmployeeRecord
buttons
{
"Create"
service ("sampleCreate")
shows fullPage
}
}servlet classname shows pagename
Following is an example of a servlet definition that appears in an eGen script: The example states the following:
servlet sample.SampleServlet shows initial
Generated Files
The eGen servlet definition described in Components of an eGen Servlet Definition generates a servlet source code file called SampleServlet.java.
Customizing a Servlet WebLogic JAM Application
The generated Java classes produced for servlet applications are intended for proof of concept and prototypes. They can be customized in limited ways. It is presumed that some other development tool will be used to develop a servlet or other user interface on top of the generated EJBs or client classes.
Supplying Security Credentials
WebLogic JAM has the capability to accept user ID and password information from a Java client program, and apply that information to access a secure service on the mainframe.
Note: When security information is transmitted via the connection between the WebLogic JAM Gateway and the CRM, it is sent in clear text (not encrypted). You should not send this information over a network that can be read by unauthorized parties.
Security Levels
There are three levels of security that are supported by WebLogic JAM.
Notes: Refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide for information on setting the security level for a CRM link and using a default user ID.
Refer to your mainframe security documentation for more specific information about establishing and administrating mainframe security.
Supplying Security Credentials in a WebLogic JAM Client Program
User security information can be supplied in a WebLogic JAM stand-alone client or client EJB. There are two methods in the EgenClient object that support this operation:
This method sets the user ID to the value specified in the String argument.
This method sets the user password to the value specified in the String argument.
These methods can be called on any sub-class of EgenClient, such as the client classes generated by the eGen utility. The methods are not inserted automatically by the eGen utility; they must be manually added to the client program source, and should be called prior to the any calls to EgenClient.callService().
The methods setUserID and setPassword can be called on any subclass of EgenClientBean, such as the client EJBs generated by the eGen utility. EgenClientBean has methods by the same name that act as wrappers for calls to methods of the EgenClient member of the EgenClientBean class.
Calls to the EgenClient.setUserId() method within a WebLogic JAM client will override any default user ID value configured for the CRM link the client is using.
These methods cannot be used with the servlet-only applications, since they do not use the EgenClient object directly. Servlet-only applications can make use of the default user ID to support security level Identify.
Listing 3-9 illustrates a class that extends the generated EJB implementation to provide security credentials to the Gateway during these operations.
Listing 3-9 Example of Class with Security Credentials
// ExtSampleClientBean.java
//
package sample;
// Imports
//
import java.io.IOException;
import com.bea.sna.jcrmgw.snaException;
/**
* EJB implementation.
*/
public class ExtSampleClientBean extends SampleClientBean
{
protected byte[] callService(String svc, byte[] input)
throws snaException, IOException
{
setUserid("JAMUSER");
setPassword("JAMPASS");
return super.callService(svc, input);
}
}
// END ExtSampleClientBean.java
Note: WebLogic JAM will return an SNANotAuthorized exception if the credentials are rejected by the mainframe security package.
WebLogic JAM to JMS
WebLogic JAM includes an EJB that has two major functions:
WebLogic JAM to JMS is a utility stateless session EJB that uses a DataView generated by the eGen utility to convert the data. The EJB is contained in the jam.ear file with a default JNDI name of JAMToJMS.
The general process for this insertion and conversion is described in the following sections.
Make sure that your eGen script is written to generate DataViews that support XML, as shown in the following code example:
generate view empRecData from emprec support xml
For more information on DataViews, refer to Writing the DataView Section of an eGen Script. For more information on generating the DataView source files, see Processing eGen Scripts with the eGen Utility. These files can be compiled for deployment. The schema and DTD can be made available to the XML application as necessary.
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
