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?
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 function||Minimum 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, JSP||Eclipse 3.2.2 and Eclipse Web Tools Platform 1.5.4|
|Web service, embedded transaction project and sample gallery||Rational Application Developer V18.104.22.168, Rational Software Architect V22.214.171.124|
or IBM WebSphereÂ® Application Server Toolkit 126.96.36.199 with Eclipse updater iFix
Table 2. Supported device platforms
|MicrosoftÂ® WindowsÂ® Mobile||Pocket PC 2003 Second Edition, Microsoft Windows Mobile 5.0, Microsoft Windows Mobile 6.0|
|Microsoft Windows CE||Microsoft Windows Embedded CE 5.0|
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
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_188.8.131.52-<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
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 184.108.40.206-20080128, Lotus Expeditor Development Runtimes VM 220.127.116.11-20080128, and Lotus Expeditor Development Runtimes 18.104.22.168-20080128. The device category includes Lotus Expeditor Tooling for Devices 22.214.171.124-20071211.
Figure 3. 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 126.96.36.199. 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
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
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:
- Choose File - New - Project to open the New wizard.
- Expand the Client Services category, select Client Services Project, and click Next.
- Enter Client Services Project in the Project Name and click Next.
- Click Next to leave the default settings for Client Services Contents.
- Click Next to leave the default settings for Target Definition.
- Available application templates are shown in figure 6. Select the eRCP e-Mail Application Template and click Finish.
- Add some breakpoints in the NormalView.java.
Figure 6. 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:
- Choose File - New - Project to open the New wizard.
- Expand the Client Services category, select Client Services Web Project, and click Next.
- Enter Client Services Web Project in the Project Name field and click Next.
- Change the Java version to 1.4 in the Project Facets field and click Next.
- Click Next to keep the default settings for Web Module.
- Click Finish to keep the default settings for Target Definition.
- Choose File - New - Other to open the New wizard.
- Expand the Web category, select Web Page, and click Next.
- Enter index.jsp in the File Name field, point the Folder to /Client Service Web Project/WebContent, and click Finish.
- Extend the com.ibm.eswe.workbench.WctWebApplication extension point which is set in plugin.xml and give it an arbitrary ID.
- Right-click com.ibm.eswe.workbench.WctWebApplication extension points, and click New - WEBApplication.
- Right-click WEBApplication, and click New - WebApplicationUrl.
- 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
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
Application debugging on Nokia devices
If you want to remotely debug on Nokia, complete the following tasks before you start:
- Install the Instrument Agent on your IDE; it can create the Nokia remote launcher profile as shown in figure. 9
- Log your Nokia onto WLAN, and examine its IP address from the Nokia IAgent as shown in figure. 10
- Fill in the Device IP field that appears in the previous step.
Figure 9. Lotus Expeditor Toolkit Expeditor on Device launcher - Nokia profile
Figure 10. 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
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:
- Choose File - Import - General - Existing Projects into Workspace.
- Click Next.
- Select the Select archive file option, and then click Browse.
- Browse to <eclipse_install>\plugins\com.ibm.rcp.tools.device.samplegallery_6.1.2.<date>\archive\ercpapp.jar, and then click Open.
- 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:
- Launch one of the emulators for the device.
- Open the device emulator manager, right-click the emulator device, and then select Cradle as shown in figure 12.
- Install Lotus Expeditor Client in the emulator.
Figure 12. 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.
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.
- Read the developerWorksÂ® Lotus article, "Introducing IBM Lotus Expeditor V6.1.1".
- Read the developerWorks Lotus article, "Getting started with the IBM Lotus Expeditor Toolkit V6.1.1".
- Read the developerWorks Lotus article, "Explore Eclipse's embedded Rich Client Platform".
- Read the developerWorks Lotus article, "Develop eRCP applications with Eclipse".
- Read the developerWorks Lotus article, "Developing embedded applications with eJFace".
- Read the developerWorks Lotus article, "Developing and deploying rich client applications on desktops and mobile devices using IBM Lotus Expeditor V6.1".
- In the Lotus Expeditor area on developerWorks, get the resources you need to advance your skills in the Lotus Expeditor arena.
- Browse the technology bookstore for books on these and other technical topics.