Using IBM Lotus Expeditor Toolkit V6.1.2 for eRCP application development on devices

This article provides a step-by-step tour of IBM® Lotus® Expeditor client and toolkit. Learn how to install the Lotus Expeditor client and toolkit, how to create a client services project and to import a sample into the tools, and how to remotely launch the application onto devices.

Share:

Charles Lu (charleslu@tw.ibm.com), Software Engineer, IBM

Charles Lu is a software developer at the IBM China Software Development Lab and currently works on IBM Lotus Expeditor development. He is interested in device programming, instant messaging, and voice technology.



Sam Lo (locl@tw.ibm.com), Software Engineer, IBM

Sam Lo is a software developer at the IBM China Software Development Lab and works in Lotus client technology. He loves to travel and play musical instruments and sports.



20 May 2008

IBM Lotus Expeditor Toolkit provides a complete, integrated set of tools that allow you to develop, debug, package, and deploy client applications to the IBM Lotus Expeditor client environment. You can use the toolkit to develop the following types of applications on devices:

  • Client services applications
  • Client services Web applications
  • Client services Web service applications
  • Client services embedded transaction applications

This article covers the following topics:

  • What software is required? What devices are supported?
  • How do you configure both the device and the desktop?
  • How do you remotely launch or debug the device and the emulator?

Prerequisites

Lotus Expeditor Toolkit for device requires Eclipse 3.2.2, and it cannot work with Eclipse 3.3. For Web application development, including the samples used in this article, you should also install the Eclipse Web Tools Platform. This platform can be installed from the predefined Callisto Discovery site available in Eclipse. If you do not already have a version of Eclipse and Eclipse Web Tools Platform, you can download Eclipse Web Tools Platform all in one SDK as shown in the Resources section. If you need to create an Embedded Transaction Project, use IBM Rational® Application Developer or IBM Rational Software Architect. If you are not already a Rational Application Developer customer, you can download and install the trial version of the software. Prior to installing Lotus Expeditor Toolkit in Rational Application Developer or Rational Software Architect, be sure to update to the latest fix pack of the Rational software. See tables 1 and 2 for required software and supported device platforms.

Table 1. Required software
Application type or required functionMinimum prerequisite software for Lotus Expeditor Toolkit
Standard Javaâ„¢ and Eclipse rich client platform (RCP) and embedded rich client platform (eRCP)Eclipse 3.2.2
Web application, JSPEclipse 3.2.2 and Eclipse Web Tools Platform 1.5.4
Web service, embedded transaction project and sample galleryRational Application Developer V7.0.0.4, Rational Software Architect V7.0.0.4
or IBM WebSphere® Application Server Toolkit 6.1.1.4 with Eclipse updater iFix
Table 2. Supported device platforms
PlatformModel
Microsoft® Windows® MobilePocket PC 2003 Second Edition, Microsoft Windows Mobile 5.0, Microsoft Windows Mobile 6.0
Microsoft Windows CEMicrosoft Windows Embedded CE 5.0
NokiaSeries 60

Lotus Expeditor client for device installation

To install the device runtime on the Microsoft Windows Mobile device, you must have Lotus Expeditor Client 6.1.2. Install the device runtime from the corresponding device directory. For example, to install the Lotus Expeditor Client on the Microsoft Windows Mobile device, you have to run XPD-wm-setup.exe from the <Expeditor_Client_CD>\device\install\wm\ directory. After installation, a new program group named Lotus Expeditor is created, which includes two applications, Application Manager and Support Assistant. This pacakge contains the Lotus Expeditor core runtime. If you want to test for Web application, Web service, DB2e, EJB, and so on, install the optional update site using the Application Manager; you can find it at <Expeditor_Client_CD>\device\updates\.

Figure 1. Lotus Expeditor program group on Microsoft Windows mobile device
Lotus Expeditor program group on Microsoft Windows mobile device

To provide the capability of device debugging on the Microsoft Windows Mobile device, replace J9 with the debug build. This file contains the debug required information. In addition, the J9 console is provided so that you can see any log or expectations from it. For instance, if you are using the Microsoft Windows Mobile 6.0 device, you can find the file j9dbg_wm.exe at <Expeditor_Client_CD>\utils\jclDevice\wm directory, rename it j9.exe, and replace the original file at <device_eclipse_root>\plugins\com.ibm.pvc.wece.device.win32.arm_6.1.2.0-<date>\jre\bin on the device.

