Deploying a Sample ODWEK Java Client
Published 03 December 2004
Authors: Wei-Dong Zhu
This document discusses how you can deploy a sample IBM® DB2® Content Manager OnDemand Web Enablement Kit (ODWEK) Java™ client.
In this document, we describe a way to deploy an ODWEK Java client. The Java client in this document was build by Hakan Carlberg in Sweden. The Java client should be used as-is, and it is not supported by the IBM Technical Support Team or the IBM Redbook organization. It is, however, an excellent example of developing an ODWEK Java client using the Java APIs supplied by ODWEK.
The source code is downloadable from the IBM Redbook site and you can modify the code to meet your needs or use it as a starting point to develop your own ODWEK Java client. It is not our intention here to describe how the Java client is build; rather, we concentrate on deployment of the code.
What does the sample Java client do?
The sample Java client allows you to do the following tasks:
- Enables you to log on to any OnDemand server of your choice, by entering the server name (IP-address/Hostname that you can ping),
- Allows you to view TIFF, line data, AFP, and PDF documents through a Web browser,
- Enables simple logging (to STDOUT), so that you can follow the flow of the application.
If you are logging on to a z/OS OnDemand server, and that server is not running with code page 1047, then you need to change the code page on the logon menu screen. Note also, the sample client uses the ODWEK Java APIs 184.108.40.206 and requires a Web application server. It has been tested on WebSphere 5.1.
Before you start
Before you start, we make the following assumptions:
- You have properly installed JRE, HTTP, WebSphere, ODWEK and fixes,
- You are familiar with installing ODWEK for CGI and ODWEK servlet on Windows®,
- A line data report is loaded in OnDemand.
To ensure successful deployment, you need to modify the EAR file and ensure certain prerequisites are met as listed below:
- You need to change the ConfigDir in the EAR file to point to the location where you have your own arswww.ini file.
- If you want to view PDF documents, the foldername must start with "PDF".
- If you want to view AFP documents, you need to install AFP plug-in on your machine. The AFP plug-in is supplied with ODWEK and exists in the plug-ins directory.
- If you want to transform the AFP document to PDF, you will need AFP2WEB, which is a Service Offering from IBM. The transform between AFP to PDF are specified through the arswww.ini file, in the [AFP2PDF] section.
- If you want to view TIFF images (or any other type of images), you need to install the image plug-in supplied with ODWEK.
In this document, we use the following environment for our example:
- Windows 2000 Server
- IBM WebSphere 5.0 aka WAS5
- HTTP Server 1.3.28 or HTTP Server with WAS5
- ODWEK 220.127.116.11
- OnDemand 18.104.22.168
- Microsoft Internet Explorer 6.0
- We use the D:\ drive in this example
- OnDemand is installed on ODServer1
- The OnDemand server is wishart
- The IBM HTTP and WebSphere are installed on congo
Summary steps of the deployment task
The following steps summarize what you need to perform to deploy the sample Java client:
- Download the SampleODWEK code
- Create directories and subdirectories
- Copy files into the new directories
- Modify the Window path and classpath
- Re-assemble the SampleODWEK EAR file (optional)
- Deploy the EAR file
- Edit the arswww.ini files
- Copy logon, Api.htm, and make update
- Test the Java client
Step 1. Download the SampleODWEK code
Disclaim: We use the sample code, SampleODWEK.ear as-is. Remember, it is not supported by the IBM Technical Support team or the IBM Redbook organization.
Down load the SampleODWEK.ear file and store it in a directory. Example: D:\EAR files. When you work with WebSphere Application Assembly Tool in a later step, you will need to locate this file.
Download the sample code from here: ftp://www.redbooks.ibm.com/redbooks/TIPS0462/
Step 2. Create directories
You need to create appropriate directories as outlined by the following steps:
- Create a new directory called D:\MyODWEK, or something similar,
- In the MyODWEK directory, create a subdirectory called JAVA,
- In the MyODWEK\JAVA directory, create a new subdirectories called bin.
You should now have the directory D:\MyODWEK\JAVA\bin or something similar.
Step 3. Copy files
Perform the following tasks:
- Copy the following files from the D:\ODWEK directory to the D:\MyODWEK directory:
- Copy all the INI files from the D:\ODWEK directory to the D:\MyODWEK\JAVA\bin directory:
- Copy the ArsWWWServlet.jar file from the D:\ODWEK\Servlets (or whereever you installed ODWEK) directory to the <WAS_HOME>\Appserver\lib directory. <WAS_HOME> is where we installed WebSphere Application Server. In our example, it is D:\WAS5.
- Copy the ODApi.jar file from D:\ODWEK\api directory to the <WAS_HOME>\Appserver\lib directory.
You directories should look similar to the following figure:
Step 4. Modify the Path and Classpath system variables in Windows
Once you copied the DLL and INI files to the D:\MyODWEK and D:\MyODWEK\JAVA\bin directories, you need to let the Window system know
how to find them. You do this by adding the path to the Windows path environment:
- In Windows 2000, go to the desktop, right-click the My Computer icon and select Properties from the context menu.
- Click the Advanced tab.
- On the advanced tab, click Environment Variables in the middle of the menu. On the Environment Variables screen, there are two windows, one on top is the User variables and the one on the bottom is the System variables.
- Scroll down the System Variables until you see Path. Highlight Path, click edit.
- When the edit window appears, add D:\MyODWEK to the end of the Path variable. Click OK. This enables the system to read the DLLs you have added.
Important: Be sure there is a semicolon “;” between the original Path variable value and your appended value.
- Back on the System Variables window, scroll up or down until you see the Classpath variable. Highlight Classpath, and click edit.
- Add <WAS_HOME>\AppServer\lib to the end of the Classpath variable. Click OK. This gives a path to the ArsWWWServlet.jar and the ODApi.jar files. <WAS_HOME> is the directory where you installed WebSphere Application Server. In our example, it is D:\WAS5.
Important: Be sure there is a semicolon “;” between the original Classpath variable value and your appended value.
- When you finish updating the Path and Classpath system variables, click OK and another OK to save the setting.
Step 5. Reassemble the SampleODWEK
If you place all your files in the same location as is specified in this example, you do not need to edit the SampleODWEK.ear file. If, however, you placed the files in different locations, you must edit the SampleODWEK.ear file with the Application Assembly Tool and re-assemble the file.
To edit and re-assemble the SampleODWEK, perform the following steps:
- Start the AATool in WebSphere
- Select File and click Open
- Navigate to where you download the SampleODWEK.ear file. In our example, it is D:\EAR
- Highlight the SampleODWEK.ear and click Open
- Expand Web Modules and you should see the following figure
Note, the following system settings:
- File name is SampleClient.
- Content root is /ODWEK.
- Classpath is D:\WAS5\AppServer\lib.
These are the context root and Classpath we use in our example. If you are using a different name or location, change these values, and click Apply.
- From the left hand panel, expand SampleJavaClient -> Web Components -> Logon.
- Select Initialization Parameters under Logon. The following figure appears.
Note the following system settings:
– Parameter name is ConfigDir.
– Parameter value is D:\MyODWEK\JAVA\bin.
This is where the arswww.ini file is placed. We use the specified location in this sample. If you moved your arswww.ini to another location, make the appropriate changes and click Apply.
- Expand the AFP2PDF component, and select Initialization Parameters. You should see a screen similar to the following figure:
Note, if your InstallPath for AFP2PDF is different from what is shown, make the appropriate changes and click Apply.
AFP2PDF is a utility offering from IBM Printing Systems for transforming Advanced Function Presentation (AFP) files to Adobe PDF files on the fly. The source files are stored as AFP format in OnDemand. With the help of AFP2PDF, the files will be transformed to PDF for viewing on the Web browsers when users request to view them. It is not necessary for you to have this feature installed. To learn more about transforms, refer to IBM Content Manager OnDemand for Multiplatforms: Web Enablement Kit Implementation Guide Version 7.1, SC27-1000.
- Once all the modifications are made, select File -> Save (or Save As), and save the EAR file to a location where the WebSphere Administration Console can find it later.
- You should get a message from the AAT saying the Archive file was saved successfully. You are done with the assembly process and can exit out of the Application Assembly Tool.
Step 6. Deploy the EAR file
Now that the SampleODWEK.ear file has been updated and reassembled, it is time to deploy the EAR file in WebSphere.
To deploy the EAR file, perform the following steps:
- Select Start -> Programs -> IBM WebSphere Application Server v5.0 -> Administrative Console. This launches the Administration Console.
- Login to the Administration Console.
- From the main menu, select Applications -> Install New Application.
- The Preparing for the application installation window appears. Select Local. Select Browse to find the SampleODWEK.ear file. Select the EAR file, and click Next.
- Accept the defaults on Preparing for the application install window, and click Next.
- Click Next at Step 1: Provide options to perform the installation screen.
- Click Next at Step 2: Install New Application screen.
- Click Next at Step 3: Map modules to application servers.
- Click Finish on Step 4: Summary.
- On the Installing screen, click Save and another Save.
- On the Main menu, expand Environment to find Update Web Server Plug-in.
- Select Update Web Server Plug-in, then click OK and wait until you see the message "The Web server plug-in configuration was updated successfully".
- Start the sample ODWEK application:
a. Go back to the Administration Console's main menu
b. Select Enterprise Applications
c. Locate the application, check the box next to it, go to the top and click Start. You should see the red X change to a green arrow.
You have just deployed the ODWEK java client! Time to see if it works.
- Stop and re-start the Web server:
a. Select Start -> Program -> IBM WebSphere -> Application Server v5.0, and click First Steps.
b. Click Stop to stop the server. When the server is stopped, a message similar to "Server server1 stop completed" should appear on the bottom of the screen.
c. Click Start to restart the server. When the server is started again, a message similar to "Server server1 open for e-business; process id..." should appear on the bottom of the screen.
Tip: Anytime you make changes to the application in WebSphere, you must regenerate the server plug-in!
Once the servlet (SampleODWEK.ear) is deployed, you need to go to the D:\MyODWEK\JAVA\bin directory and edit the arswww.ini file.
Make the appropriate changes to different variables. The following shows the arswww.ini file setting for our example:
Note: wishart is the name of this OnDemand server example. Pay special attention to the bold text. You may have to change according to your system settings.
Step 8. Copy and Edit the logon file
When you deployed the SampleODWEK ear file, WebSphere place the file in a directory structure similar to:
Where InstalledApps is where WebSphere deploys the EAR file, odwek is the name of a WebSphere node, and ODWEKsampleClient.ear is the sample code we just deployed. If you open the SampleClient.war directory, you see the files needed by this client.
To copy and edit the logon file, peform the following steps:
- Find the Api.htm file and copy it to D:\MyODWEK\JAVA directory.
- Edit the Api.htm and make the following changes:
-> Change the FORM statement to point to the /ODWek context root and /ApiLogon in the ODWEKsampleClient code.
-> Change the host name to reflect your OnDemand host (in this example, it is wishart).
- Save the Api.htm file.
The following shows the Api.htm in our example:
<title>OnDemand Internet Connection</title>
<h1 align="center">OnDemand Internet Client(Java-API)</h1>
- Here is the form definition to gather logon information from the
- user and submit it to the Internet client script. An important
- thing to note here is that the ACTION item must include a fully
- qualified domain name.
<FORM METHOD=POST ACTION="/ODWek/ApiLogon">
<H4>Please enter your logon information:</H4>
<b>Server Name:</b> <input type=text name=_server value=wishart>
<b>Port :</b> <input type=text name=_port value=1445>
<b>User:</b> <input type=text name=_user size=10 value=>
<b>Password:</b> <input type=password name=_password value=>
<input type=hidden name=_function value=logon>
<input type=hidden name=_html value=tomtemplate.htm>
<input type=submit value="Submit">
<input type=reset value="Reset">
Step 9. Testing the Java client
Once the Java client is deployed, you can test the client:
- Open a browser and enter the following URL:
- The sample Java client launches. Enter valid OnDemand server name, user ID, password, and click Submit.
- The Folder List screen appears. This means you have successfully deployed the Java client.
If you get an error message, most likely the Api.htm is pointing to the wrong place to find the arswww.ini (Context root).
This material has not been submitted to any formal IBM test and is published AS IS. It has not been the subject of rigorous review. IBM assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a client responsibility and depends upon the client's ability to evaluate and integrate them into the client's operational environment.
Follow IBM Redbooks
Follow IBM Redbooks