Chapter 6: JSP Client for EJB

You need to do the tutorials in this book in the order shown by the Tutorials Map.

Overview

In this chapter, you generate an EJB and JSP client for the interface you mapped in the earlier tutorials. You then deploy the EJB and client to a J2EE application server. You also deploy a J2EE resource adapter.

An EJB running a COBOL service runs in two places: the COBOL service runs under an enterprise server, and the EJB and client run under a third party J2EE application server, such as WebSphere or WebLogic. In the chapter Deploying a Service you deployed the COBOL service. In this chapter, you generate the EJB and its client, deploy them, and then run the JSP client.

In this tutorial, you:

Generate the EJB and its client, which are packaged into an enterprise archive file (.ear) together with some deployment descriptors.
Deploy the .ear file to WebLogic or WebSphere.
Deploy the supplied resource adapter mfcobol-notx.rar to WebLogic or WebSphere. A resource adapter enables the EJB to communicate through its J2EE application server with an enterprise server. Resource adapters are also known as J2EE connectors and they are packaged in resource archive (.rar) files.
Run the JSP client.

When you run the JSP client, it takes a request from the end user and passes it to the EJB you generated. The EJB in turn passes the request to the enterprise server, ESDEMO. The original COBOL program runs on the enterprise server and processes the request, returning the results back to the JSP.

Two enterprise archive files are supplied: JMapServ-WL.ear for WebLogic and JMapServ-WS.ear for WebSphere. Each file contains the generated EJB and client and also the necessary deployment descriptors for WebLogic and WebSphere respectively. You can deploy these .ear files to the relevant application server without generating the EJB and client yourself.

Preparation

You need to install and configure one of the following third-party J2EE application servers: BEA WebLogic and IBM WebSphere. We give instructions specific to WebLogic 8.1 and WebSphere 5.0 Advanced Edition, which use the J2EE 1.3 specification. If you have another supported version of WebLogic or WebSphere there will be minor differences, but it will work in essentially the same way.

You also need a Java Development Kit (JDK) 1.3.x (or higher) installed. We recommend that you use the JDK supplied with your J2EE application server. Make sure that your PATH environment variable points to the bin directory of the correct JDK. You set the PATH using a command such as:

set path=jdk-installation\bin;%path%

If Net Express, the project Mapdemo, and the Service Interfaces window aren't open, open them now - to open the Service Interfaces window, click File > Open Service Interfaces, then select mapdemo.mpr from Examples\Net Express IDE\Mapdemo and click Open.

Make sure the ESDEMO enterprise server is started and the JMapServ service is deployed in it, as described in the chapter Deploying a Service.

Generating the EJB, Client and .ear File

To generate the EJB and its client:

In the Service Interfaces window, right-click the entry for JMapServ.
Click Settings.
On the EJB Generation tab:
1. In the Classpath field, specify the path to your EJB connector classes. For WebSphere, the path is websphere-install-directory\AppServer\lib\j2ee.jar. For WebLogic, the path might be similar to weblogic-install-directory\server\lib\weblogic.jar.
2. In the Application server field, choose the WebLogic or WebSphere version that you are using.
3. Accept the default values for the other fields. Notice that the archive files (.ear .jar and .war) default to the same name as the service, JMapServ. This name is also used as the context root for the client JSP.
4. Click OK.
In the Service Interfaces window, right-click the entry for JMapServ again.
Click Generate Client.

This creates both the EJB and the JSP client and packages them into the file JMapServ.ear. The Output window shows progress on the Java compilation.

EJB and Client Files Created

When you generate the client and the EJB, the files are generated in the directory structure under Examples\Net Express IDE\mapdemo\mapdemo\repos\JMapServ.deploy.

The files are packaged into the following archive files:

JMapServ.jar, which contains the EJB classes and other files
JMapServ.war, which contains the client software, such as the JSP, and the remote, home and bean classes
JMapServ.ear, which contains:
- JMapServ.jar
- JMapServ.war
- Various deployment descriptors and manifest files.
- mfejblib.jar, which contains Micro Focus support for CustomRecord and RuntimeProperties.
This .ear file contains everything to deploy the EJB.

