How to develop, deploy, and run a Client Services Web project in IBM Lotus Expeditor

by John JY Hsu and Sam CL Lo

Architecture and framework of Client Services Web project
Client Services Web projects are Web applications targeting the OSGi-based Lotus Expeditor platform. An application targeting this platform is also called a Bundle, and thus a Web application on this platform is called a "Web Application Bundle," or WAB.

A WAB can be developed by use of Web development tools such as the Eclipse Web Tools platform and the IBM Rational Software Delivery platform. Before using these IDEs to develop the WAB, however, we must first install the Lotus Expeditor toolkit to enable the Client Services Web project creation wizard. For more information on Web development tools, refer to the Lotus Expeditor Application Developer's Guide.

In this article, we not only explain the main differences between the standard Web applications, but also guide you through the steps to develop a WAB targeting the workbench of Lotus Expeditor platform.

Here we briefly introduce each component in the framework of a Client Services Web project (see figure 1).

Figure 1. WAB structure


Manifest file
This file is located under META-INF/MANIFEST.MF and contains bundle information, including package and bundle dependencies.

plugin.xml
Contains extension point contributions, such as lazily start the Web application extension and the workbench targeting extension.

wab.properties
A Client Services Web application contains additional deployment information in wab.properties, which is located in the web content WEB - INF folder. The content of wab.properties is shown as follows (the file is generated after compiling):

webapp.content.location=WebContent
webapp.context=/Hello

web.xml
The format of web.xml is same as that of a standard Web application.

generated_web.xml
This file is an  auxiliary file of web.xml. The WAB checks both the content of web.xml and generated_web.xml while running. Here is a sample content of generated_web.xml (generated after compiling):


_ibmjsp._index
_ibmjsp._index


_ibmjsp._index
/index.jsp


translated-jsps.jar
The generated class file from JSP is stored in this file. Before exporting as a JAR file, be sure to include it in the binary build, which can be configured in the build.properties.

translated-jsps.txt
This is the log file of translating the JSP file into the corresponding class file.

As you can see in the figure, one index.jsp file is created directly under WebContent, which is considered the root directory of the WAB. After compiling, index.jsp's are translated into their respective servlet classes (_ibmjsp/_index.class) before the Web application is deployed to the runtime as a WAB, which is stored in the traslated-jsps.jar.  As for a pure serlvet, you can also create your own servlet directly under the src folder

Note that there are differences between the supported versions of Servlet and JSP in Lotus Expeditor Client for Desktop and Device. Lotus Expeditor Client for Desktop supports Web applications using up to Servlet 2.5 and JSP 2.1 features. Lotus Expeditor Client for Device only supports Web applications using up to Servlet 2.4 and JSP 2.0 features. Note that the Web Tools do not restrict an application developer from using features that may not be supported on devices.

How a Client Services Web project differs from a standard Web project
You can develop Web applications using either a Client Services Web project or a Dynamic Web project. The choice of which to use depends on the application content and its primary use. In general, Web applications that primarily target the Lotus Expeditor platform, or depend on other OSGi services besides core servlet and JSP support, should be developed using a Client Services Web project.

A Client Services Web project is an extension of the dynamic Web project, and hence both use the dynamic Web project tools. In addition, a Client Services Web project provides support for developing a Web application targeting the Lotus Expeditor platform. Below are the main differences between a Client Services Web application and Standard Web project:

- Client Services Web application must also be a valid OSGi bundle. The OSGi manifest file required by Lotus Expeditor applications can be automatically managed by the tools.

- The project’s class path is maintained to match the class path environment that will exist in the Lotus Expeditor runtime. This is useful for detecting class visibility problems at development time rather than runtime.

- Client Services Web application has plugin.xml, which can facilitate the extension point framework to easily enrich and develop the application

- The Lotus Expeditor platform does not support deploying Enterprise Applications through an EAR.

- It is also possible to transform an existing Web Application Archive (WAR) file into a WAB suitable for running on the Lotus Expeditor platform through the use of the WAB Utility.

- When testing the WAB project, and targeting the Client Service runtime, the Client Service launch configuration will be used in the Eclipse Run / Debug launch feature.

- When exporting the Web application, you use the “Plug-in Development > Deployable plug-ins and fragments” wizard to export as JAR file format.

Developing a Client Services Web application

Create a Client Services Web Project:

1. Select File > New > Project, and then click Client Services > Client Services Web Project (see figure 2). Click Next.

Figure 2. Create a Client Services Web Project


2. Enter TestWebApp in the Project Name field. Click Next twice.

3. On this screen, you are able to change the Context Root (see figure 3), which changes the URL of the Web App after deployment. Here we will just leave the default and click Next.

Figure 3. Configure Web Module


