How to develop, deploy, and run a Client Services Web project in IBM Lotus
by John JY Hsu and Sam CL
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
This file is located under META-INF/MANIFEST.MF and contains bundle information,
including package and bundle dependencies.
Contains extension point contributions, such as lazily start the Web application
extension and the workbench targeting extension.
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
The format of web.xml is same as that of a standard Web application.
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):
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.
This is the log file of translating the JSP file into the corresponding
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
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
3. Select Basic Templates > JSP, and enter “Hello” in the File Name
field; click Finish.
. 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;
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
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. 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.
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:
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
Projects to Plug-in Projects via PDE Tools
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.
Projects to Plug-in Projects via Client Services
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.