You can view the contents of these archive files using the jar command or a zip utility such as Winzip. For more information see the section Jar, War and Ear Files Generated in the chapter Mapping a Java Interface and Using Resource Adapters in your Java and COBOL book.

WebLogic Deployment

WebLogic comes with a Server Console, which you use to deploy EJB and resource adapters. Instructions on how to use the console are available online from the console. You use the console by navigating the tree in the left-hand pane and clicking an item on the left to display the required page on the right.

Set Up and Start WebLogic Server

Setting up WebLogic involves setting up a domain to hold the EJBs and resource adapters being deployed, and also setting up the environment for WebLogic to run.

Set up and start WebLogic Server as follows:

Set up a domain using the Domain Configuration Wizard:

Click Start > Programs > BEA WebLogic Platform 7.0 > Domain Configuration Wizard.
Click WLS Domain.
Follow the wizard, entering the information shown in the following summary:

Details required	Details that you select or supply
Domain template name	WLS domain
Domain name	MicroFocus
Server type	Single Server (Standalone Server)
Server name	MFserver
Install directory	bea_installation\user_projects
Listen address	You can leave this blank, and it is then populated with localhost
Listen port	7001
SSL listen port	7002
Windows service	yes
Windows start menu	yes
Username	Create a username here
Password	Create a password here

Set up your environment by editing the startup command file, as follows:
1. Open bea_installation\user_projects\MicroFocus\StartWebLogic.cmd in a text editor.
2. Go to the end of the file.
3. Above the line @rem Call WebLogic Server, add the following lines:
```
set MF_HOME=NetExpress\base\bin
set JAVA_HOME=bea-jdk
set classpath=%JAVA_HOME%\lib\tools.jar;
              %MF_HOME%\jar_path\mfconnector.jar;
              %MF_HOME%\mfcobolpure.jar
```
  where:
  - NetExpress is the location of your Net Express installation.
  - bea-jdk is the location of your JDK installation for WebLogic. You must not point this to any other JDK installation. (The set classpath statement is shown broken across two lines for ease of reading.)
  - jar_path is j2ee13/beaweblogic8 or j2ee14/beaweblogic9 depending on the WebLogic version you are using.
4. Save the file.
Start WebLogic Server by clicking Start > Programs > BEA WebLogic Platform 7.0 > User Projects > MicroFocus > Start Server. This runs the StartWebLogic.cmd that you just edited.
Wait for the server to be successfully started.
Start the WebLogic Server Console as follows:
1. Open a browser and enter the URL: http://localhost:7001/console.
2. Enter the username and password that you supplied when configuring your WebLogic domain.

Deploy the Resource Adapter to WebLogic

To deploy the resource adapter, go to the WebLogic Server Console and then:

In the left pane expand MicroFocus > Deployments > Connectors. You can see in the hierarchy on the left that no Micro Focus resource adapters are deployed.
Click Configure a new Connector Component and follow the steps on the page. When you are asked to upload the resource adapter file, upload it from Net Express\Base\bin\mfcobol-notx.rar.
Wait for the resource adapter to finish deploying. Confirm that the resource adapter has been deployed successfully, by examining the Deployment Activity table on the page on the right. The resource adapter should also be listed in the hierarchy on the left.

You do not need to create a connection factory or specify the JNDI name of the resource adapter, because these are already specified in the deployment descriptor for the connection factory. Here are the relevant lines from that deployment descriptor, weblogic-ra.xml:

<connection-factory-name>
    CCIMFCobol_v1.0
</connection-factory-name>
<jndi-name>
    eis/MFCobol_v1.0
</jndi-name>

If you want to view weblogic-ra.xml, find mfcobol-notx.rar in the location given above and extract weblogic-ra.xml from it.

Deploy the EJB and Client to WebLogic