4. The Target Definition screen (see figure 4) lets you select the features that determine what will be in the Automated Management of Dependencies in MANIFEST.MF editor. Lotus Expeditor Toolkit defines some built-in targets. Here we select the Default Target and click Finish.

Figure 4. Select Target definition and features


Create sample JSP and adjust settings:

1. Right-click the WebContent folder under SampleWebApp project and select New > Other.
2. Select Web > Web Page; click Next (see figure 5).
3. Select Basic Templates > JSP, and enter “Hello” in the File Name field; click Finish.

Figure 5. New Web Page


4. You should now have a Hello.jsp created under WebContent folder with basic HTML content in it. Since we are showing how to develop Web Applications in Lotus Expeditor Toolkit, we just write a very simple hello jsp and focus on Lotus Expeditor-related material (see figure 6).

Figure 6. Hello.jsp


5. Open the MANIFEST.MF under the META-INF folder and switch to the Dependencies tab. We need to import servlet and jsp libraries because the JRE that Lotus Expeditor uses does not have them. To do this, click the Add button in the Required Plug-ins area and select com.ibm.pvc.servlet and com.ibm.pvc.servlet.jsp (see figure 7).

Figure 7. Select a Plug-in


Deploying and running Web applications in Lotus Expeditor runtime

1.  Select Run >Run…
2.  Select Client Services, then click the “New launch configuration” button (see figure 8).

Figure 8. Create a configuration to launch a Client Services


3. On the Arguments tab, change  –Dcom.ibm.pvc.webcontainer.port=0 in the VM arguments area to –Dcom.ibm.pvc.webcontainer.port=8777 (see figure 9).

Figure 9. VM arguments


4. On the Plug-ins tab (see figure 10), select the “Choose plug-ins and fragments to launch from the list” radio button. Then select only SamplelWebApp from Workspace Plug-ins and all the plug-ins from Target Platform; click Run.

Figure 10. Choosing plug-ins and fragments


5. The Lotus Expeditor runtime that is built into the toolkit for development use should now launch. After the launch is complete, enter ss in the j9 console (see figure 11) and file the bundle id of SampleWebApp.

Figure 11. Expeditor runtime


6. Type “start id” from the console. The id is the bundle id of SampleWebApp; in this case, type “start 1126”.

7. After the bundle is started, open the browser and enter this URL:  http://localhost:8777/SampleWebApp/Hello.jsp. The Web page displays in the browser (see figure 12). Note that the port 8777 here is set in the run configuration with the VM argument  –Dcom.ibm.pvc.webcontainer.port=8777. If you want to change the port, just change this argument before you launch the runtime, or set it to zero to dynamically assign it at runtime.

Figure 12. Web page displayed in browser


8. Another way to launch the Web application is through Lotus Expeditor workbench. To do this, we must extend the com.ibm.eswe.workbench.WctWebApplication extension point in the plugin.xml of our SampleWebApp project:  Shut down the runtime, open the plugin.xml file, switch to the Extensions tab, and click Add.

9. Uncheck the “Show only extension points from required plug-ins”option at the bottom of the screen (see figure 13), and select com.ibm.eswe.workbench.WctWebApplication.

Figure 13. New Extension


10. Enter values shown in figure 14 in the Extensions tab.

Figure 14. Extensions tab values




11. Select Run-> Run, and launch the Lotus Expeditor runtime again. Enter the keystore password of your system JVM to enter the runtime (see figure 15).

Figure 15. Lotus Expeditor runtime


12. Click Open on the top left corner of the screen and select Hello (see figure 16).

Figure 16. Select Hello


13. The Lotus Expeditor launches its internal browser and connects to the URL we defined in the extension com.ibm.eswe.workbench.WctWebApplication, in the attribute “url” of element “WebApplicationUrl” in Step 10 above. You can also change the Hello text seen in figure 17 by changing the DisplayName attribute in Step 10.

Figure 17. Hello text


Convert the standard J2EE Web project into Client Services Web Project
Finally, we point out that there are two ways you can transfer the existing standard J2EE project into a Client Services Web project:

Method 1: Right-click the  PDE Tools project and select Convert Projects to Plug-in Projects (see figure 18). You'll find there is META-INF folder generated with MANIFEST.MF inside it. You can freely add extension points and required bundles to run in the XPD runtime, the same as in the previous section.

Figure 18. Convert Projects to Plug-in Projects via PDE Tools


Method 2:  Right-click the Client Services project and select Convert Project to Client Services Project (see figure 19). This method also adds the META-INF folder with MANIFEST.MF inside it. You can freely add extension points and required bundles to run on the XPD runtime, as in the previous section.

Figure 19. Convert Projects to Plug-in Projects via Client Services


Conclusion
We hope to have explained the main differences between the standard Web applications. We also have guideed you through the steps to develop a WAB targeting the workbench of Lotus Expeditor platform.