For the Nokia device, purchase and install the debug build of Nokia eRCP and Instrument Agent. After you install them, two new programs are created within the insallations group, eRCP AppMgr and IAgent Config. The IAgent Config is the connection tool used by the Lotus Expeditor toolkit. Now both Nokia eRCP and the Lotus Expeditor client core for S60 have been installed. You can find it at <Expeditor_Client_CD>\device\install\S60. Put it in the folder named Download under micro SD memory card, and install the feature from eRCP AppMgr. After the S60 core has been installed, the Support Assistant icon is shown on the installation group (see figure 2). If you want to test for Web application, Web service, DB2e, or EJB, install the optional update site as you did Microsoft Windows Mobile using eRCP AppMgr.

Figure 2. Nokia eRCP
Nokia eRCP

Lotus Expeditor Toolkit installation

You can use the trial version of Lotus Expeditor Toolkit. After you download the toolkit ZIP file, extract the file in a temporary location, then install it via Software Updates. To access the toolkit installation instructions, release notes, and other documentation, open the autorun.html file in your browser of choice. Lotus Expeditor Toolkit is divided into four features in two categories as shown in figure 3. The desktop category includes Lotus Expeditor Toolkit 6.1.2.2-20080128, Lotus Expeditor Development Runtimes VM 6.1.2.2-20080128, and Lotus Expeditor Development Runtimes 6.1.2.2-20080128. The device category includes Lotus Expeditor Tooling for Devices 6.1.2.0-20071211.

Figure 3. Lotus Expeditor Toolkit 6.1.2 update site
Lotus Expeditor Toolkit 6.1.2 update site

Depending on your target runtime environment, you can install different combinations of these features. The base feature is the Lotus Expeditor Toolkit 6.1.2 feature, which contains the core tooling, and it should be installed by all developers. To develop applications for devices, install the Lotus Expeditor Tooling for Devices 6.1.2.0. This feature contains a Win32 version of the device client that can be used for building and debugging applications on the Microsoft Windows desktop operating system. For the purposes of this article, we recommend that you install all toolkit features. After you install Lotus Expeditor Toolkit and restart Eclipse, you are presented with the dialog box shown in figure 4.

Figure 4. Toolkit Configuration dialog box
Toolkit Configuration dialog box

Configuration

To develop device applications by Lotus Expeditor Toolkit, select Lotus Expeditor for Device in the Toolkit Configuration option. This option is available only if you have installed the Lotus Expeditor Tooling for Device feature. In addition, the jclDevice VM is selected for you, and the compiler compliance level is set to 1.4.

NOTE: You can develop code for the device platform on Linux®; however, you cannot run or debug the code on these systems. You must create an update site with the features that you want to install and deploy those to the device. Microsoft Windows XP is the recommended platform to use when developing for the Lotus Expeditor for Devices platform.


Project types and application templates

After it is installed, Lotus Expeditor Toolkit creates a new project type, two application templates, and two configuration types. The newly created project type is Client Services, which contain four types of projects as shown in figure 5:

  • Client Service Project, the basic plug-in project
  • Client Service Web Project
  • Client Service Web Service Project
  • Client Service Embedded Transaction Project, also known as Enterprise JavaBeans Project
Figure 5. Client Services Projects
Client Services Projects

Two application templates are created:

  • eRCP Basic Application Template. A minimal, basic eRCP application.
  • eRCP E-mail Application Template. The same as the sample in Sample Gallery.

Two configuration types are created that can be used to launch an eRCP application:

  • Client Service. Used to debug or run an eRCP/RCP application on the desktop.
  • Expeditor on Device. Used to debug an eRCP application on the device.

Create the client services application

Lotus Expeditor Toolkit creates a new client services project when you try to create a new project. Let's see how we use it to create a Client Services project from scratch.

To create a simple client services project, follow these steps:

  1. Choose File - New - Project to open the New wizard.
  2. Expand the Client Services category, select Client Services Project, and click Next.
  3. Enter Client Services Project in the Project Name and click Next.
  4. Click Next to leave the default settings for Client Services Contents.
  5. Click Next to leave the default settings for Target Definition.
  6. Available application templates are shown in figure 6. Select the eRCP e-Mail Application Template and click Finish.
  7. Add some breakpoints in the NormalView.java.
Figure 6. eRCP application templates
eRCP application templates

Now the eRCP e-mail sample has been created in the workspace and is ready to debug on the device.

To create a simple client services Web project, follow these steps:

  1. Choose File - New - Project to open the New wizard.
  2. Expand the Client Services category, select Client Services Web Project, and click Next.
  3. Enter Client Services Web Project in the Project Name field and click Next.
  4. Change the Java version to 1.4 in the Project Facets field and click Next.
  5. Click Next to keep the default settings for Web Module.
  6. Click Finish to keep the default settings for Target Definition.
  7. Choose File - New - Other to open the New wizard.
  8. Expand the Web category, select Web Page, and click Next.
  9. Enter index.jsp in the File Name field, point the Folder to /Client Service Web Project/WebContent, and click Finish.
  10. Extend the com.ibm.eswe.workbench.WctWebApplication extension point which is set in plugin.xml and give it an arbitrary ID.
  11. Right-click com.ibm.eswe.workbench.WctWebApplication extension points, and click New - WEBApplication.
  12. Right-click WEBApplication, and click New - WebApplicationUrl.
  13. Enter the URL that should be identical with the contentRoot value in plugin.xml. In this example, we assign the value /Client_Serivce_Web_Project as shown in figure 7.