To deploy your EJB:

At the WebLogic Server Console, select MicroFocus > Deployments > Applications.
Click Configure a new Application on the right and follow the steps on the page. You can accept all the defaults with the following exceptions:

When prompted for: Do this:

Path to the .ear file
Specify mapdemo\repos\JMapServ.deploy\JMapServ.ear within your mapdemo directory

Target server Enter MFserver
Click Deploy Application on the page on the right and wait for the application to finish deploying. Confirm that the deployment was successful, by examining the Deployment Activity table. The application should also be listed in the hierarchy on the left.

You do not need to specify the JNDI name of the EJB or map the JNDI name of the resource adapter, because these are already specified in the deployment descriptors. Here are the relevant lines from those deployment descriptors, weblogic-ejb-jar.xml and weblogic.xml :

<resource-description>
    <res-ref-name>CCIMFCobol_v1.0</res-ref-name>
        <jndi-name>eis/MFCobol_v1.0</jndi-name>
</resource-description>
...
<jndi-name>ejb/JMapServEJB</jndi-name>

If you want to view weblogic-ra.xml, find JMapServ.ear in the location given above, extract JMapServ.jar and then extract weblogic-ra.xml from it.

Stop and Restart WebLogic Server

When you have changed the modules deployed on the server, the BEA WebLogic documentation recommends stopping and restarting the server. To do this:

At the WebLogic Server Console, right-click MicroFocus > Servers > MFServer in the left pane. Then click Start/Stop server and follow the instructions to stop the server.
The WebLogic Server Console will not be available until you restart the server.
Restart WebLogic Server, in the same way as you started it before.
Wait until the server has restarted and then click Refresh in the Server Console.

Note: If you reboot your machine, you need to restart the WebLogic server. You must start the WebLogic server from the Start menu. You cannot start it using Services in the Windows Control Panel and you cannot configure it in the Control Panel to start automatically when you reboot the machine.

WebSphere Deployment

WebSphere comes with an Administrative Console, which you use to deploy EJBs and resource adapters. The console takes you step by step through deployment and provides full information online on how to do this. You use the console by navigating the tree in the left-hand pane and clicking an item on the left to display the required page on the right.

Start WebSphere Server and the Administrative Console

Start WebSphere Server and the Administrative Console as follows:

Start WebSphere Server from the Start menu or using a command such as:
```
 websphere_installation\bin\startServer
```
Wait for WebSphere Server to start and then launch the WebSphere Administrative Console, either from the Start menu or by opening a browser and specifying the URL, http://localhost:9090/admin.
Enter a username to identify yourself.

Deploy the Resource Adapter to WebSphere

To deploy the resource adapter, go to the WebSphere Administrative Console and then:

In the left pane expand Resources and click Resource Adapters. Notice, at the bottom of the page on the right, that there are no Micro Focus resource adapters deployed.

Click Install RAR and follow the instructions on the screen. You can accept all the defaults with the following exceptions:

When prompted for:	Do this:
Path to the resource adapter	Specify Net Express\Base\Bin\mfcobol-notx.rar
Name of the resource adapter	Enter any name you want, such as Micro Focus resource adapter

The new resource adapter is now listed on the right. Click it to display its properties.
Add a connection factory for the resource adapter. You might need to scroll to Additional Properties at the end and then click J2C Connection Factories. Then click New and follow the instructions on the screen to specify:
- A name for the connection factory, such as MF adapter connection.
- The JNDI name for Enterprise Server, which is eis/MFCobol_v1.0.
Confirm that the new connection for the resource adapter is now listed on the right.

Deploy the EJB to WebSphere

To deploy your EJB:

At the WebSphere Administrative Console, expand the hierarchy for Applications on the left.

Click Install New Application and follow the instructions on the screen. Accept all the defaults with the following exceptions:

