This article provides a high-level tour
of the IBM Lotus Expeditor Toolkit. Learn how to install and configure
the toolkit, how to import a sample into the tools, and how to launch the
sample in the Expeditor Test Environment.
IBM Lotus Expeditor Toolkit provides a complete, integrated set of tools
that allows you to develop, debug, test, package, and deploy client applications
to IBM Lotus Expeditor V6.2, IBM Lotus Symphony V1.2, and IBM Lotus Notes
V8.5. You can use the toolkit to develop the following types of client
- Eclipse Rich Client Platform (RCP) applications
(desktop client only)
- Eclipse embedded Rich Client Platform
- Web applications
- Portlet applications (desktop client
- Database applications
- Messaging applications
- Web services applications
The toolkit provides wizards that enable you to create Client Services
projects to develop client applications. The toolkit uses target definitions
to provide a convenient method for you to specify the runtime environment,
the build-time environment, and the set of components that can run on the
platform. For example, when you create a Client Services project, you select
a target definition from a list of available targets, and then a set of
features from a list in the target definition. The toolkit uses this information
to automatically set up the Java build path and runtime for your project.
You can then edit, compile, and debug your project. The toolkit provides
a default list of target definitions; however, you can also create your
Who should use the toolkit?
Lotus Expeditor Toolkit is intended for use by Java, Eclipse RCP, and J2EE
developers. Using the provided tools, you can reuse your existing skills
and resources to deploy existing applications or to build new applications
for your target runtime environment.
A non-warranted and non-supported version of the Lotus Expeditor Toolkit
6.2 is available for download from the DeveloperWorks
page. The downloaded
file contains an update site that can be installed into an existing Eclipse
3.4 or later based IDE, including IBM Rational Application Developer for
WebSphere Software V7.5.
At a minimum, Lotus Expeditor Toolkit requires Eclipse 3.4. For most functions,
including the sample used in this article, you should also install the
Eclipse Web Tools Platform (WTP). This can be installed from the predefined
Ganymede Discovery site available in Eclipse. If you do not already have
a version of Eclipse and the Eclipse Web Tools Platform installed, you
can download and install the Java EE project bundle of Eclipse from the
project page. The Java
EE project bundle and Lotus Expeditor Toolkit together provide everything
needed for development of Java, Web, and Web services applications for
Lotus Expeditor. Most application types can be created using just Eclipse
Ganymede (3.4), WTP, and the toolkit. If you create portlet applications,
you need to install Rational Application Developer V7.5. If you are not
already a Rational Application Developer customer, you can download and
install an evaluation
of the software. Prior
to installing Lotus Expeditor Toolkit in Rational Application Developer,
be sure to update to the latest fix pack of the Rational software.
Table 1. Required software
|Application type or
software for Lotus Expeditor Toolkit
|Standard Java and Eclipse RCP and
|Web Application Java, JSP, Servlet
||Eclipse 3.4 and Eclipse Web Tools
|Web Application Portlet container
||Rational Application Developer
7.5 or IBM Rational Software Architect 7.5|
Test Environment Installation
Releases of the toolkit prior to V6.2 included test environments for the
Lotus Expeditor Client for Desktop and Lotus Expeditor Client for Devices
product offerings. These test environments were provided to facilitate
the build and test of applications through the Lotus Expeditor Toolkit.
With the 6.2 release of the toolkit, this is no longer the case. The appropriate
client product offering must be installed before installing the toolkit.
For the purposes of this article and follow-up articles, it is recommended
that you install the Lotus Expeditor Client for Desktop product offering.
To do so, follow these instructions:
- On Windows systems, run the setupwin32.exe
program and follow the installation instructions.
- On RedHat or Suse Linux Enterprise Desktop
(SLED) systems, run the installation by double-clicking the RPM and using
the graphical RPM installer, or, alternatively, run the installer from
the command line as follows:
The installation programs are located in the desktop/install
directory on the Client DVD.
To start the client, click the Lotus Expeditor Client shortcut on your
desktop (on Windows systems) or in the Application > Office
(on Linux systems).
To develop Lotus Expeditor Client for Desktop applications with the Lotus
Expeditor Toolkit, you must install the Desktop Development Enablement
Utilities Feature which contains the following items:
- JavaDoc and .exsd files for public APIs
in the client
- DesktopEE SDK VM
- Target definitions that represent configurations
that are supported for the client
Install this feature as follows:
1. Click File > Application > Install
to open the installation wizard.
2. Select the Search for new features to
option, and then click Next
3. Select Add Folder Location
. In the
Browse For Folder
dialog box, browse to the platform update site
on the Client DVD (in the desktop/updates/platform
then click OK
4. When the Edit Local Site dialog box displays,
and then click Finish
5. When the Updates dialog box displays, expand
location, select the Development
containing the Lotus Expeditor Desktop Development Utilities feature and
then click Next
6. Carefully review the license agreements for
the feature. If the terms of the license are acceptable, select I accept
the terms in the license agreements
. Do not proceed to download the
feature if the license terms are not acceptable.
7. Click Finish
to allow the download
and installation to proceed.
After installing the feature, you are prompted to restart Lotus Expeditor
for the changes to take effect. Select Yes
. The client closes and
After you download the toolkit ZIP file, unzip the file in a temporary
location. To access the toolkit installation instructions open the index.html
file in your browser of choice. Lotus Expeditor Toolkit is divided into
two features in two categories as shown in figure 1. The Lotus Expeditor
Toolkit category includes Lotus Expeditor Toolkit 22.214.171.12481020
and the device category includes Lotus Expeditor Device Toolkit 126.96.36.199-20081017
Figure 1. Lotus Expeditor Toolkit V6.2 update site
The Lotus Expeditor Toolkit V6.2 feature contains the core tooling, and
it should be installed by all developers. You should install the Lotus
Expeditor Device Toolkit V6.2 if you develop applications for devices.
For the purposes of this article and follow-up articles, it is recommended
that you install just the toolkit feature in the Lotus Expeditor Toolkit
category. Follow the detailed instructions provided in the index.html
file to complete the install.
After you install Lotus Expeditor Toolkit and restart Eclipse, you are
presented with the configuration dialog box shown in figure 2.
Figure 2. Toolkit Configuration dialog box
To develop applications for Lotus Expeditor for Desktop, select Lotus
Expeditor for Desktop
in the Test Environment option. The Target Location
shown represents the default location for the Lotus Expeditor Client for
Desktop product offering. If you installed the client into an alternate
location, use the Browse
button to navigate to the correct location.
In addition, the desktopEE VM is selected for you, and the compiler compliance
level is set to 1.5.
To develop applications for Lotus Expeditor for Devices, select Lotus
Expeditor for Devices
in the Test Environment option. This option is
available only if you installed the Lotus Expeditor Device Toolkit feature
and the Lotus Expeditor Client for Devices product offering. The deviceEE
VM is selected for you, and the compiler compliance level is set to 1.4.
Windows XP is the recommended platform to use when developing
for the Lotus Expeditor for Devices platform.
It is also recommended that you select the option Display the first
time a workspace opens
in the Test Environment Configuration Preferences
dialog box. This selection causes the configuration dialog box to be presented
only the first time the toolkit is used in a workspace. You can change
this preference later in any workspace. When you click OK
, the Eclipse
IDE is reconfigured for development against Lotus Expeditor for Desktop.
If you want to change the configuration of the toolkit later, you can access
the configuration preference by choosing Window > Preferences >
. On this page, you can reconfigure the environment
to any of the other supported environments. Click the Configure
button, and modify the IDE using the same dialog box as presented at startup.
After you save your changes in the dialog box, Eclipse is updated with
your new selections.
Applications built to run on Lotus Expeditor must provide information to
the platform about their contents through the OSGi Manifest file. For additional
information on the OSGi manifest, see the "Creating
" topic in
the Lotus Expeditor Developers Guide.
Lotus Expeditor Toolkit also provides the ability to automatically manage
OSGi manifest dependencies. (For more information, read the developerWorks
how Eclipse plug-ins work with OSGi
) The default setting automatically adds Import-Package statements into
your manifest file as necessary. If you want to use Require-Bundle statements
for manifest dependencies, select the Give preference to Require-Bundle
option and click OK
. In general, the default selection of Import-Package
is the most appropriate. For additional details on the OSGi manifest, Require-Bundle,
and Import-Package, refer to the "Class
" topic of the Lotus
Expeditor Information Center. The preference can be modified later by choosing
Windows > Preferences > Client Services > Development
Import a sample
Lotus Expeditor Toolkit provides a large number of samples for both Desktop
and Device applications. When you use Rational Application Developer, you
can import the samples from the Help system. To start, simply choose Help
> Help Contents
from Rational Application Developer. The help is
displayed in a new window. Expand Samples in the left pane of the window
and there are Lotus Expeditor samples and/or a Lotus Expeditor samples
for Devices category under Showcase samples, Application samples, and the
Technology samples sections of the Samples Gallery as shown in figure 3.
Figure 3. Order entry sample in Rational Help System
To import a sample, select the sample you want to import in the left pane
and click the option Import the sample
in the right pane. Let's
use the Order Entry sample, available from the Showcase samples section,
to demonstrate the launch capability; import that feature now. When you
are presented with the Order Entry sample dialog box as shown in figure
4, click Finish
Figure 4. Import Order Entry sample
The sample projects are imported into the workspace. If you have configured
Eclipse for use with the device client, reconfigure the environment now
for Lotus Expeditor for Desktop.
If you are using Eclipse and not Rational Application Developer, you can
import the sample from the file system. To import the Order Entry 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. Choose the Select archive file
and then click Browse
4. Browse to \plugins\com.ibm.rcp.tools.samplegallery_6.2.0.\archive\orderentry.jar
and then click Open
5. Verify that the checkboxes next to all the
projects have been selected, and then click Finish
as shown in figure
Figure 5. Import the Order Entry sample in Eclipse
The Order Entry sample is really two separate interface samples. The Order
Entry Web sample is an example of a Web (JSP/servlet)-based application
that can run locally on Lotus Expeditor Client. It requires either Rational
Application Developer or Eclipse and the Web Tools Platform (WTP) to build
the Web application. The Order Entry sample also includes the Order Entry
Rich Client sample, which shows an SWT-based user interface. The business
logic used in the sample is shared between the Web and the Rich Client
versions. The Rich Client version can be built and run using only the Eclipse
Lotus Expeditor Toolkit provides a custom launcher that can be used to
launch Lotus Expeditor for Desktop, Lotus Expeditor for Devices, Lotus
Sametime, and Lotus Notes. You can access the launcher by choosing Run
> Run Configurations
from the IDE menu. The launcher is named Client
Services. Select the Client Services launcher in the left pane, and then
click the New
button. This creates a new instance of the Client
Services launcher as shown in figure 6.
Figure 6. Lotus Expeditor Toolkit Client Services launcher
The launcher is populated with all the options you need to launch your
configured platform. Click the Run
button to launch the client platform.
Lotus Expeditor Client is launched, and you are asked to create a new password
if this is your first launch in the selected workspace; otherwise, you
can enter your previously created password.
Start the Web version of the sample by clicking the Open
and choosing Order Entry Web Sample
from the drop-down list.
You then see the starting page of the Web version of the sample as shown
in figure 7. Click the Start
button to begin using the sample application.
Create a few new orders using the Web user interface.
Figure 7. Home page for the Order Entry Web Sample
Now start the rich client version of the sample by clicking the Open
button and choosing Order Entry Rich Client Sample
You then see the starting page of the Rich Client version of the sample.
If you created orders in the Web version, you see these orders reflected
in the Rich Client version as well as shown in figure 8.
Figure 8. Home page for the Order Entry Rich Client Sample
At this point, both the Web and the rich client versions of the sample
are running. Because the two different applications share a common set
of backend logic, orders that are created in one user interface are reflected
in the other. You can move between the two versions of the sample, creating
new orders in each interface by selecting the different application tabs
at the top of the user interface.
A basic Order Entry Server is also provided as part of the sample. If you
want to see the orders processed, refer to the Order
in the Help system or in the developers guide.
When you are ready to create your own applications, you can create projects
using Lotus Expeditor Toolkit. The toolkit provides four different types
of projects, which you can see by choosing File > New > Projects
> Client Services
category from the Eclipse menu. The four project
types are the Client Services Project, the Client Services Web Project,
the Client Services Portlet Project, and the Client Services Fragment Project
as seen in figure 9. The Client Services Platform and Client Services Target
wizards let you create Platform and Target File Definitions respectively
in an existing project within your workspace. The Wiring Properties wizard
lets you create a Property Broker WSDL file in an existing project within
your workspace. This file can be modified using the Property Broker Editor
component packaged with the Lotus Expeditor Toolkit.
Figure 9. Lotus Expeditor project types
Table 2 lists the recommended use of the project types.
Table 2. Project types and their recommended use
|Client Services project
||Basic Java code, user interfaces build from SWT and JFace,
JDBC access, or other access to most Lotus Expeditor Java APIs.
|Client Services Fragment project
||Packaging of native code, platform-specific code, and
translated material in properties, XML files, and so on.
|Client Services Web project
||Servlets, JSPs, Axis 1.4 Web service clients.
|Client Services Portlet project
||JSR-168 portlets; these projects are available only in
Rational Application Developer when you install the Portlet tools.
In addition to the default configurations that Lotus Expeditor Toolkit
provides, there are other advanced configuration options that you may find
useful. Lotus Expeditor Desktop Client and Device Client are designed to
be configured and installed in a number of custom configurations to meet
your needs. Lotus Expeditor Toolkit enhances the Eclipse concept of targets
to allow you to simulate different configurations of the clients in your
development environment to match the version installed on users' systems.
When you configure Lotus Expeditor Toolkit for Desktop, the workspace target
is set to the Default Target. Two other configurations of Lotus Expeditor
are provided for you to work with. The core target provides a subset of
Lotus Expeditor that matches its minimum working set. The Default with
Embedded Sametime Target allows you to launch Lotus Expeditor along with
the embedded version of Lotus Sametime.
Figure 10 shows Lotus Expeditor Client running the Order Entry rich client
sample along with the embedded version of Lotus Sametime in the sidebar.
Figure 10. Order Entry rich client sample running with embedded Lotus Sametime
in Lotus Expeditor
The target that is used can be selected in a few different places. To set
the default for the workspace (that is, for new projects and new launch
configurations), set the Default Target Selection on the Window >
Preferences > Client Services > Development
preference page as
shown in figure 11.
Figure 11. Set the workspace default target from the Clients Services –
You can also override the workspace default for each project. During the
project creation process, you can select from any of the available targets
in the system. To limit the choices, deselect the ones you do not need
in the Select the Targets to be available for development
on the Client Services > Development
preference page (see figure
11). When you create a launch configuration, you can override the launch
that is used by selecting the Targets
tab of the launcher.
You can use the Core target provided by the toolkit as a template to create
your own custom configurations of Lotus Expeditor and to launch them from
the toolkit. To create your own target, import the Core target and use
the Client Services target editor to add the features that your custom
Lotus Expeditor platform contains. See the "Creating
a Target Definition
of the Lotus Expeditor Developers Guide for more information on creating
a custom target.
In this article, you reviewed the process for installing and configuring
Lotus Expeditor Toolkit. You learned how to import a sample application
and how to launch the application on the Lotus Expeditor Client for Desktop
product offering. You also got a brief overview of the projects you can
create with the toolkit. Finally, you saw some advanced features of the
toolkit that you can use in developing applications for custom Lotus Expeditor