Now the client services Web project has been created in the workspace. Let's add some code in the index.jsp shown in listing 1. Add breakpoints between <% and %>

Figure 7. Client service Web extension page
Client Service Web extension page
Listing 1. Sample code of index.jsp
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
<%@page language="java" contentType="text/html; charset=UTF-8"
	pageEncoding="UTF-8"%>
<%! int count=0; %>
<%! int number=1; %>
<html>
<head>
<title>index</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="GENERATOR" content="Rational Application Developer">
</head>
<body>
Hello World.
<% 
	count++;
	number = number+count;
%>The final result is
<%=number %>
</body>
</html>

Now the JSP Web application has been created and is ready to debug on the device.

NOTE: The current Nokia platform does not support client services Web project debugging.


Remotely launch on the device

Application debugging on Microsoft Windows Mobile devices

You can access the debug launcher by choosing Run - Debug from the integrated development environment (IDE) menu. The launcher is named Expeditor on Device. Double-click Expeditor on Device in the left pane to create a new instance of the Expeditor on Device as shown in figure 8.

Figure 8. Lotus Expeditor Toolkit Expeditor on Device launcher - Microsoft Windows Mobile profile
Lotus Expeditor Toolkit Expeditor on Device launcher - Microsoft Windows Mobile profile

Application debugging on Nokia devices

If you want to remotely debug on Nokia, complete the following tasks before you start:

  1. Install the Instrument Agent on your IDE; it can create the Nokia remote launcher profile as shown in figure. 9
  2. Log your Nokia onto WLAN, and examine its IP address from the Nokia IAgent as shown in figure. 10
  3. Fill in the Device IP field that appears in the previous step.
Figure 9. Lotus Expeditor Toolkit Expeditor on Device launcher - Nokia profile
Lotus Expeditor Toolkit Expeditor on Device launcher - Nokia profile
Figure 10. Examine IP of Nokia
Examine IP of Nokia

Click the Debug button to launch the device platform.

Doing so launches the desired application on your device, and the IDE gets into Debug mode when it stop at breakpoint. Now you can debug the application as usual.


Import a sample

You can import the existing samples from Lotus Expeditor Toolkit. To start the samples gallery from Rational Application Developer, select Help - Samples Gallery. The Samples Gallery is displayed in a new window. There are Lotus Expeditor samples for the Devices category under Application samples as shown in figure 11. Click the Import the sample button, and the project is imported into the workspace. You can now run it on the device.

Figure 11. Lotus Expeditor samples for devices in Rational Application Developer samples gallery
Lotus Expeditor samples for devices in Rational Application Developer samples gallery

If you are using Eclipse and not Rational Application Developer, you can import the sample from the file system. To import the eRCP email sample using just Eclipse and the Web Tools Platform, follow these steps:

  1. Choose File - Import - General - Existing Projects into Workspace.
  2. Click Next.
  3. Select the Select archive file option, and then click Browse.
  4. Browse to <eclipse_install>\plugins\com.ibm.rcp.tools.device.samplegallery_6.1.2.<date>\archive\ercpapp.jar, and then click Open.
  5. Verify that the check boxes next to all the projects have been selected, and then click Finish.

Using Lotus Expeditor Toolkit in the device emulator

There is not much difference between emulators and devices. You have to download the Microsoft Windows Mobile emulator image additionally from the Microsoft web site. Follow these instructions:

  1. Launch one of the emulators for the device.
  2. Open the device emulator manager, right-click the emulator device, and then select Cradle as shown in figure 12.
  3. Install Lotus Expeditor Client in the emulator.
Figure 12. Emulator connects to a PC using ActiveSync
Emulator connects to a PC using ActiveSync

Now the device emulator is connected by ActiveSync, and you can do anything as the real device does in previous sessions.


Conclusion

In this article, you reviewed the installation process of Lotus Expeditor Client and Toolkit. You learned how to create a simple Client Services project. You learned how to launch the application on the device and how to import a sample application. You also got a brief overview of the projects that you created with the toolkit. Finally, you saw how the device emulator can be used instead of the real device.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, WebSphere
ArticleID=308322
ArticleTitle=Using IBM Lotus Expeditor Toolkit V6.1.2 for eRCP application development on devices
publish-date=05202008