When prompted for:	Do this:
Path to the .ear file	Specify mapdemo\repos\JMapServ.deploy\JMapServ.ear within your mapdemo directory
Application name	Enter any name, such as My MapDemo EJB
Precompile JSPs	Don't check this
Deploy EJBs	Check this
Map modules to application servers	Check both modules

Wait for the deployment to finish and confirm that it was successful by reading the messages on the screen. Save the new configuration as described on the screen.
List the applications now installed, by clicking Enterprise Applications on the left. The JMapServ application should now be shown on the page on the right.
Select the JMapServ application and start it, by clicking Start.

Stop and Restart WebSphere Server

When you have changed the modules deployed on the server, the IBM WebSphere documentation recommends stopping and restarting the server.

To do this, go the WebSphere Administrative Console and then:

Save the configuration by clicking Save in the right-hand pane at the top.
Stop WebSphere Server, either from the Start menu or by typing the following command:
```
 websphere_installation\bin\stopServer
```
Restart the server in the same way as before.
Wait until the server has restarted and then click Refresh in the Administrative Console.

Client Source Code

The client JSP and its servlet are generated in the directory structure under Examples\Net Express IDE\mapdemo\mapdemo\repos\JMapServ.deploy\Client .

The files include:

JMapServMain.jsp. This is the JSP. It passes data back and forth between the end-user and the servlet.
JMapServJspBean.java. This file contains the getter and setter methods that are used to move information back and forth between the servlet and JSP.
JMapServServlet.java. This file is the servlet. It processes the incoming requests from the JSP, invokes an instance of the stateless EJB, and forwards the response back to the JSP.
JMapServSessionMonitor.java. This is a helper class, which stores the EJB instances for the stateful session bean.

To see how the EJB is invoked from the servlet, look at the file JMapServServlet.java, which is in the directory JMapServ.deploy\Client\WEB-INF\com\mypackage\JMapServ. Open the file in your Java development tool or a text editor, and examine the following lines:

InitialContext initCtx = new InitialContext();
Object objRef = initCtx.lookup("java:comp/env/ejb/JMapServEJB");
hi = (com.mypackage.JMapServ.JMapServHome) 
     javax.rmi.PortableRemoteObject.narrow(
     objRef,
     com.mypackage.JMapServ.JMapServHome.class);

These lines look up the EJB in JNDI when the EJB is first needed.

```
ri = hi.create();
JMapServSessionMonitor.setClientRequest(session, ri);
```
These lines create an instance of the EJB and start a session for handling the request.

ri = JMapServSessionMonitor.getClientRequest(session)

This line gets the EJB on subsequent occurrences.

Run the JSP Client

The demonstration application uses a simple book database file . Recall from the chapter Creating a Service that the file as supplied contains records 1111 and 2222, and you might have added a record yourself, number 4444, if you used the example data suggested in that chapter.

To run the JSP:

Start WebLogic Server or WebSphere Server from the Start menu in the same way as before. You do not need to start the WebLogic Server Console or the WebSphere Administrative Console.
When the server has successfully started, open another browser.
For WebLogic, enter the URL http://localhost:7001/JMapServ/JMapServMain.jsp.
For WebSphere, enter the URL http://localhost:9080/JMapServ/JMapServMain.jsp.
Use the client to find a book in the book database, as follows:
1. Click the link for the Read operation.
2. In the read_lnk_b_details_lnk_b_stockno field type 1111 and click Go.
  After a few moments, the client displays the name and content of each field in the requested record. This demonstrates a request being passed by your EJB interface, through the resource adapter, to an enterprise server, and demonstrates the COBOL service, BOOK.Read, handling the request, looking up the record in the file and sending a response back to the JSP.
Go back to the main test client page, by clicking Back. Try a few more operations, such as adding or deleting books.

Before Continuing...

To see how to debug this service, continue at the chapter Debugging a Service.

If you want to take a break first, you can close your development system or just the project.

When prompted for:	Do this:
Path to the .ear file	Specify mapdemo\repos\JMapServ.deploy\JMapServ.ear within your mapdemo directory
Target server	Enter MFserver