Assembling and Deploying Lotus Expeditor 6.2.2 Applications

Seventh Edition

July 2010

About this edition

In keeping with IBM's commitment to accessibility, this edition of the product documentation is accessible.

Printing

When you print this document some of the style elements are removed to create a better print output. Here are a few tips about printing:
  • The document length may exceed the browser's print capability. Microsoft Internet Explorer has demonstrated the ability to print large files successfully.
  • This document is long. Use print preview to determine the printed page length.
  • You can highlight section of the document and then choose to only print the selected content

Working offline

You can save a local copy of this document from your browser. Each browser has different menus and menu options. Consult the browser help if you need assistance saving the document locally.

Submitting feedback

If you would like to provide feedback about this document, see the Lotus Documentation Feedback Web site.

Understanding Expeditor Client runtime configuration

This section introduces the Lotus® Expeditor Client's runtime configurations.

The Lotus Expeditor Client is built on an Eclipse platform. Eclipse is an award-winning, open source platform for the construction of powerful software development tools and rich desktop applications. Leveraging the Eclipse plug-in framework to integrate technology on the desktop saves technology providers time and money by enabling them to focus their efforts on delivering differentiation and value for their offerings. Full details on Eclipse are available at http://www.eclipse.org.

Multi-user configuration

Lotus Expeditor Client only supports installing for multiple users on the same machine, such as a workstation used as a kiosk with individual operating system log-ins.

You, as administrator, install all applications and the users enable them into their individual configurations. The installer must be a member of the administrator group on Windows or defined as root on Linux.

Choose from two locations to install applications for a user: ${rcp.home}/rcp, and ${rcp.home}/shared. As administrator, you control all of these locations. Users must only have read and execute permissions for these locations. As administrator, you can install multiple versions of the same feature. If there are multiple versions, a user is able to select which version to use.

A user can install applications to their private user site. In most cases, it is recommended that you, as administrator, install these applications to the shared site.

A user can install multiple versions of the same feature in his application site. If there are multiple versions, a user is able to select which version to use if the history size is not set to 0.

Follow these administrative steps for installing for your users:
  1. Log in as an administrator on Windows or as root on Linux.
  2. Choose a root site for the install tree
  3. Change the permissions on the root site so only you can write to the installed areas.
  4. Create group access with only read and execute permission.
  5. Install the Lotus Expeditor Client at this location.
  6. Notify users to launch the desktop icon for the first time. When a user initially launches the desktop icon, a provisioning cycle is initiated for this user. The workspace and configuration space are initialized. The provisioning cycle will use the deploy manifest file to do this. For more information on customizing this manifest, see Customizing basic installation.

    The Lotus Expeditor Client is launched for the first time for the user. The user can use any of the provisioning modules provided to customize his or her environment.

  7. Install additional applications or features, as needed. This enables the new applications or features for all users.

    If you are installing additional features through Update Manager on Vista you must start Expeditor using "Run as Administrator" to get the features enabled to all users. If you install features without being an elevated administrator they will only be installed on your user applications site.

Security

The core install sites ${rcp.home}/rcp, and ${rcp.home}/shared and any additional sites added as <root> sites must have the access rights controlled. Users should only be given read and execute access to these sites.

On Windows, the default access rights may give any user change rights. This allows a user to add files to the Lotus Expeditor Client install tree. For a secure installation, it is recommended that you remove these change rights. If the change rights are not removed, a user can add an untrusted feature to a site by copying. At this point, any user could install it.

First-time provisioning

The first time that the multiple user environment is installed and setup, you, as administrator, select the level of base features to install. This sets the base level for all users. When a user starts Lotus Expeditor Client for the first time, the user's configuration, workspace, and feature set are provisioned to the same level as initially selected by the administrator. Provisioning guarantees that the version used for a feature is the same or higher.

This first-time provisioning happens once. From that point forward, the feature set is individualized for each user as needed.

Restricted Workbench Service

Enable the Restricted Workbench Service to provide a restricted environment in which all Lotus Expeditor users are limited to the applications and operating system services that you, as administrator, have configured.

When the Restricted Workbench Service is enabled and a user without administration privileges logs on to the operating system, the Lotus Expeditor is launched and the Restricted Workbench Service is automatically enabled. For non administrative users, the Lotus Expeditor replaces Windows Explorer as the desktop shell on Windows systems. On Linux systems, the Lotus Expeditor replaces the GNOME Window Manager's default session. The following restrictions are imposed on the Workbench:
  • The Workbench alters its behavior, look, and feel, as follows:
    • No title bar
    • No sizing borders
    • Maximized to fill the screen
    • Pinned down in the Z-order such that no other windows can be drawn beneath it
    • Cannot be closed, re-sized, or minimized
    • The menu sequence File > Exit is removed from the Menu Bar
  • The user is not able to gain access to the file system except through items contributed to the shared contribution areas of the Workbench (Cool Bar, Menu Bar, or Application Switcher Bar).
  • The user is not able to gain access to any native applications except through items contributed to the Application Launcher.
  • The user is not able to gain access to any operating system functions (for example, screen lockup, logoff, shutdown, change locale) except for the use of the Alt + Tab key combination to navigate between open native windows and through items contributed to the shared contribution areas of Workbench (Menu Bar and/or Eclipse Preference Pages)
  • The user is blocked from performing the following key-stroke combinations:
    Windows:
    Alt + F4, which closes the window with focus. This is only blocked on the Lotus Expeditor window; other windows can still be closed with Alt + F4.
    Ctrl + Shift + Esc, which opens the Windows Task Manager. Task Manager lets you stop processes (including Lotus Expeditor).
    Windows Logo Key + L, which locks the display.
    Ctrl + Alt + Delete, which displays the Windows Security dialog. The Window Security dialog is not blocked but all the buttons except for Cancel are disabled.
    Linux:
    Alt + Ctrl + Backspace, which terminates the gnome session.
    Alt + Ctrl + (F1 through F12), which switches between virtual terminals.

The Windows XP operating system introduced the notion of "Use Fast User Switching" to change credentials but not fully logout and exit all running applications. If these settings are enabled, the system security policy is also altered to provide a more streamline experience for the users. When running the Lotus Expeditor in Restricted Workbench mode, it is recommended you disable the "Welcome Screen" and "Use Fast User Switching" settings to further increase your administrator control over the system. For instance, if these settings are enabled, and a system screensaver is set, once the screensaver activates and then is deactivated, the user will be presented with a dialog allowing him or her to shutdown or logoff the system. Another modification relates to the Ctrl + Alt + Del key sequence, which presents a Windows Security dialog. If the Lotus Expeditor Restricted Workbench is installed, and the "Welcome Screen" and "Use Fast User Switching" settings are disabled, the only option available to the user on this dialog is Cancel. However, if the "Welcome Screen" and "Use Fast User Switching" options are enabled, the user will again have the ability to logoff or shutdown the system. When installing the Restricted Workbench, these settings are automatically disabled to provide a more secure environment.

To verify these settings, perform the following steps:
  1. Click Start > Control Panel.
  2. Click the User Accounts control panel.
  3. Click Change the way users log on or off.
  4. Modify the Welcome Screen and Use Fast User Switching options accordingly.
  5. Click Apply Options.

Additionally, the default Administrator Windows XP account should not be used to install the Lotus Expeditor Restricted Workbench. It is recommended that you create a secondary administrative user account and use this account to install the Restricted Workbench environment.

For more information, see Installing with the Restricted Workbench Service.

Enterprise Management Agent Client

You can enable your Lotus Expeditor workstations to be managed by an Expeditor Server. This is one way to centrally administer your Lotus Expeditor environment.

The Expeditor Server contains the Client Management server component and provides basic platform management of the client along with additional features, such as support for ISync and MQe servers.

For more information, see Managing with a Client Management server.

Portal-administered client

You can enable your Lotus Expeditor Client workstations to receive configuration information from a WebSphere® Portal server. This is one way to centrally administer your Lotus Expeditor Client environment.

The portlet container allows for many different client side architectures with the composite application infrastructure. There are two primary ways applications can run on the client:
  • A standard widget toolkit (SWT)-based application aggregated and deployed by Portal. This application is composed of SWT-based views and is placed on the Portal with the various view components wired together with the Portal wiring tool.
  • Locally running portlets. Properly bundled portlets can be run locally and off-line in the Lotus Expeditor Client. This ability, mixed with Property Broker, allow for the locally running portlets to inter-communicate with each other. These disparate components can then communicate with each other using the declarative wire expressed in the composite application XML.
Additionally, a third way of encapsulating Web applications with other components is by wrapping the Managed Browser in a managed browser SWT view that exposes property broker actions and properties. This has the same effect as a traditionally wired experience of any portlet or view driving another component (in this case a browser taking in URLs).

For more information, see Managing Rich Clients using the Portal server.

Network Client Install

Install the Network Client Installer so that users can remotely install the Lotus Expeditor, install the administrative components needed on your Portal server, and manage the Lotus Expeditor.

See Installing with the Network Client Installer for more information.

Understanding the client file layout

When the Lotus Expeditor Client is installed on a machine, the installer creates a directory structure in the installation directory. This section describes the layout of the installation directory installed on the client platform.

<installation directory>/
    ITLM/                             - For license management
    license/                          - Product licenses in multiple languages
    rcp/                              - Platform components
         deploy/
				install.xml
         jvm.properties
         plugin_customization.ini
         eclipse/
         .eclipseproduct
         features/
         links/                        - Required by the Toolkit. Not used by Expeditor
         plugins/
         rcplauncher                   - Platform launcher for Linux
         rcplauncher.exe               - Platform launcher for Windows
         rcplauncher.properties        - Platform launcher configuration file
         startcollector.bat            - IBM Support Assistant log collector utility (Windows)
         startcollector.sh             - IBM Support Assistant log collector utility (Linux)
         systemdata/                   - Workspace used during Linux install or Windows System install
         installHistory/               - Install snapshots of critical log files to add support in debugging install issues 
             collectionutility.jar     - Internal install utility to gather provisioning data for support 
    shared/                            - Site to contain apps shared across multiple configs
         eclipse/
             .eclipseproduct
             features/
						plugins/

Single sign-on with the operating system

Configuring the Lotus Expeditor platform to provide single sign-on (SSO) with the operating system enables a user, who has successfully logged into the operating system, to gain access to resources protected by the Lotus Expeditor platform without ever being prompted for a password.

The Lotus Expeditor platform stores security-related information, such as authentication credentials (passwords), keys, and certificates in the local keystore. When SSO with the operating system is enabled, the Lotus Expeditor platform stores the password that is used to unlock the credential store in the operating system's native credential store.

Managed settings

The managed settings framework allows you control over the runtime behavior of client applications by letting you set the values of the settings that the applications are reading out of the Eclipse preference store.

If you also designate these settings as read-only, any changes that the client applications make to the settings will either be prevented or be subsequently overwritten with your values, depending on how the client accesses the settings. If the client program knows about managed settings and accesses them through the ManagedSettings Eclipse preference scope, any changes to read-only settings are prevented. For other plug-ins, which access the settings in the traditional way, changes can occur but are later overwritten with your values. Updates are run regularly to add any of your new settings or settings changes to the preference store on the client.

The managed settings framework can retrieve policy, preferences, or any other name and value pairs from any back-end system for which there exists a managed settings provider. Providers contain the knowledge of the specific back-end system. Lotus Expeditor Client includes providers to retrieve settings both from Portal Policy Manager and from an XML file residing on an HTTP server. Lotus® Notes® 8.0 includes a provider to retrieve policies from Domino® using the Notes® client. If there is no provider available for your back-end system, you may write your own. See Adding a managed settings provider for more information.
Note: Managed settings will not work when using Portal 6.0.1. Portal 6.0 or Portal 6.0.1.1 must be used.

Installing and launching the Lotus Expeditor Client

This section describes how to install and launch Lotus Expeditor Client onto client machines.

There are several installation methods available. Before you install Lotus Expeditor Client, ensure that each machine on which you are installing meets the client prerequisites.

Installing the Lotus Expeditor Client on the desktop

Before you install Lotus Expeditor Client, ensure that each system meets the minimum hardware and software requirements.

Complete hardware and software requirements for Lotus Expeditor are documented here: http://publib.boulder.ibm.com/infocenter/ledoc/v6r2/topic/com.ibm.help.ic.doc_3.1.1/expeditor_sysreqs_62.html

Installing from a CD

This section provides the steps involved in installing Lotus Expeditor Client from a CD.

Before you install the Lotus Expeditor Client, check that there is enough space in the temporary directory of your operating system. In addition to the space required to install the product,the temporary directory of your operating system must have at least 200 MB free.

Use the following steps to install Lotus Expeditor Client on Microsoft Windows from a CD.
  1. Insert the Lotus Expeditor Client CD into the CD-ROM drive.
  2. Launch the setupwin32.exe installer executable file. The installer is located in the install/ directory on the CD.
  3. The Lotus Expeditor Client Installer guides you through the rest of the installation:
    1. At the installer welcome page, click Next.
    2. Read the license. To accept the license, select I accept the terms in the license agreement and click Next.
    3. If a previous version is detected, you are prompted to upgrade. Click Next to continue and proceed to step 3e.

      During installation, the installer checks for Lotus Expeditor Client 6.1.x. If it is found, your settings are upgraded and the installation continues. If you have Lotus Expeditor Client 6.0 installed, you must first install and migrate to Lotus Expeditor Client 6.1 using the 6.1 installer and then upgrade to 6.2.

    4. Enter the destination where you want to install the Lotus Expeditor Client and click Next.
      Note: The default destination might not be accessible by the current user. In this case, change the location to a user-accessible destination. For example, C:\Documents and Settings\user99\IBM\Lotus\Expeditor.
    5. If you would like to install optional program features, select them and click Next.
    6. If a previous version is detected, you must ensure that Lotus Expeditor Client is not running, then click Next. Otherwise, continue to step 3g.
    7. To begin the installation, click Install.
    8. After the installation is complete, click Finish.
Note: During a product upgrade, the platform site (install dir/rcp/eclipse/) is replaced. If you installed additional features into this site (not part of the product installer), you might need to reinstall these features after the upgrade.
Note: Note: The following characters are not allowed in the install path: ;%#<>"!?*|
Use the following steps to modify an installed version of Lotus Expeditor Client on Microsoft Windows from a CD.
  1. Insert the Lotus Expeditor Client CD into the CD-ROM drive.
  2. Launch the setupwin32.exe installer executable file. The installer is located in the install/ directory on the CD.
  3. The Lotus Expeditor Client Installer guides you through the rest of the installation:
    1. At the installer welcome page, click Next.
    2. Select the Modify option and click Next.
    3. Select the optional program features to install or remove, then click Next.
    4. Ensure that Lotus Expeditor Client is not running, then click Next.
    5. To begin the installation, click Install.
    6. After the installation is complete, click Finish.
Use the following steps to install Lotus Expeditor Client on Linux from a CD:
  1. Insert the Lotus Expeditor Client CD into the CD-ROM drive.
  2. Launch the installation. The installer is located in the install/ directory on the CD.
    1. On RHEL or SLED, you can launch the installation by double-clicking the RPM and using the graphical RPM installer, or you can run the installer from the command line as follows:
      rpm -Uvh <name of .rpm file>
    2. On Ubuntu, you can launch the installation by double-clicking the Debian package and using the graphical package installer, or you can run the installer from a terminal as follows:
      sudo dpkg -i <name of .deb file>
    Note: When using the graphical RPM installer during upgrade or uninstall, the graphical installer might report a success even if the underlying RPM installation has failed. You might need to verify that an upgrade or uninstall has completed successfully by checking the rcp_install.log and/or rcp_uninstall.log in <install dir>.
  3. If you want to upgrade from Lotus Expeditor Client 6.1.x you must be sure to install the RPM to the same location where Lotus Expeditor Client 6.1.x was installed. To do this upgrade, assign the --prefix=<dir> option to RPM. For example:
    rpm -Uvh --prefix <location of 6.1.x installation> <name of .rpm file>
  4. After the installation is complete, you can launch the platform using the icon created in the Applications > Office menu. On first launch, are presented with a license acceptance window. (Each user on the system sees this by default).
Note: During a product upgrade, the platform site (install dir/rcp/eclipse/) is replaced. If you installed additional features into this site (not part of the product installer), you might need to reinstall these features after the upgrade.
Note: The following characters are not allowed in the install path: \;:%#<>,"!|?

Installing from a shared network location

This section provides the steps involved in installing Lotus Expeditor Client from a shared network location.

Use the following steps to install Lotus Expeditor Client from a shared network location.
  1. Map to the shared folder.
  2. Continue with step 3 described in Installing from a CD.
Note: If installing on Microsoft Windows Vista, you must run the installation as an administrator:
  1. In Windows Explorer, right-click setupwin32.exe and select Run as Administrator.
  2. Follow the prompts to complete the installation.
  3. Launch IBM® Lotus Expeditor as the standard user using <install location>\rcp\rcplauncher.exe. This step creates a workspace and desktop icon for the standard user.

For network share installation to complete successfully on Microsoft Windows Vista, you might need to adjust to the Local security policy for UAC or disable it.

Installing with the Restricted Workbench Service

Enable the Restricted Workbench Service to provide a restricted environment in which all Lotus Lotus Expeditor users are limited to the applications and operating system services that you, as administrator, have configured.

The Restricted Workbench Service can be enabled only during initial installation; it cannot be added to an existing installation. The Expeditor Restricted Workbench client does not support uninstallation. Running the uninstallation program might appear to function properly, but the system can encounter problems when logging in as a previously restricted user afterward. It is necessary to reinstall the base operating system instead of attempting to remove the Lotus Expeditor Restricted Workbench.

Notes:
  • If performing an upgrade of a previously installed Microsoft Windows XP Restricted Workbench environment, it is necessary to ensure Microsoft Windows Installer 3.1 or greater is already installed and configured, or the system becomes unusable.
  • Due to a known limitation of Java, it is necessary to execute the following commands as the root user on Linux machines, after the initial Lotus Expeditor Restricted Workbench installation:
    1. Exit Lotus Expeditor if it is running
    2. Specify the following:
      cd /opt/ibm/Lotus/Expeditor/rcp/eclipse/plugins/com.ibm.rcp.lockdown.gtk_6.2.2.<date>/install
    3. If the directory uninstall/restricted exists, specify rm -rf uninstall/restricted
    4. Specify ./lockdown.sh install
  • When installing the Restricted Workbench environment on Windows XP systems you must launch the installation from the command line with the following additional parameters:
    setupwin32.exe /v"LOCKDOWN=true"
  • On Windows XP, the Restricted Workbench environment must be installed on the system drive (typically C:) and not an additional drive. Doing so might render the system inoperable.

* The Restricted Workbench environment is supported only on Microsoft Windows XP, Redhat Enterprise Linux 5.4/5.3, and SuSe Linux Enterprise Desktop 10 systems.

The Restricted Workbench Service is available in multiuser installation environments only. To enable the Restricted Workbench Service during product installation, ensure that the installation manifest (whether using the provided version or creating your own custom manifest file) contains the following information:
<feature 
        id="com.ibm.rcp.lockdown.feature" 
        version="<feature version>" 
        match="compatible" 
        action="install"
        shared="false" 
/>

See Customizing basic installation for more information on installing manifest files.

Accessing the operating system

As an administrator, you can access the operating system while the Restricted Workbench Service is installed.

To access the unrestricted operating system, for example the Gnome shell in Linux, follow these steps:
  1. Log on to the operating system as an administrator.
  2. The default operating system window shell is displayed.
You are logged in to the unrestricted operating system.

Changing Home Portal Account settings for users in the Restricted Workbench environment

You can change the Home Portal Account settings for users in the Restricted Workbench environment.

You can change the Home Portal Account server address or user name and password for users in the Restricted Workbench environment by altering either the preferences or the plugin_customization.ini, as follows:
com.ibm.rcp.platform/portalServerAddress=<your_portal_server>:port/wps
com.ibm.rcp.platform/portalEnabled=true
com.ibm.rcp.platform/portalAuthType=PORTAL-FORM
When a portal resource is accessed, the user is prompted for a user name and password. The user is then given the option to store these credentials in the account.

Embedding Linux native applications into Lotus Expeditor

Lotus Expeditor allows you to embed the initial top-level windows of GTK-based applications in Eclipse views within the Lotus Expeditor framework.

Native Application Embedder View example
The following example illustrates the basic elements of launching a native application and embedding it inside the Lotus Expeditor workbench. Key concepts demonstrated include:
  • Use of the Native Application Embedder View to launch and embed a native application in the workbench
  • Use of the GtkNativeApplication extension point to specify the native application and the attributes to control the behavior of the view
  • Dynamically launching a specific native application and embedding it inside a Native Application Embedder View when a user clicks an attachment within the previously embedded application
  1. Create a Client Services or plug-in project.
  2. Set the Required Bundle as: Require-Bundle: com.ibm.rcp.applauncher.gtk.linux.x86.
  3. Create a simple Eclipse perspective implementation as shown:
    package nativeSamplePerspective; 
    import org.eclipse.ui.IFolderLayout; 
    import org.eclipse.ui.IPageLayout; 
    import org.eclipse.ui.IPerspectiveFactory; 
    
    public class Perspective implements IPerspectiveFactory { 
    
    IFolderLayout a = null;
    public Perspective() { 
    super(); 
    } 
    
    public void createInitialLayout(IPageLayout layout) { 
    String editorArea = layout.getEditorArea(); 
    layout.setEditorAreaVisible(false); 
    layout.addStandaloneView( "com.ibm.rcp.applauncher.view.NativeView:native.app.sample.thunderbird", true, 
       IPageLayout.LEFT, 0.95f, editorArea); 
    } 
    }

    The com.ibm.rcp.applauncher.view.NativeView is the view that is shown in this perspective. This view is a placeholder for the application that is embedded. The way to inform the view of the application is through the secondary id, native.app.sample.thunderbird. This secondary id is the name of the Native application definition that you specify in the GtkNativeApplication extension. You specify one view for each perspective when using the NativeView.

  4. Update the plugin.xml file as show:
    <?xml version="1.0" encoding="UTF-8"?> 
    <?eclipse version="3.2"?> 
    <plugin> 
    <extension point="org.eclipse.ui.perspectives"> 
    <perspective name="Thunderbird"
    class="nativeSamplePerspective.Perspective" <!-- This is the fully qualified name of the perspective 
       implementation class above. -->
    id="nativeSamplePerspective">
    </perspective> 
    </extension> 
    
    <extension id="main_view" point="com.ibm.eswe.workbench.WctApplication"> 
    <Application DisplayName="Thunderbird" <!-- This  shows up under the Open menu of the workbench -->
    PerspectiveId="nativeSamplePerspective"> </Application> 
    </extension> 
    
    <extension point="com.ibm.rcp.applauncher.gtk.linux.x86.GtkNativeApplication"> 
    <NativeApplicationDefinition 
    appname="/opt/thunderbird/thunderbird" <!-- this executable will be launched upon the opening of the NativeView --> 
    name="native.app.sample.thunderbird" <!-- This is the secondary id to pass with the view. -->
    timeout="15" 
    close_perspective="true" 
    title="Thunderbird"/> <!-- The NativeView service  finds an open window that has this title as a substring. --> 
    </extension> 
    
    </plugin> 
  5. Build and export the project to launch as part of Lotus Expeditor.
Launching a native application for a specific attachment or specific file types
The following steps illustrate how to launch and embed native applications of various file types.
  1. Make sure that there is an Eclipse extension provided for the GtkNativeApplication extension point as part of the native application that handles the file types.
    <extension point="com.ibm.rcp.applauncher.gtk.linux.x86.GtkNativeApplication">
    <NativeApplicationDefinition
    appname="acroread"
    name="native.app.sample.acroread"
    timeout="30"
    close_perspective="true"
    prompt_on_close_window=”false”
    file_extensions=”pdf”
    title="Acrobat Reader"/> 
    </extension>
  2. Update the OS level applications launcher for the file types you would like Lotus Expeditor to handle.
    On SLED 10, the desktop menu specification allows searching several directories for .desktop files. The following directories are searched on SUSE Linux:
    • /opt/kde3/share/applications/
    • /opt/gnome/share/applications/
    • /usr/share/applications/
    The following code sample illustrates how to modify the .desktop files on your platform for Acrobat Reader. You can find the acroread.desktop file in the /usr/share/applications/ directory. You must modify the value of the Exec key, which contains a default key/value such as this value.
    Exec=acroread %U

    Modify this value to point to an executable script (rcplauncher_lanunchNativeAppCommand.sh) that you create in the following step.

  3. You can place the file anywhere. Ensure that its executable permissions are set properly.
    #!/bin/bash
    #filename: rcplauncher_lanunchNativeAppCommand.sh
    
    unset LD_PRELOAD
    unset LD_LIBPATH
    echo $@
    exec /opt/ibm/lotus/Expeditor/rcp/rcplauncher -config notes -maxargcnt 7 -
    com.ibm.rcp.applauncher.gtk.linux.x86#launchNativeApp "$@"
  4. Update the value of the Exec key to point to the script you created in the previous step; in this example, the rcplauncher_lanunchNativeAppCommand.sh script in the /opt directory.
    Exec=/opt/rcplauncher_lanunchNativeAppCommand.sh %U
  5. Save the acroread.desktop.

After completing the procedure, anytime a file with a .pdf extension needs to be launched, it is routed to the rcplauncher with its location as an argument to the launcher. This information, in turn, is passed to the launchNativeApp command handler. This command searches the Eclipse registry for the GtkNativeApplication extension to locate the supported Native application for the file being passed. If a supported GtkNativeApplication is found, it is launched and then opened inside an instance of NativeView as a-tab.

A new tab is created for each invocation of this command. Creating a tab for each command invocation is suitable for applications that support Single Document Interface. There are some applications, however, that support the Multiple Document Interface (for example, using a single window to display all documents; the application manages the documents layout.)

For detailed information on GtkNativeApplication, refer to its extension point schema. Documentation about Lotus Expeditor extension points schemas is provided as Javadoc with the Lotus Expeditor Toolkit.

Invoking a silent installation on Microsoft Windows

You can set up the Lotus Expeditor Client installation program to run silently if you do not want users to interact with the installation wizard on Windows. Additionally, using a transform file on Microsoft Windows, you can customize the installation properties.

During silent installation, if a previous version of Lotus Expeditor is detected, it is upgraded.

To install silently with default options:

  1. From a command line, change to the install/ directory on the CD.
  2. Run the following command:
    On Windows:
    <setup executable> /s /v"/qn LICENSEACCEPTED=true"

    For example, setupwin32.exe /s /v"/qn LICENSEACCEPTED=true".

To install silently with custom options:

  1. Create a transform file on Microsoft Windows using the steps provided in Creating and using transform files.
  2. Modify the transform file with the customized values for your installation.
  3. From a command line, change to the install/ directory on the installation CD.
  4. Run the following command:
    <setup executable> /s /v"/qn TRANSFORMS=<fully qualified path to transform file>"
    For example, setupwin32.exe /s /v"/qn TRANSFORMS=c:\temp\mytransform.mst"
    Note: When using a transform file to install silently, you must set the following property in your transform file for the installation to proceed:
    LICENSEACCEPTED=true
Note: Alternatively, public properties can be passed in using a command line (subject to command line length restrictions).

You can add optional components to the install during an initial install, modify, or upgrade by passing in the property ADDFEATURES. The optional components available to install are Composite Application Editor, Sametime®, and Samples. The ids for these components will need to be used to pass into the ADDFEATURES property. Those are: xpd.aaf, xpd.sametime, and xpd.samples respectively.

For example, setupwin32.exe /s /v"/qn ADDFEATURES=xpd.aaf,xpd.samples"

If you want to install all components during an install, modify or upgrade, you can specify ALL as the value for ADDFEATURES. For example, ADDFEATURES="ALL"

You can also remove optional components from the install during a modify or upgrade operation by passing in the property, REMOVEFEATURES.

For example, setupwin32.exe /s /v"/qn REMOVEFEATURES=xpd.samples"

Customizing installation options

You can customize the Lotus Expeditor Client installation to set up various settings for the platform, including security settings, portal management settings, and enterprise management settings.

To customize the installation on Microsoft Windows, you can create a transform file. To customize the installation on Linux, you can create an options file.

Creating and using transform files

Transform files are the standard way to make customizations to a Windows installer's behavior. Using a transform file, you can customize initial settings for the Lotus Expeditor Client installation.

Creating a transform file

To create a transform file, use the InstallShield Tuner utility. It is available to install from the Lotus Expeditor Client CD, in the /desktop/tuner/ directory.

After the utility is installed, load the utility and when prompted, identify the provided Lotus Expeditor .itw configuration file. It is located in the desktop/ directory of the Lotus Expeditor Client CD. Then follow these steps:

  1. Select the option to create a new transform.
  2. Browse to locate and select the Lotus Expeditor .msi installation package to be customized. It is also located in the desktop/ directory of the Lotus Expeditor Client CD.
  3. Provide a project name and location for the transform.
  4. Create the transform.
The InstallShield Tuner utility creates a transform file with the options that you specify. The file is named <project name>.mst.
Using a transform file

To use the transform file, you must initiate the installation from a command line with the following option specified:

msiexec /i Expeditor.msi /qn TRANSFORMS=<fully qualified path to transform file>"
For example, msiexec /i "Expeditor.msi" /qn TRANSFORMS="c:\temp\mytransform.mst"
Note: Options and properties defined on the command line take precedence over those defined in transform files.
Options available for initial installation
LICENSEACCEPTED
Use this property to control whether the license has been accepted for the installation (true or false). The default value is false. This property is available to configure in the Setup Properties table located under Application Configuration.
USEDEVICEMANAGEMENT
Use this option to determine if the Enterprise Management Agent is utilized (true or false). The default value is false.
The following properties are used to configure the Enterprise Management Agent user name, password, and server URL:
  • DEVICEMANAGEMENTUSERNAME
  • DEVICEMANAGEMENTUSERPASSWORD
  • DEVICEMANAGEMENTSERVERURL - the default value is http://<DMserver_address>/dmserver/OMADMServletAuthRequired.

DEVICEMANAGEMENTUSERNAME and DEVICEMANAGEMENTUSERPASSWORD are not populated with an initial value, and therefore, to specify a value they need to be added to the Setup Properties table located under Application Configuration.

The following properties configure the use of Portal management (true or false) as well as the Portal server URL:
  • USEPORTALMANAGEMENT
  • PORTALCONFIGURATIONSERVERURL

PORTALCONFIGURATIONSERVERURL is not populated with an initial value, and therefore, to specify a value it needs to be added to the Setup Properties table located under Application Configuration.

SECURITYALLOWCONFIGURATION
Use this property to allow users the ability to configure whether they want to allow a password prompt (true or false). The default value is true.

This property is available to configure in the Setup Properties table located under Application Configuration.

SECURITYPASSWORDPROMPT
Use this property to enable the platform to prompt for a password at startup (true or false). The default value is true.

This property is available to configure in the Setup Properties table located under Application Configuration.

INSTALLDIR
Use this property to specify the install location of the product. Specify a valid directory into which the product is be installed. The defaults is C:\Program Files\IBM\Lotus\Expeditor.
Note: The use of square brackets [ ] in path variables is not supported.

This property, which appears as "Default Destination Path" is available to configure in the Product Properties table located under Organization.

UDATESITELIST
Use this property to override the update site list during initial provisioning. You must specify the format as follows: UPDATESITELIST="site_1|site_2|…|site_n".

This property is available to configure in the Setup Properties table located under Application Configuration.

RCPDATA
Use this property to override the rcp.data value specified in the rcplauncher.properties file during initial provisioning.

This property is not populated with an initial value, and therefore, to specify a value it needs to be added to the Setup Properties table located under Application Configuration.

RCPLOCALE
Use this property to override the com.ibm.rcp.locale property in the rcplauncher.properties file during initial provisioning. The value must be in language_REGION format. If not specified, no default value is used, and no corresponding value is written to rcplauncher.properties, allowing the launcher to detect and use the default system locale.

This property is not populated with an initial value, and therefore, to specify a value it needs to be added to the Setup Properties table located under Application Configuration.

Options available for upgrade

Use LICENSEACCEPTED to control whether the license has been accepted for the installation (true or false). The default value is false.

Note: Other initial install options are ignored during upgrade.

Creating and using options files on Linux

Linux RPM-based installations typically have no install-time customization ability. For Lotus Expeditor Client, however, an install.options file can be used to customize some of the initial settings for the platform.

Note: The install.options file cannot be used to change the installation destination directory for the platform. For Linux RPM installations, the "--prefix <install destination>" command-line options must be used.
Creating an install.options file

A file named install.options must be created in /etc/ibm/expeditor/ before the RPM is installed. This file is a java.io.Properties format file (that is, ASCII characters only with Unicode escapes), and single quotation marks are required around the value (for example, <variable>='<value>'). Use any available text editor on your Linux system to create this file.

Using an install.options file

The install.options file must be placed in the /etc/ibm/expeditor/ directory before the Lotus Expeditor Client RPM installation is started.

Options available for initial installation
LICENSEACCEPTED
Use this option to control whether the license has been accepted for the installation (true or false). The default value is false.
USEDEVICEMANAGEMENT
Use this option to determine if the Enterprise Management Agent is used (true or false). The default value is false.
The following options are used to configure the Enterprise Management Agent user name, password, and server URL:
  • DEVICEMANAGEMENTUSERNAME
  • DEVICEMANAGEMENTUSERPASSWORD
  • DEVICEMANAGEMENTSERVERURL - the default value is http://<DMserver_address>/dmserver/OMADMServletAuthRequired
The following options configure the use of WebSphere Portal management (true or false) as well as the WebSphere Portal Server URL:
  • USEPORTALMANAGEMENT
  • PORTALCONFIGURATIONSERVERURL
SECURITYALLOWCONFIGURATION
Use this option to allow users the ability to configure whether they want to allow a password prompt (true or false). The default value is true.
SECURITYPASSWORDPROMPT
Use this option to enable the platform to prompt for a password at startup (true or false). The default value is true.
INSTALLDIR
Use this option to specify the installation location of the product. Specify a valid directory into which the product is to be installed. The default is C:\Program Files\IBM\Lotus\Expeditor.
Note: The use of square brackets [] in path variables is not supported.
UDATESITELIST
Use this option to override the update site list during initial provisioning. You must specify the format as follows: UPDATESITELIST="site_1|site_2|…|site_n".
RCPDATA
Use this option to override the rcp.data value specified in the rcplauncher.properties file during initial provisioning.
RCPLOCALE
Use this option to override the com.ibm.rcp.locale property in the rcplauncher.properties file during initial provisioning. The value must be in language_REGION format. If not specified, no default value is used, and no corresponding value is written to rcplauncher.properties, allowing the launcher to detect and use the default system locale.
Note: The following options are not populated with an initial value, and therefore, if you do not specify a value, these optionsdo not display in the list of properties:
  • DEVICEMANAGEMENTUSERNAME
  • DEVICEMANAGEMENTUSERPASSWORD
  • PORTALCONFIGURATIONSERVERURL
  • RCPDATA
  • RCPLOCALE
Options available for upgrade

Use LICENSEACCEPTED to control whether the license has been accepted for the installation (true or false). The default value is false.

Note: Other initial install options are ignored during upgrade.

Uninstalling the Lotus Expeditor Client

Use the steps in this section to uninstall the Lotus Expeditor Client.

Note: Before you uninstall, ensure that the Lotus Expeditor Client is not running.
On Microsoft Windows:
  1. Launch Add/Remove Programs by selecting Settings > Control Panel > Add/Remove Programs.
  2. Select Lotus Expeditor Client and click Remove.

On Microsoft Windows Vista with UAC enabled:

The uninstallation must be run with full administrative access. To uninstall, follow these steps:
  1. Open a command prompt as administrator: From the Start menu, browse to the command prompt, and right-click and select Run as Administrator.
  2. From the command prompt, run the following command:
    <client destination>\uninstall.bat
  3. Accept any prompts to allow access.

On Linux:

  • If using RPM packaging, run:
    rpm -ev expeditor
  • If using Debian packaging, to remove, run:
    sudo dpkg -r expeditor 
    or, to purge, run:
    sudo dpkg -P expeditor 
Notes:
  • The uninstallation wizard does not provide the option to remove user data. You must manually remove it. Refer to Removing user-specific data.
  • Uninstallation can be performed only in the same language in which the installation was performed.

Silently uninstalling the Lotus Expeditor Client on Windows

To silently remove Lotus Expeditor, run the following command:
"<client destination>\uninstall.bat" -silent

Removing user-specific data

After removing Lotus Expeditor from a user system, the user-specific data (the workspace) is left behind. The workspace from a previous installation of Lotus Expeditor can be reused if Lotus Expeditor Client is reinstalled on the system. If you do not want the user-specific data on the system you must manually remove it.

To remove the data, delete the workspace location. The default locations are stored in the rcp.data value in rcplauncher.properties.
If you have changed this value from the default location, delete the overridden location.
Note: You must complete these steps for each account that has launched the product because a workspace has been created for each user.

Customizing basic installation

The Lotus Expeditor Client installation process consists of two steps: installation of core platform files and provisioning of additional components.

The set of components to be provisioned is defined within a provisioning manifest, which is processed by the installer and platform provisioning system.

On Microsoft Windows, the file must be named install.xml and must be located in a deploy/ directory located in the same location as the installer executable.

For Microsoft Windows customization, the default install.xml is located on the Lotus Expeditor Client CD. You cannot modify this file because it resides on the CD. If the contents of the install/ directoryare copied to a read-write file system (as in the case of a Web download scenario), then the install.xml can be modified to include a customized set of components.

On Linux, the provisioning manifest is, by default, located inside the installation package. The default manifest, however, can be overridden by placing an override manifest in /etc/ibm/expeditor/install.xml.

For Linux customization, the default install.xml must be obtained from within the Linux install package. To do this task, perform the following instructions (only one method is necessary, as the install.xml is the same in both RPM and Debian packages):

To customize the platform installation from the RPM package:

  1. Run mkdir /tmp/test.
  2. Change the directory to /tmp/test.
  3. Run rpm2cpio <fully qualified path to .rpm file> | cpio -idv.
  4. Copy the /tmp/test/opt/ibm/lotus/Expeditor/rcp/deploy/install.xml file to /etc/ibm/expeditor/install.xml.
  5. After the install.xml file is retrieved, the /tmp/test directory can be deleted.
  6. Modify /etc/ibm/expeditor/install.xml as you wish to customize the platform installation.

To customize the platform installation from the Debian package::

  1. Run mkdir /tmp/test.
  2. Change the directory to /tmp/test.
  3. Run dpkg-deb -x <fully qualified path to.deb file>.
  4. Copy the /tmp/test/opt/ibm/lotus/Expeditor/rcp/deploy/install.xml file to /etc/ibm/expeditor/install.xml.
  5. After the install.xml file is retrieved, the /tmp/test directory can be deleted.
  6. Modify /etc/ibm/expeditor/install.xml as you like to customize the platform installation.
Note: Modifying these provisioning manifests from their shipped states can result in an invalid platform installation.

During the installation process, the provisioning manifest is processed and copied to <product destination>/rcp/deploy/install.xml.

The location of this file is then passed to the platform provisioning component to begin the provisioning process.
Note: The same methods described above can be used to customize the plugin_customization.ini, jvm.properties, and keystore files.

For more information about using the provisioning manifest and its syntax, see Using the provisioning manifest.

Using the validation tool to verify a modified installation kit

The validation tool allows deployers to test installation kit changes before rolling out new installations of Lotus Expeditor. If the installation kit is modified to remove or add features in the platform it is recommended that the validation tool is run against the modified install kit to verify that the changes are valid for installation.

The validation tool catches common errors that occur when modifying the installation kit, such as invalid syntax, version mismatches, and missing resources. The tool tests three main areas to ensure that the installation manifest and update site are valid for install:
  • Manifest Validation - ensures that the installation manifest has valid XML and provisioning syntax.
    • Tests the XML for valid syntax
    • Tests the XML against a provisioning schema to ensure that the correct required attributes and fields are set
    • Tests certain attributes in the XML to ensure that they are valid for provisioning
  • Update Site Validation - ensures that the update site is valid and not missing any features or plug-ins
    • Loads the plug-ins into the OSGi resolver to ensure that there are no missing bundles
    • Tests all feature and plug-in references in the site.xml to validate that they are included in the update site
  • Manifest Features on Update Site Validation - ensures that the exact manifest referenced features can be found on the update site.
    • Compares the install manifest against the update site to validate that all referenced features are found and meet the specified match rule

The tool can be found on the CD image in the utils directory. Copy the validation_tool.zip from the CD to a temporary location on the disk and unzip.

Overriding the list of update sites for provisioning

You can override the list of update sites used to search for features to install.

To override the list of update sites for provisioning, select instructions for your particular operating system:
  • Windows only
    On Windows systems, the IBM Lotus Expeditor installer accesses an update site in a location relative to the setup executable (setup_executable/updateSite.zip) to provision the platform components. You can override the update sites searched during installation from the command line:
    1. From the command line, change to the desktop/ directory on the CD.
    2. Enter the following command using the UPDATESITELIST property as follows:
      setupwin32.exe /v″UPDATESITELIST=\″site_1^|site_2^|...^|site_n\″″
    Each update site specified must be a valid URL. Also, if the site specified contains the text ${installer.root}, the text is replaced by a file URL value that contains the location from where the installer launched.
    Note: Note: If you override the UPDATESITELIST and do not include the default product update site (jar:${installer.root}/updateSite.zip!/) in the list, then you will not have access to install the product's default set of features.
  • Linux only
    On Linux systems, the IBM Lotus Expeditor installer does not require an external site to provision the platform components because components are included within the RPM or Debian package. However, if any desired, additional components (referenced in the install manifest) are located externally, you can place them in /etc/ibm/expeditor/updateSite/, which is the default external update site list. If you want to override the update sites searched during installation, follow these steps:
    1. Prior to installing the product, create an /etc/ibm/expeditor/install.options file containing the following property:
      UPDATESITELIST='site_1|site_2|...|site_n'
    2. Run the RPM or Debian package installation.
    Note: In contrast to Windows, processing of the ${installer.root} property is not done for Linux.

    Each update site specified must be a valid URL.

Note: This override is only used for installation or upgrade of the Expeditor Client platform for the current user. To have a custom list of update sites available for other users before they launch, you must modify the com.ibm.rcp.provisioning.updateSiteList property in <install dir>/rcp/plugin_customization.ini. For more information, see Changing deployment preferences.

Installing the Lotus Expeditor Client for shared launching from a network drive

The Lotus Expeditor Client can be installed onto a drive that can be shared as a network drive. This enables a single install location on the network to be shared among many users.

The installation must adhere to the following restrictions:
  • The install can be used only by clients running on the same operating system family as the install application. In other words, if you are using Windows to install the Lotus Expeditor Client, then the installation can be used only by users on Windows systems. If you are using Linux to install the Lotus Expeditor Client, then the installation can be used only by users on Linux systems.
  • The install can be made either to a local drive that is later shared with other users, or it can be installed to a shared drive. On Windows, when installing to a shared drive, the shared drive must be mounted as a drive letter. UNC mounted destinations are not supported.

    Installing to a shared drive mounted with the Linux Samba client is not supported. If you are using Linux and attempt to use the Samba client to mount a shared folder and install into that shared folder, you will receive errors indicating that files could not be renamed. This is a known issue with this configuration. An alternative would be to use NFS for mounting shared folders.

To enable use of a network shared installation, the configuration related properties files do not contain absolute directory and file location references, but use the following variables that are resolved and replaced during the launch process:
${rcp.data}
Refers to the workspace directory. See Overriding the workspace directory location for more information.
${rcp.home}
Refers to the platform install location. The value for rcp.home is set by the launcher to be the parent directory of the directory containing the launcher.

On Windows, the default install location is C:\Program Files\IBM\Lotus\Expeditor. The Expeditor directory contains a directory rcp, in which resides the launcher, rcplauncher.exe. rcp.home is set to C:\Program Files\IBM\Lotus\Expeditor.

On Linux, the default install location is /opt/ibm/lotus/Expeditor. The Expeditor directory contains a directory rcp, in which resides the launcher, rcplauncher. rcp.home is set to the /opt/ibm/lotus/Expeditor directory.

The default install sites – rcp, and shared – reside under the rcp.home directory. Install sites cannot be added unless they are also referenced as children of the rcp.home root.

Overriding the workspace directory location

You can override the default workspace directory location with a location that you specify.

On Windows, the default workspace location is <APPDATA>\Lotus\XPD.

On Linux, the default workspace location is <HOME>/Lotus/XPD where

<APPDATA> and <HOME> are system environment variables. In default Windows installations, the workspace directory would resolve to Documents and Settings\<userid>\Application Data\Lotus\XPD. In default Linux installations, it would resolve to /home/<userid>/Lotus/XPD.
Note: On installations upgraded from IBM Lotus Expeditor 6.1.0, the workspace location will be preserved from the 6.1.0 installation. On both Windows and Linux systems, this location is <user home directory>/IBM/RCP/<rcp_install_ID>/<user name>.

When specifying the new directory location, the location must be accessible to all users that will be using the workspace. If each user will have their own unique workspace, the workspace directory location should be specified containing environment variables that will be replaced on launch and will therefore resolve to a unique location for each user. If a common workspace will be serially shared by all users logging onto the system. The workspace directory must be in a location accessible to all users, with full permissions on the common location.

  • On Windows:

    Use the RCPDATA property to override the workspace directory location. This can be done with a transform file, or on the command line as follows:

    setupwin32.exe/v"RCPDATA=\"<desired workspace location>\""

    If a workspace location is not specified, ${env.APPDATA}/Lotus/XPD is used.

    Note: If the command line override is used, logging is not automatically enabled. Add /liwemo "<install log location>" to enable logging. For example:
    setupwin32.exe/v"/liwemo \%TEMP%/rcp_install.log\" RCPDATA=\"${env.APPDATA}/Lotus/XPD\""
  • On Linux:
    Use the RCPDATA property in the install.options file to override the workspace directory location as follows:
    1. Before installing, create /etc/ibm/expeditor/install.options.
    2. Add RCPDATA='<desired workspace location>' to the install.options file.
    3. Save the install.options file.
    4. Run the installer
    If a workspace location is not specified, ${env.HOME}/Lotus/XPD is used.

Features that were installed into one workspace cannot be uninstalled from a different workspace. For example, when you initially launch IBM Lotus Expeditor using the default workspace, a set of features are installed and provisioned for you. If you later launch with a different workspace using the -data command-line rcplauncher option or the rcp.data property in the rcplauncher.properties file, the features that were installed into the default workspace cannot be uninstalled from the new workspace. If you attempt to uninstall these features, they will not be uninstalled and errors will be written to the error log.

Locating the Lotus Expeditor Client launcher program

IBM Lotus Expeditor creates registry keys on Windows and files on Linux to allow for the location of the Lotus Expeditor Client launcher.

On Windows, the registry path depends on the install attributes. If an administrator has installed the Lotus Expeditor platform, the registry path is HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Lotus\Expeditor. Otherwise, the path is HKEY_CURRENT_USER\SOFTWARE\IBM\Lotus\Expeditor. Within this registry folder, there will be another key created based on the product.name of the installed product. Within this new key, the string value launcher will be created to contain the path of the rcplauncher.exe program. When searching the registry, first check HKEY_CURRENT_USER. If the keys are not found, then check HKEY_LOCAL_MACHINE.

On Linux, a configuration file will be created to contain the location of the launcher. If an administrator has installed the IBM Lotus Expeditor platform, the configuration file will be created in /etc/ibm/lotus/expeditor directory. Otherwise, the path is $HOME/user/.expeditor. Within the directory, a file named Expeditor.cfg will be created to contain the path to the rcplauncher program. As an example, the file contents would be the following line:
launcher=/opt/ibm/lotus/Expeditor/rcp/rcplauncher
IBM Lotus Expeditor uses the product.name Expeditor in its branding feature to create the registry entries as described above. Installations that have replaced the IBM Lotus Expeditor branding feature with another branding feature might change the product.name, and as a result, the file name containing the launcher information will be different.

Understanding Microsoft Windows Vista installations

Read this section for an understanding of User Account Control and the security model associated with Microsoft Windows Vista.

Microsoft Windows Vista User Access Control

Microsoft Windows Vista implements a new security model referred to as User Account Control (UAC), which when enabled limits access to protected directories and sections of the registry. These limits are imposed on standard users and members of the Administrator group. Members of the Administrator group are prompted for access each time they attempt to access the resource. Likewise, users must provide the password of a member of the Administrators group each time they want to access the resource. An additional limitation in both scenarios is the dialog prompting for consent or the password has a two-minute timeout after which it will disappear and interrupt software installations or deny access to the requested resource.

UAC also implements resource virtualization for the protected directories and sections of the registry. An example of resource virtualization is a standard user trying to create a file in C:\Program Files\<MyApp>\<MyFiles> will not receive an access error; rather the file will be created in C:\Users\<user>AppData\Local\VirtualStore\Program Files\<MyApp>\<MyFiles>. If UAC is disabled, resource virtualization is disabled.

IBM Lotus Expeditor can be installed with UAC enabled or disabled, though it is recommended to keep User Account Control enabled to help secure the system.

Administering the platform on Windows Vista

With the advent of the new Microsoft security model in Vista, the platform is inherently more secure as all users are limited to standard user access rights. Administrative users can request elevated privileges when they need to perform administrative functions. For IBM Lotus Expeditor, you must launch the platform requesting the elevated privileges when installing additional features, multicultural language support, or making other configuration changes which might affect all users. This will allow proper creation of new application icons on the Windows Desktop or in the Windows Start Menu and proper creation of global registry keys. The platform should not be run with elevated privileges excessively as some functions such as launching external browsers will not behave as expected. To run the platform with elevated privileges:
  1. Log in to Vista as a user part of the Administrators group
  2. Right-click on the IBM Lotus Expeditor icon (typically on the desktop or in the Start Menu)
  3. Select Run as administrator
  4. Respond to the Vista prompt for consent to run the program with elevated privileges

Launching the Lotus Expeditor Client on the desktop

This topic describes how to start the Lotus Expeditor Client, how the daemon process works, and how an existing process is joined if a new personality is requested.

See Configuring the platform launcher for details on available commands.

Starting the Lotus Expeditor Client

During installation of the Lotus Expeditor Client a new desktop icon titled Expeditor 6.2 will be created, which can be used to start the Lotus Expeditor Client.

Additionally, you can launch the Lotus Expeditor Client from the command line. By default, no arguments are required, but additional arguments can be provided. For a list of the supported command line arguments, see Configuring the platform launcher. On Linux systems, if the Lotus Expeditor Client has been installed to the default directory, use the following command to launch the client:
/opt/ibm/lotus/Expeditor/rcp/rcplauncher
On Windows systems, if the Lotus Expeditor Client has been installed to the default directory, use the following command to launch the client:
C:\Program Files\ibm\Lotus\Expeditor\rcp\rcplauncher.exe

Using the RCP daemon and Dcommands

This section describes how the daemon works and how and existing process is joined when using a new personality.

When the Lotus Expeditor is running, you can execute commands from outside of the Expeditor user interface through the use of an Expeditor daemon. These commands are treated as additional arguments to the main rcplauncher executable. When an rcplauncher process is invoked with these additional commands and an Lotus Expeditor is already running, the rcplauncher process will use the daemon and inform the Lotus Expeditor to execute these commands instead of bringing up another full instance of the Lotus Expeditor and then invoking the commands within the new environment.

You can invoke additional personalities that will join the currently running Lotus Expeditor environment rather than creating another full instance. This is done using the daemon discussed in the previous section and is done to help conserve system resources.

As an example, let's examine an office productivity suite of applications containing a word processor and a spreadsheet application. Each of these applications may be separate desktop icons, both of which use the rcplauncher executable but provide a different personality via the -personality parameter. Initially, the user needs to work on some spreadsheet data to generate the necessary data for a letter to be written so the user launches the spreadsheet. When nearing completion of the spreadsheet work, the user decides to begin work on the letter to ensure the layout will lend well to the data to be included, so the user now launches the word processing application. The rcplauncher process will recognize the Lotus Expeditor is already running with the spreadsheet personality and will not invoke another full instance. Instead, the rcplauncher process will use the daemon and have the currently running Lotus Expeditor open a new window, using the new word processing personality.

Understanding workspace creation

This section provides information about the creation and the contents of the Lotus Expeditor workspace.

The workspace is used to store data in between platform launches, and also contains the configuration area for the platform. The configuration area stores information related to the applications and features installed in the platform.

The initial workspace is created during the initial install. The install program first installs a minimal set of features and plug-ins into the installation directory. These features are then used to launch the platform for the first time. During this first time launch, the initial workspace is created. The initial workspace and configuration are created based on the contents of the provisioning manifest. All of the features defined in the provisioning manifest are installed and enabled, and the resulting configuration information is stored in the workspace.

In multiple user environments, when additional workspaces are created following the initial workspace creation, the features installed during the initial workspace creation are used. With respect to the feature life cycle, this means that the features are not installed again but are only enabled. If you are providing your own features and they contain install handlers, they should perform most of the required work on the configure and unconfigure operations. For more information, see Understanding feature life cycle.

On Windows, if the platform installation is performed using the System account, the initial workspace will be located in <install dir>\rcp\systemdata. If the platform installation is performed by an administrator, the initial workspace will be located, by default, in %APPDATA%\Lotus\XPD. On Linux, the initial workspace will always be located in <install dir>/rcp/systemdata.

Two system properties defined in the .config/rcpinstall.properties file in the workspace provide specific information for the launcher to determine what happens when launching the platform.
rcp.install.id
Associates a version of the workspace with an installed version of the platform. Upon launch, the value of rcp.install.id is compared with the value of the rcp.install.id in the <install_dir>/rcp/rcplauncher.properties file. If these values are different, it is assumed that the workspace does not match the installed platform. See Reusing an existing workspace for more information.
provisioning.manifest.version
Defines the version of the workspace configuration that is used. On launch, the value of the provisioning.manifest.version is compared with the value of the provisioning.manifest.version property in the <install_dir>/rcp/rcplauncher.properties file. If these values are different, then it is assumed that the provisioning manifest defined by the rcplauncher.properties file is more recent and needs to be applied to the workspace. The launcher than launches the platform using the ProvisioningApplication to perform the operations defined in the provisioning manifest. See Using the Provisioning application for more information.
As the platform definition contains features associated with specific locales, only those features that apply to the current locale will be enabled. For example, if you launch the platform using the German locale de, the only features that will be enabled are those without a specific locale filter and those features that contain the filter specifying de as a specific locale. In a multiple user scenario, you must first install all locale-related features prior to users creating a new workspace.

Reusing an existing workspace

This section details how existing workspaces are handled.

Workspaces will reused if the value of the rcp.install.id property in the rcpinstall.properties does not match the value of rcp.install.id property in the rcplauncher.properties.

This situation will generally occur if a workspace pre-exists on a system, and a new install of Lotus Expeditor occurs.

If the launcher determines that the workspace does not match the installed version of the platform based on the rcp.install.id property, the launcher will take the following actions:
  • The .config/platform.xml file will be copied to the workspace root and renamed to platform.xml.old.
  • The .config directory is backed up.
  • A new rcpinstall.properties will be created from the contents of the rcpinstall.properties supplied in the com.ibm.rcp.base plug-in.
  • The ProvisioningApplication will be launched to create a new workspace:
    • The ProvisioningApplication will read the provisioning manifest defined by the rcplauncher.properties file and will attempt to create a new workspace using the features already installed on the file system, just as if the workspace had not previously existed.
    • The ProvisioningApplication will read the platform.xml.old file that was created and will attempt to enable each of the features included in the user applications site.
    • The ProvisioningApplication will read the provisioning manifest and will attempt to enable each of the features included in the shared site.
    • The ProvisioningApplication will exit and the launcher will restart the installed platform.

Launching the Expeditor Client from a network drive

This topic describes how to start the Lotus Expeditor Client from a network drive.

When the Lotus Expeditor Client has been installed onto a shared network drive, no icons are created or available for users to do the initial launch of the Lotus Expeditor Client. The initial launch must be performed by locating the rcplauncher.exe (Windows) or rcplauncher (Linux) program, and starting the program.

For example, on Windows, if you have a network drive X: that contains the directory X:\Expeditor, switch to the X:\Expeditor\rcp directory, and start the rcplauncher.exe program. The workspace will be created in the normal location. As part of the initial creation of the workspace, icons will be added to the desktop to enable subsequent launches to occur using the shortcuts.

In the event that the drive letter that refers to the network drive changes after the initial launch, the created icons will no longer allow you to launch the Lotus Expeditor Client. If the drive letter is permanently changed, you can update the shortcut to change the launch location.

Launching the Lotus Expeditor using a non-standard workspace location

The default workspace location is computed based upon the operating system and the defined user.

If your workspace needs to be located at an alternative location, then start the launcher by specifying the "–data" parameter. For example, if you want to store a workspace on a USB drive connected to the system on drive G:, you can start the Lotus Expeditor by specifying rcplauncher –data G:\workspace. As this is a non-standard location for the workspace, you must either update the shortcut used to launch the Lotus Expeditor, or always use a console or Run menu to launch the Lotus Expeditor.

The same workspace can be referenced from different locations. For example, if the workspace is created on a USB-drive, it may attach as drive G: on one machine, and as D: on another. You will need to launch the Lotus Expeditor and specifically identify the data directory on each launch.

See Overriding the workspace directory location for more information.

Using links to composite applications

Use the CAI protocol to launch IBM Lotus Expeditor.

Composite Applications are URL-addressable with URLs beginning with CAI:///. This is known as the Composite Application Infrastructure (CAI) protocol. For the browser to understand the CAI protocol, CAI must be registered with the operating system. In Windows, the registry file cai_register.reg is part of the IBM Lotus Expeditor installation. IBM Lotus Expeditor contains information to be written to the Windows registry. In Linux, a similar technology, called GConf, is used to register CAI with the operating system. On a multi-user installation, the first time the Lotus Expeditor Client is run by each user, this registration (enablement) is executed.

Thereafter, when a URL beginning with CAI:/// is used in the browser, IBM Lotus Expeditor will open (if not already open) and load the specified composite application. See Creating client runtime images for more information. In addition, links starting with CAI:/// that are included inside document types which support links on the operating system will also be enabled, resulting in IBM Lotus Expeditor opening and loading the specified composite application.

Within IBM Lotus Expeditor, use the Edit > Copy As menu items (enabled when a composite application is opened) to create these CAI:/// links.

Installing the Expeditor Client on devices

You, as administrator, can assist users in installing Lotus Expeditor Client on to their supported devices. Before installing, ensure that all devices meet the recommended hardware and software requirements.

Complete system requirements for Lotus Expeditor can be found online at the following Web address: http://publib.boulder.ibm.com/infocenter/ledoc/v6r2/topic/com.ibm.help.ic.doc_3.1.1/expeditor_sysreqs_62.html.

Note that devices have different capabilities for running large application environments like Lotus Expeditor Client. You should pre-approve certain devices for users based on the application load you expect them to run.

Installing the core runtime

There are several ways to install the Lotus Expeditor Client core runtime on a supported device:
Installing from a CD
For Windows Mobile and Windows CE devices, you can provide a CD to end-users. The user must have a PC with ActiveSync installed and their device connected. The user runs a setup program on the PC which transfers a setup program to the device where installation continues. This method is only appropriate when there is a one-to-one relationship between the PC and device. Alternately, you could provide users with one of the following operating system-based Lotus Expeditor Client setup files using some other mechanism.
Setup file Device
device/install/wm/Expeditor-wm-setup.exe For Windows Mobile devices with touch screen
device/install/wmstd/Expeditor -wmstd-setup.exe For Windows Mobile devices without touch screen
device/install/wince/Expeditor-wince-setup.exe For Windows CE devices
Installing from a storage card
For Windows devices, you can provide users with a storage card containing one of the following operating system-based Lotus Expeditor Client cab files. Users can insert the storage card into their device and start the installer using File Explorer.
Setup file Device
Expeditor-wm-Core.CAB For Windows Mobile devices with touch screen
Expeditor-wmstd-Core.CAB For Windows Mobile devices without touch screen
Expeditor-wince-Core.CAB For Windows CE devices
Installing from a Web site
For Windows devices, you can set up a Web site that provides one of the following IBM Lotus Expeditor cab files. Users use Internet Explorer on the devices to browse to your Web site and download the appropriate setup file based on the device operating system. The setup file automatically runs and installation starts on the device.
Setup file Device
Expeditor-wm-Core.CAB For Windows Mobile devices with touch screen
Expeditor-wmstd-Core.CAB For Windows Mobile devices without touch screen
Expeditor-wince-Core.CAB For Windows CE devices
Note: For information about setting up your Web server, see Installing with the Network Client Installer.
Installing to a storage card:
You can use any of the installation methods above to install the Lotus Expeditor Client onto a storage card. If a storage card is present during installation, users are asked if they would like to install to it. When Lotus Expeditor Client is installed to a storage card, the workspace folder is also be placed on the storage card. If you are upgrading an existing installation of IBM Lotus Expeditor, and the new release is being installed on storage card, an existing workspace on the device is automatically migrated and moved to the storage card.

If you are migrating server-managed devices from IBM Lotus Expeditor 6.1, 6.1.1, or 6.1.2 to 6.2, after the migration, you should schedule an inventory job so that the management server will obtain updated information about the managed devices.

Installing Lotus Expeditor Client applications

There are several ways to install applications that run on the Lotus Expeditor Client onto devices. The method you chose depends on how your Clients will be managed. In all cases, it is your responsibility to provide the dependencies that an application needs to execute. These may include optional features from Lotus Expeditor Client for Devices.
Enterprise Managed Clients
You remotely manage devices. In this case, you use the Device Manager server console to package applications and create jobs that are automatically deployed to devices. See Managing with a Client Management server for more information. When an application is installed on a device, the user might see a pop-up message informing him to restart Lotus Expeditor Client. If a restart is required, the new application will be launchable after the restart. Otherwise, it is launchable immediately.
Remote Update Site
You can package applications in an update site that you make available on a Web server. See Creating an update site for more information. The user uses Application Manager to browse the remote update site and install applications from the site. Note that you must tell the user the specific Web address to browse.
Local Update Site
You can package applications in an update site that you make available on a storage card. The user inserts the storage card into the device and uses Application Manager to open the site and install applications. Note that for Windows devices, it is best to place update sites in a folder in the root of the storage card. The folder name can thus identify the update site and you can place more than one site on a card if needed. Sites should not be placed more than one folder deep.

For Windows Mobile devices, you can also place an update site in the My Documents folder on the device.

For WinCE devices, you can place an update site in any location on the device.

Note: When installing, updating, or uninstalling features, the user may be advised to restart the client runtime. This is generally not necessary when installing or updating features. However, uninstalls will not be effective until a restart occurs. If a user has a batch of uninstalls to perform, it is acceptable and more efficient to delay restarting until the last operation has been completed.

Migrating device data

Lotus Expeditor 6.2 supports the migration of user data which is stored in the workspace for 6.1, and the migration of both user data and user installed features for 6.1.1 and 6.1.2. However, prior to migration, you must manually uninstall the previous version.

  1. Connect your device with a PC with ActiveSync installed.
  2. Select Tools > Add/Remove Programs...
  3. Select the previous version of Lotus Expeditor.
  4. Click Remove.... This removes Lotus Expeditor from both your device and the PC. During uninstallation, you will be asked if you want to remove user setting data in the workspace. Click No if you want to keep your data and installed applications.
When you install Lotus Expeditor 6.2, your data and installed applications are migrated automatically.

Uninstalling

You can uninstall Lotus Expeditor Client from a device.

For Windows Mobile devices, if you installed using a setup.exe file, connect your device using ActiveSync and uninstall by running the setup.exe again, choosing to remove the Lotus Expeditor Client. If you installed from a storage card or Web site, then on your device select Start > Settings > System > Remove Programs. Select IBM Lotus Expeditor Client and tap Remove. Do not remove workspace data if you want to retain applications and device registration information.

For WinCE devices, if you installed using a setup.exe file, connect your device using ActiveSync and uninstall by running the setup.exe again, choosing to remove the Lotus Expeditor Client. If you installed from a storage card or Web site, then on your device select Start > Settings > Control Panel > Remove Programs. Select IBM Lotus Expeditor Client from the list of applications. Do not remove workspace data if you want to retain applications and device registration information.

Launching the Lotus Expeditor Client on devices

Review how to launch the Lotus Expeditor Client on Windows.

You do not need to directly launch the Lotus Expeditor Client on devices. Instead the Lotus Expeditor Client environment is started automatically when Lotus Expeditor Client applications are started. Note that the device cannot be remotely managed until an Lotus Expeditor Client application is started.

On Windows devices, the Lotus Expeditor Client remains running while any IBM Lotus Expeditor application is still open.

Installing with the Network Client Installer

Install the Network Client Installer so that users can remotely install the Lotus Expeditor Client, install the administrative components needed on your Portal server, and manage the Lotus Expeditor Client.

Note: Running command-line tools on Windows when configured for Hungarian: By default, when Windows is installed with Hungarian, the code page for the command prompt does not contain all the characters needed to display the Hungarian translations provided by the ArchiveCreator and SiteXMLUpdater tools. To use these tools, configure the command prompt by following these steps:
  1. Set the font to Lucinda Console.
  2. Set the code page to 1251 by running the command chcp 1251.
The text for the command-line tools provided by the Network Client Installer will now display correctly for Hungarian.

Installing the Network Client Installer

You can install the Network Client Installer on Lotus Expeditor Server, a standalone Web server, or a Portal server.

Before you begin you should understand the configuration of these servers to know which choices are best for you. You must also have an active account on the server.

To install the Network Client Installer, follow these steps:
  1. Insert the Lotus Expeditor Client CD into the CD-ROM drive.
    Note: For Portal clustered environments, install the Network Client Installer on only one Portal node in the cluster.
  2. If autorun is enabled on your system, a browser opens and displays a welcome page. If autorun is disabled, launch the file that is appropriate for your server operating system. The Network Client Installer is located on Lotus Expeditor Client CD in the \nci directory:
    Windows
    Launch \nci\install\setupwin32.exe
    Linux
    Launch \nci\install\setuplinux.sh
    AIX®
    Launch \nci\install\setupaix
    Linux on System p®
    Launch \nci\install\setupLinuxPPC.sh
  3. Follow the prompts to install the Network Client Installer.
    Note: Do not install the Network Client Installer in the multiple locales NL path. Valid characters for an installation directory are a-z, A-Z, 0-9, '-' (dash), '_' (underscore), and space (Windows only). Double-byte characters are not valid.

    If you choose to install on the Web server, you are prompted for the HTTP server document root location, the host name, and the URL to access the document root. You also have the choice to set the Device Management agent URL, as well as the Portal URL.

    If you choose to install on the Portal server, you are prompted for the Portal server home directory and the administrative user ID and password for the Portal server.

    Specify these settings as they pertain to your environment.
  4. For Portal clustered environments only, complete the following steps:
    1. Wait for the Deployment Manager to synchronize the Network Client Installer portlets to the other nodes in the cluster, or force synchronization.
    2. Activate the deployed portlets:
      UNIX
      Run the following command from the portal_server_root/config directory:

      ./WPSconfig.sh activate-portlets

      Windows
      Run the following command from the portal_server_root/config directory:

      WPSconfig.bat activate-portlets

  5. If you encounter an error during the installation process while installing the application template, you may have to install it manually. To do so, perform the following procedure:
    1. Launch the portal administration interface.
    2. Click Launch, then select Templates.
    3. Select the Template Library tab.
    4. Next, click Import... at the top left of the template area.
    5. Using the File selection dialog, select the file from the client CD. It is located in the nci/portal60/scripts directory, and named SampleAppTemplate.xml.
    6. Click OK to import the template.
The Network Client Installer is installed on the server and the server is ready for a client to install.
If you are installing on the Web server, the following Network Client Installer components are deployed on the server:
  • Lotus Expeditor Client update site
  • Lotus Expeditor Client installers
  • Download applet
  • The configuration files for the download applet that contain the host URL are updated with information gathered during the installation.
If you are installing on the Portal server, the following Network Client Installer components are deployed on the Portal server:
  • Portlets for Portal-administered client
  • Download portlet for client install
  • Application template
After the Network Client Installer is installed, the file layout is as follows:
/Expeditor
Contains the program root folder files.
/Expeditor/applet
Contains files for the download applet.
/Expeditor/install
Contains client installers and option files.
/Expeditor/updates
Contains the Eclipse update site.

Installing the Network Client Installer when using SSL with a self-signed test certificate

If you have configured your Web server or Portal server to use Secure Sockets Layer (SSL) and are using a self-signed test certificate, you must create a truststore and define it to the Network Client Installer before running the Network Client Installer to ensure that SSL communications will occur properly between the Network Client Installer install program and the Web server or Portal server.

If the Portal environment is HTTPS(10035) and 10038 port is disabled, before installing the Network Client Installer, you must validate that the entries in the <WP_HOME>/config/wpconfig.properties file are correct. For example:
XmlAccessPort=10035 
xmlAccessProtocol=https
Steps 1-5 below are specifically for IBM HTTP Server (IHS). If you are using a different HTTP server, consult that documentation for how to create a truststore, and execute Step 6 below.
  1. Extract the self-signed certificate from the IBM HTTP Server (IHS) if you are installing onto the Web server.
    Launch ikeyman from <ihs_home>\bin and open the keystore defined in the httpd.conf file under the Keyfile directive. For example, the keyfile C:/Program Files/IBM HTTP Server/selfCert/serverkey.kdb should look similar to the following:
    # Extract the public self-signed certificate key.
    # Click Personal Certificates in the menu and select the self signed certificate you are using.
    # Click Extract Certificate. Extract the certificate to a file:
    
            Data type
             Base64-encoded ASCII data
            Certificate file name
             cert.arm
            Location
             c:\program files\IBM HTTP Server\selfCert
    
    # Click OK.  
  2. Extract the self-signed certificate from Portal.
    Launch ikeyman from <ihs_home>\bin and open the keystore defined in for Portal. The keyfile C:\ibm\WebSphere\profiles\wp_profile\etc\DummyServerKeyFile.jks should look similar to the following:
    # Extract the public self-signed certificate key.
    # Click Personal Certificates in the menu and select the self signed certificate 
    # you are using
    # Click Extract Certificate. Extract the certificate to a file:
    
            Data type
             Base64-encoded ASCII data
            Certificate file name 			    
             cert.arm
            Location
             C:\ibm\WebSphere\profiles\wp_profile\etc
    
    # Click OK. 
  3. Create a new keystore.
    Launch ikeyman from <ihs_home>\bin
    # Click Key Database File > New from the iKeyman menu.
    # Enter the following settings:
    
    Key database type
     JKS
    File name
     key.jks
    Location
     c:\testKeyStore
    
    # Click OK.
    # Set the password of your choice at the password prompt and confirm the password. 
  4. Import the certificate from the IBM HTTP Server.
    # Click Signer Certificates from the list and click Add. This action imports the 
    # public certificate previously extracted from the HTTP server keystore file.
    
    Data type
     Base64-encoded ASCII data
    Certificate file name
     cert.arm
    Location
     c:\program files\IBM Http Server\selfcert
    
    # Click OK. You are prompted for a label name that represents the trusted signer public certificate.
    # Enter a label for the certificate: IHS Self Signed certificate
  5. Import the certificate from the Portal Server.
    Launch ikeyman from c:\Program Files\IBM Http Server\bin  	
    
    Open the keystore defined in for portal 	
    Keyfile C:\ibm\WebSphere\profiles\wp_profile\etc\DummyServerKeyFile.jks  		
    
    # Extract the public self-signed certificate key.  		
    # Click Personal Certificates in the menu and select the WASplugin certificate that you just created.
    # Click Extract Certificate. Extract the certificate to a file:  			
      
      Data type 			    
       Base64-encoded ASCII data 			
      Certificate file name 			    
       cert.arm 			
      Location 			    
       C:\ibm\WebSphere\profiles\wp_profile\etc  		
    
    # Click OK.
  6. Create an appropriate SP file.
    Using an editor, create a text file with the same name as the Network Client Installer install launcher, but with the extension .sp:
    Windows:
    setupwin32.sp
    Linux:
    setuplinux.sp
    AIX:
    setupaix.sp
    Linux on System p:
    setupLinuxPPC.sp
    Add these lines:
    javax.net.ssl.trustStore=C:\testKeyStore\key.jks
    javax.net.ssl.trustStorePassword=<your keystore password>
    javax.net.ssl.trustStoreType=jks
    When you launch the installer, it will now communicate correctly using SSL with the self-signed certificates.
    Since the following command is necessary to successfully install the Network Client Installer in a Portal SSL environment where port 10038 is disabled, then that information should be communicated to your users.
    ./setupLinuxPPC.sh -is:javaconsole -V NCI_PORTAL_HOME_URL_PORT=10035 -V NCI_PORTAL_HOME_URL_PROTOCOL=https

Notifying users on how to install from the Web using Windows and Linux

As administrator, you need to inform your users on how to install the Lotus Expeditor Client from the Web using the download applet on Windows and Linux.

Your users should be informed of the following steps:
  1. Provide users with the URL of your customized installation Web site. Use the sample HTML template provided and customize it for your environment. The default is http://<server name>/Expeditor/applet/index.html.
  2. Advise Linux users to start their browser with root privileges so that the download applet can launch the Lotus Expeditor Client installer with the required root privileges.
    • To start the browser with root privileges, run the following command:
      sudo firefox & 
      or
      su - root -c "firefox &"
      Note: Using "&" is optional and simply specifies that the command should run in the background, which enables users to continue to use the terminal window to issue other commands.
  3. If their browsers support Java, advise users to click on the Start button to launch the download applet. The applet will download the required files for their particular Linux (RedHat or SuSE) or Windows platform, and launch the Lotus Expeditor Client installer.
  4. If their browsers do not support Java, advise users to click on the link "If you have trouble with the downloader, click here". Then the user will be able to click on either a Linux or Windows link to download the zip package, which will contain the same required files that the applet downloads.
  5. Instruct users to unzip this file and execute the appropriate installer: install.bat (for Windows) or install.sh (for Linux). Advise Linux users to launch install.sh with root privileges, for example: sudo ./install.sh or su - root -c "./install.sh"
  6. Upon completion, the client installer contacts the server and completes the installation. If the update site is in a protected area, the client will prompt for user ID and password.

Special considerations for Windows Vista

Installing the Lotus Expeditor Client from the Web using Windows Vista in protected mode is not supported. Follow these steps as a work-around:
  1. Place your Web server in a trusted zone using the Internet Explorer configuration. This will disable protected mode for this site and allow the installation to succeed.
  2. Direct your users to access the following site:
    http://<server>/Expeditor/applet/text/<language>/DownloadListIndex.html  
    where <server> is the server name and <language> is the language.

Installing on Ubuntu

  1. Download the Linux zip package from the customized installation Web site.
  2. Extract the files from the zip onto a local folder on your system.
  3. Create the following directory structure on your system if it does not exist:
    /etc/ibm/expeditor
  4. Copy the install.options file included in the zip to the /etc/ibm/expeditor directory.
  5. Launch the Expeditor client installation by running the following command:
    sudo dpkg -i Expeditor-6.2.0.<buildlevel>.deb
If you need to remove Lotus Expeditor Client from Ubuntu, run the following command:
sudo dpkg –r expeditor

Notifying users on how to install from the Web using supported devices

As administrator, you need to inform your users on how to install the Lotus Expeditor Client from the Web using supported devices.

If a user recieves a "get page-cannot-be-found" error from the download links on the NCI download page for mobile platforms, this is because the NCI installer provides desktop download files on an HTTP server. To solve this issue, you must copy all CAB and SISX files from <device_image_CD>\device\install folder to the HTTP server document root. For IBM HTTP Server (IHS), the location of the HTTP server document root is:
<IHS_ROOT>/htdocs/<locale>/Expeditor/install 
For the default NCI server install, the respective installation files reside in the following directories:
  • Windows Mobile Professional - <IHS_ROOT>/htdocs/en_US/Expeditor/install/wm
  • Windows Mobile Standard - <IHS_ROOT>/htdocs/en_US/Expeditor/install/wmstd
  • Windows CE - <IHS_ROOT>/htdocs/en_US/Expeditor/install/wince
  • Nokia S60 - <IHS_ROOT>/htdocs/en_US/Expeditor/install/s60

If you are using a different HTTP server, consult that document for the location of the HTTP document root.

You must also inform your users of the following steps:
  1. Provide users with the URL to your customized installation Web site. Use the sample HTML template provided and customize it for your environment. The default is http://<server>/Expeditor/applet/text/<language>/DownloadListIndex.html.
  2. Select the appropriate link for your platform from the list at the bottom. This causes a .cab or .SISX file to be downloaded to the device. When the device asks if the file should be automatically installed, users should select yes, install the file automatically. After the installation is complete, users must manually configure the rest of the settings.
  3. Upon completion, the users of enterprise managed devices must set Enterprise Management preferences. This can be done by installing a configuration file you provide to them or by setting the fields in the Enterprise Management preference page. This preference page is accessible on the device from the Application Manager by selecting Command > Preferences. See Configuring the Enterprise Management Agent for more information on Enterprise Management Agent parameters.

Silently installing the Network Client Installer

You can set up the Network Client Installer installation program to run silently if you do not want to interact with the installation wizard.

To do you this, you should install using the installation wizard, answering all the questions as how you would like the silent install to run. After the installation is complete, copy the installNCI.rsp file from the <destination>/package directory, where <destination> is the directory in which you chose to install the Network Client Installer.
Note: Installer executables are located in the nci/install/ directory of the CD.
  • On a Windows system, run the setupwin32.exe file.
  • On a Linux system, run the setuplinux.sh file.
  • On an AIX system, run the setupaix file.
  • On a Linux system for System p, run the setupLinuxPPC.sh file.
Choose from two ways to install silently:
  • Edit the response file.
    Important: If you choose this option, your Portal password will remain in clear text in the response file after the installation has completed. This is not the recommended approach.
    1. Using a text editor, open the response file that you copied earlier, and <destination_dir>package/installNCI.rsp, replace <enter your password> with your password in the NCI_PORTAL_PASSWORD property, and save the file.

      For example, NCI_PORTAL_PASSWORD=expeditor.

    2. Run the following command:
      <setup executable> -silent -options installNCI.rsp
      For example, on Linux:
      setuplinux.bin -silent -options installNCI.rsp
  • Use a command line option.
    1. Run the following command:
      <setup executable> -silent -options installNCI.rsp -V NCI_PORTAL_PASSWORD=<portal password>
      For example, on AIX:
      setupaix -silent -options installNCI.rsp -V NCI_PORTAL_PASSWORD=myPortalPassword
    Note: Because this is a silent install, no command line or graphical output is created. To view the progress of the install or to see any error messages generated, view the install log file, which is located in the temp folder defined by your operating system. In this temporary directory, the file NCI/logs/masterInstallLog.txt will contain the output from the installation.

Uninstalling the Network Client Installer

This topic describes how to uninstall the Network Client Installer. Before you uninstall the Network Client Installer, check that the installation completed successfully.

To uninstall the Network Client Installer, follow these steps:
  1. Locate and launch the Network Client Uninstaller program. Depending on how the product was installed, the uninstaller file is located in either the _uninst2 or _uninst3 directory in your installation path (specified by \_uninstn as shown).
    Windows
    install_path\_uninstn\uninstaller.exe.
    Linux
    install_path/_uninstn/uninstaller.sh
    AIX
    install_path/_uninstn/uninstaller.bin
    Linux for System p
    install_path/_uninstn/uninstaller.sh
    Note: To uninstall the Network Client Installer on WebSphere Portal with SSL enabled, follow these steps:
    1. Copy the .sp file generated during the Network Client Installer installation to the nci_home/_uninstn directory that contains the uninstaller program, where nci_home is the Network Client Installer installation directory and n is a number.
    2. Rename the .sp file to uninstaller.sp so that it matches the launcher's base file name.
    3. Launch the uninstaller program and complete all required steps.
  2. Follow the prompts.
The Network Client Installer is uninstalled.

Silently uninstalling the Network Client Installer

You can silently uninstall the Network Client Installer installation program.

If you need to silently uninstall the Network Client Installer, use the appropriate uninstaller launcher as described in Uninstalling the Network Client Installer together with the silent install response file referenced in Invoking a silent installation on Microsoft Windows.

For example, on Windows:
C:\program files\IBM\Lotus\Expeditor\NCI\_uninst3\uninstaller.exe -silent -options
installNCI.rsp –V NCI_PORTAL_PASSWORD=expeditor

Upgrading the Network Client Installer

Consider these things first before upgrading.

If you had a previous version of the Network Client Installer (NCI) installed on your system, and you are installing this version as an upgrade, there are some things you should consider:
  • If a previous version of NCI is installed, it will be detected. The new version will install directly without the need to manually uninstall the previous version.
  • The client update site that is installed on the web server will be overwritten with the update site on the client CD. This means that if you have added features to this site and use the siteXmlUpdater tool, you will need to re-run this tool after the update.
  • The client installers and manifest files will be overwritten with the client installers from the client CD. This means that if you have customized the provisioning manifest files in the desktop/deploy directory, you will need to re-customize these files after the update.

Updating the installation information on the Web server

If you move your Web server or change other system information, you will need to update the configuration on the Web server.

To update the installation information:
  1. Update the installer.root property in the download.properties file.

    If you want to change the way the client installer is run, you can update the win32.downloads.execute and the linux.downloads.execute property. This is useful for passing an options file or other parameters to the installer. See Creating and using options files on Linux for more information.

  2. If the URL you use to access your portal server is different from the default, update the "portal.server.url" property to the correct URL.
  3. Run the ArchiveCreator tool located in the <Expeditor_install_root>/bin directory.
The ArchiveCreator tool recreates the zip files that are downloaded when the Lotus Expeditor cannot run the download applet.

Installing the Expeditor Client for Windows and Linux on Portal

You can install the Lotus Expeditor Client for Windows and Linux on Portal.

Before you install the Lotus Expeditor Client, review system requirements and verify that you have the correct version of Portal Server installed and configured. Check that the Network Client Installer software does not previously exist on the server. A supported HTTP server must also be installed. It can be on another computer in the network.

You must also have an active account on the server.
  1. Install the Network Client Installer from the Lotus Expeditor Client CD. See Installing the Network Client Installer.
  2. Select Web content and Portal content from the list of features.
    Note: If you are installing in a clustered environment, select only Portal content from the list of features. Web content must be installed on the remote Web server.
  3. Use the Portal Administration portlets to place the downloads portlet on a page that is accessible by your users.
  4. In a clustered environment, edit the value for wed.download.url of the Download portlet to the URL of the remote Web server installation site. For example, http://<server name>/Expeditor/applet/index.html.
The Lotus Expeditor Client is ready to be downloaded and installed from Portal.

Notifying users on how to install the desktop client from Portal

As administrator, you need to notify your users on how to install from Portal.

Your users should be informed of the following steps to install the Lotus Expeditor Client from Portal.
  1. Log in to Portal using a browser, and access the Downloads portlet.
  2. Select the install link.
  3. If their browsers do not support Java, they will be prompted to save and execute the installer.
  4. Users may be prompted to restart the Lotus Expeditor Client.

Applying updates

You can apply updates to the Network Client Installer from the server.

Before you install the Lotus Expeditor, check that either the Expeditor Server or Portal Server 6.0 or greater is installed and configured. Check that the Network Client Installer software has been deployed on the Expeditor Server.

  1. Download and install the Update installer if it is not already present on the server.
  2. Download the Network Client Installer update package.
  3. Run the Update installer and select the update to the Network Client Installer.

Applying fixpacks and individual fixes

You can apply fixpacks and individual fixes to update Network Client Installer bundles.

Before you install the update to the Lotus Expeditor, ensure that the Network Client Installer has been deployed to your Web server.

  1. Download the fixpack.
  2. Unzip the IFix on top of the existing Eclipse update site (located under <docroot>/expeditor/updates/platform).
  3. Run the siteXMLUpdater tool located in the <nci_install_dir>/bin directory. This updates the site.xml.

Using options files

If you want to change the options of the client install that results from downloading from the Web Server, you can edit the options files located in the <docroot>/Expeditor/install directory on the Web server.

See Creating and using options files on Linux for the format of these options files.

To choose the command-line options for the client install from the server, edit the download.properties file under the <docroot>/Expeditor/applet directory.

After you edit this file or the options files, run the Archive Creator tool under <nci_install>/bin to regenerate the archives for non-java enabled browsers.

Installing and launching the Expeditor Client in a Citrix environment

The Lotus Expeditor desktop client can be installed on a Citrix Presentation Server 4.5 running on Windows Server 2003 and, subsequently, published as an application to allow Citrix users access. This section describes the procedures involved for such an installation.

Prerequisites

This topic lists prerequisites and recommendations to install the Lotus Expeditor desktop client on a Citrix Presentation Server 4.5 successfully.

Prerequisites are as follows:
  • Windows Server 2003 with Citrix Presentation Server 4.5
    Attention: For a new Citrix installation, it is highly recommended to test the server by publishing an application, such as Adobe Acrobat Reader, before attempting to publish Lotus Expeditor.
  • Citrix Presentation Server 4.5
    Notes:
    • Lotus Expeditor 6.2 only supports the Web/ICA deployment technology.
    • Lotus Expeditor 6.2 only supports being published as an application.
    • Lotus Expeditor 6.2 does not support multiple client monitors with Citrix Presentation Server 4.5.
    • If a farm of Citrix servers is being used, it is recommended to also employ Windows Roaming Profiles to ensure that the user has access to their Lotus Expeditor-specific information, regardless of which server the Expeditor client is running on in the farm.

Installing Expeditor Client on Windows Server 2003 / Citrix Server

This topic describes how to install the Expeditor Client in a Windows Server 2003 / Citrix Presentation Server 4.5 environment.

The initial installation steps are similar to any other Lotus Expeditor installation:
  • Member of Administrators group perform the installation
  • Launch Lotus Expeditor after installation to ensure functioning properly
  • Install all additional Lotus Expeditor-based applications, which can be accessed by users
  • Exit Lotus Expeditor

Configuring Citrix Presentation Server to publish Lotus Expeditor as an application

This topic describes how to use the Citrix Presentation Server wizard to publish Lotus Expeditor as an application.

Citrix Presentation Server 4.5 provides a wizard for publishing applications. You can launch the wizard from within the Citrix Access Management Console. Recommended settings for each wizard panel are as follows:
Note: Settings assume the default installation location: C:\Program Files\IBM\Lotus\Expeditor\
  • Welcome: There are no configuration options. Continue to the next panel.
  • Name: Type a display name, such as Lotus Expeditor and complete the application description.
  • Type: In the Application section, select Accessed from server and Installed application.
  • Location: Complete the following fields:
    • Command line: C:\Program Files\IBM\Lotus\Expeditor\rcp\rcplauncher.exe
    • Working directory: C:\Program Files\IBM\Lotus\Expeditor\rcp
    • Isolate application: Disable this check box.
  • Servers: Add one or more configured Citrix server names to deliver Lotus Expeditor to client machines.
  • Users: Add one or more user names, which require access to Lotus Expeditor.
  • Shortcut presentation:
    • Application icon:
      • The rcplauncher.exe binary does not contain icon information to allow branding and customization. Therefore, it is necessary to point to a specific Windows ICO file.
      • The default Lotus Expeditor branding icon is located at C:\Program Files\IBM\Lotus\Expeditor\rcp\eclipse\features\com.ibm.rcp.personality.default.branding.feature_version\win32x86\xpd.ico
    • Application shortcut placement: You can add the previously specified icon to the client machine's Start Menu or as a Desktop shortcut, but is not necessary. If the icon is not added to either location, users must access the Citrix Web Interface to log in and, subsequently, launch Lotus Expeditor.
  • Publish immediately: Click Finish. Lotus Expeditor is available for Citrix users to access.

Accessing Lotus Expeditor remotely through the Citrix Web interface

This topic describes how Citrix clients can access Lotus Expeditor remotely.

After completing the installation and application publication steps, Citrix clients can access Lotus Expeditor by completing the following steps:
  1. Open Internet Explorer and load the Citrix server Web address.
  2. Install the Citrix ICA Client package, if it is not installed already. This might require a browser and/or system restart depending on the installation options selected.
  3. Log in to the Citrix server. Lotus Expeditor is displayed in the Applications panel.
  4. Click the Lotus Expeditor icon to launch the Citrix ICA Client. The Lotus Expeditor platform is launched.
Note: If different Display name or Application shortcut placement options were selected during configuration, the user might need to look for a different icon, or perform additional navigation operations on the Citrix Web interface, before the Lotus Expeditor platform is launched.

Citrix environment limitations

This topic lists limitations when running the Lotus Expeditor desktop client in a Citrix environment.

The Lotus Expeditor desktop client in a Citrix environment functions similar to any other installation. However, the following limitations are introduced, primarily due to multiple users concurrently accessing the platform:
  • Lotus Expeditor 6.2 does not support the Lotus Expeditor Restricted Workbench functionality in a Citrix environment.
  • The installation directory (for example, C:\Program Files\IBM\Lotus\Expeditor) must be properly secured to ensure that only members of the Administrators group can add, modify, and delete files.
  • To prevent platform corruption, only one member of the Administrators group should manage/provision the Lotus Expeditor platform installation at any given time.

Changing the virtual machine

The default virtual machine used by the IBM Lotus Expeditor platform is the DesktopEE runtime environment. This virtual machine provides sufficient capabilities for the default install set of IBM Lotus Expeditor components. If you need more function, such as Swing, or AWT programming libraries that are provided by the Java 2 SE 5.0 virtual machine (VM) , follow the instructions in this section to either use an existing VM on your system or install the IBM Device Runtime Environment (DRE), a separately available product.

Installing the IBM Device Runtime Environment

Follow the instructions in this section to install the IBM Device Runtime Environment (DRE), a separately available product.

The IBM Device Runtime Environment product contains two features that are applicable to the Lotus Expeditor Client platform. The first is the J2SE Core JVM Feature, which provides the Java 2 SE 6.0 VM capabilities. The second feature is the JavaServer Faces Feature, an alternative to the Apache MyFaces support.

To use either of these components, you must install them into the Lotus Expeditor Client.

Installing DRE components into the Lotus Expeditor Client

Install the DRE using either the Install/Update UI or using the provisioning manifest. The Install/Update UI is useful for installing a DRE into only one runtime, but for automation purposes, you should consider using the provisioning manifest.

To install DRE components using the Update Manager UI:
  1. Start the Lotus Expeditor Client. Then select File > Application > Install
  2. From the Install/Update (Feature Updates) dialog, select Search for new features to install. From the Install (Update Sites to Visit) dialog, create a new Update site definition.

    Select a New Remote Site if the DRE has been made available using a Web site. Otherwise, select a New Local Site. Browse to the location of the DRE (CD-ROM drive letter or location where it might have been unzipped on a mapped drive letter or mount), then select updates/client. Select Finish.

    When the Install (Search Results) dialog appears, select the Core JVM Feature – J2SE feature, then select Next. (You can also select the JavaServer Faces (JSF) feature at this point). If the license terms are agreeable, select I accept the terms in the license agreement, then select Next. Then select Finish to complete the installation.

    A dialog informing you that the feature is not signed might appear. Select Install on this dialog to continue.

  3. To perform a more automated installation of the DRE, you can either customize the provisioning manifest for install (Customizing basic installation) or use the ProvisioningApplication to install the DRE using a provisioning manifest (Using the provisioning manifest).
    For example, you could use the following provisioning manifest contents in file C:\core.jvm.feature-j2se.xml:
    <?xml version="1.0"?>
    <ibm-portal-composite>
    <domain-object name="com.ibm.rcp.installmanifest">
    <object-data>
    <install>
    <installfeature id="core.jvm.feature-j2se" required="true">
    <requirements>
    <feature action="install" 
             id="com.ibm.rcp.jvm.feature" 
             match="greaterOrEqual" url="file:/X:/updates/client/site.xml" 
             shared="false" 
             version="2.0.0.0-200704260500"/>
    </requirements>
    </installfeature>
    </install>
    </object-data>
    </domain-object>
    </ibm-portal-composite>
    where X: is the CD-ROM drive containing the DRE CD-ROM.
    You would then invoke the provisioning application to install the DRE in addition to the DesktopEE VM that is already installed:
    rcplauncher –application com.ibm.rcp.provisioning.application.ProvisioningApplication 
       –provisioningOperation provision C:\core.jvm.feature-j2se.xml  
    Alternatively, you can choose to only install the Core JVM Feature – J2SE during the initial installation.

    You can update the install.xml provisioning manifest to include the feature definition as above (and remove the com.ibm.rcp.jvm.feature definition that refers to the version 1.0.0.x of the jvm feature).

Changing to a different runtime and class library

Although you can install both virtual machines (DesktopEE and Java 2 SE 6.0) into the Lotus Expeditor Client, only one VM is active for the platform. To switch the active VM, you must use the Application Management UI to switch the VMs. To do so, select File > Application > Application Management. Expand the /rcp/eclipse site, and locate the Core JVM Feature. Select this feature, then select the task Replace with another version. This will open a dialog prompting you to select another version of the feature. You can switch from DesktopEE to J2SE, or J2SE or DesktopEE using this method.

Understanding the VM packaging

The VM that implements the Java specifications is packaged as a feature.

All VM features are child features of the parent feature com.ibm.rcp.jvm. The major version number represents an entirely different VM provider. For instance, the Lotus Expeditor Client ships with Desktop EE VM and is major version 1. This scheme allows for seamless upgrade of a VM and also allows the switching of VMs using the update manager.
com.ibm.rcp.jvm.feature_2.0.0.0 includes
        com.ibm.rcp.j2se.win32.x86.feature_1.5.0.SR2 
com.ibm.rcp.jvm.feature_1.0.0.0 includes         
        com.ibm.rcp.dee.win32.x86.feature_6.5.0.<builddate>
The VM properties are located in the VM plug-in file jvm.properties. The launcher dynamically adds these properties to the launch command. This method assures that the VM plug-in defines the properties that it needs.

The –vm property can be used on the command line. However, if you need additional VM properties, you are responsible for adding them.

Using an existing virtual machine

The Expeditor Client uses the J2SE runtime environment by default. On Windows, if you would instead like to use an existing Java 1.5 or 1.6-based virtual machine on your system during the installation of the Expeditor Client, you must use the EXTERNAL_JVM_LOCATION property.

Note: On Linux, the internally packaged J2SE virtual machine is always installed. Upgrading from previous platforms where an external JVM was used will now result in the internal JVM being used. The EXTERNAL_JVM_LOCATION property is not available on Linux for Expeditor Client 6.2.1.

The EXTERNAL_JVM_LOCATION property must point to a valid IBM or Sun JVM, version 1.5 or 1.6, and must also point to the Java executable (java or javaw) that you wish to use. The installation of Expeditor Client validates this JVM to ensure that it is a supported JVM. Expeditor Client does not allow an installation using unsupported JVMs.

Expeditor Client supports the following external JVMs:
  • Sun J2SE 5.0
  • Sun Java SE 6.0
  • IBM J2SE 5.0
  • IBM Java 6.0
  • DesktopEE 6.5

On Windows, you can set the EXTERNAL_JVM_LOCATION property either as a command-line property or within a transform.

To set it as a command-line property, use:
setupwin32.exe /v"EXTERNAL_JVM_LOCATION=\"<absolute path to Java executable on system>\"" 
To set it within a transform, you must add the EXTERNAL_JVM_LOCATION property and give it a value of:
<absolute path to Java executable on system> 

If you wish to utilize the default JVM on your system (and not provide an exact location to the java or javaw executable) you may set EXTERNAL_JVM_LOCATION=SYSTEM_JVM. Expeditor Client validates the system JVM to ensure that it is a supported version before installing.

Note: When installing a platform and using an external JVM, only upgrades which also use an external JVM are supported. Upgrading a platform that does not use an external JVM to one that uses an external JVM is not supported. Similarly, upgrading a platform that uses an external JVM to one that does not use an external JVM is not supported.

Configuring the platform

This section describes the tasks you can perform to configure the Lotus Expeditor Client on the user's machine.

Configuring Java system properties

Applications might require specific system properties to be set at startup when running the Lotus Expeditor Client platform.

To minimize the number of parameters that you must specify on the command line, you can add configuration lines to the rcpinstall.properties file.

See Updating the rcpinstall properties file for detailed information.

You can also specify properties on the command line when you launch the platform. See Configuring the platform launcher for more information.

Configuring Virtual Machine arguments

Applications might require the addition of specific arguments for a Virtual Machine (VM) that implements the Java specifications when the platform starts.

To minimize the number of parameters that must be specified on the command line, you can add vmarg.* configuration lines to the rcpinstall.properties file, which resides in the .config directory of the workspace. (See Overriding the workspace directory location for more information.).

See Updating the rcpinstall properties file for detailed information.

You can also specify VM arguments on the command line when you launch the platform. See Configuring the platform launcher for more information.

Configuring native library references

When using the Lotus Expeditor on the desktop, the recommended approach is that all native library objects be included in operating system/processor specific fragments.

In general, this is sufficient to allow the application code and the operating system to locate the desired library. However, there might be cases where it is not possible to organize the libraries within a fragment, or the library loading requirements inhibit this approach. Therefore, library search path must be updated.

You will need to update the library.path.append or library.path.prepend lines in the rcpinstall.properties file to specify the directory locations containing the libraries.

See Updating the rcpinstall properties file for detailed information.

Configuring Java bootclasspath libraries

When using the Lotus Expeditor Client on the desktop, the recommended approach is that all class libraries that are needed by applications reside within plug-ins or fragments.

If there are cases in which the libraries must be placed on the Java bootclasspath, then you will need to update the –Xbootclasspath.append or Xbootclasspath.prepend line or lines in the rcpinstall.properties file.

Refer to Updating the rcpinstall properties file for detailed information.

Configuring the platform launcher

You can configure additional arguments to use when the user launches the Lotus Expeditor Client. For example, you can specify that a console is displayed when launching the client.

Options that you might want to configure are as follows:

–application
Temporarily overrides the application property in the rcpinstall.properties file.
–config
Allows you to specify command options in the rcplauncher.properties file to avoid operating system restrictions in the length of commands. See Updating the rcplauncher.properties file for more information.

The launcher output is written to a file named rcplauncher.log in the logs directory. For a normal launch, it does not contain any output. It contains information if you are using the –debug option or if the launcher has a fatal error while launching the platform. In the event of a fatal error prior to the creation of the log, the output is written to /tmp/rcplauncher.log on Linux and to %TEMP%/rcplauncher.log on Windows.

Arguments based on VM, Eclipse, or OSGi are passed through, except for the following:
  • If either the –console or –consoleLog option is specified, then javaw.exe/expeditorw.exe specified in the rcpinstall.properties file is converted to java.exe/expeditor.exe by the launcher.exe.
  • –configuration: This option is stripped. The configuration location is always calculated as workspace_location/.config.

For a complete list of runtime options defined by Eclipse, see the Platform Plug-in Developer's Guide, which is installed with the Rational® Software Development Platform, and to http://help.eclipse.org/help32/index.jsp.

To configure the platform launcher to use additional options, you must add the option to the path of the executable. To add options to the executable, modify the shortcut from the desktop icon. Additionally, you can add options as properties in rcplauncher.properties. See Updating the rcplauncher.properties file for more information.

–console
Enables you to display the OSGi console. You can have the maximum information logged by adding logredirector.level=INFO to the rcpinstall.properties file. These two options work well together when you need to debug problems.
Note: On Linux you must also change the application type to "Application Terminal" in the shortcut properties.
–data
Temporarily overrides the workspace location (osgi.instance.area property). The default calculation of the workspace is specified by the rcp.data property in rcplancher.properties. The configuration area is calculated based on this value. A –configuration option is ignored.
Note: If the default workspace is not available or inaccessible, specify the workspace during IBM Lotus Expeditor startup using the following command:

rcplauncher.exe -data workspace

where workspace is the path to the desired workspace location.
–debug
Causes additional debugging information to be logged automatically for the core launcher components. Normally the --launcher.supressErrors argument is added by the launcher. This has the effect of suppressing the dialog displayed by the Eclipse executable when the Java machine returns unexpectedly. If you want to see this dialog during a debug session it can be enabled by adding -debug to the launch arguments.
–dir
Overrides the bidi direction. Correct values are rtl and ltr.
Note: Overriding the settings to specify rtl is not supported on Linux.
–nl
Overrides the locale being used. The appropriate locale features must have been installed to provide for localized content. For more information, see Installing additional languages content.
Note: Overriding the settings to specify Hebrew or Arabic as a locale is not supported on Linux.
–personality
Customizes the look and feel depending on the desired applications. This can be used to override the value specified in the rcpinstall.properties.
–product
Overrides the product feature that is specified by other means.
–version
Prints the version of the rcplauncher to the temporary log and exits. For example: rcplauncher.exe –version
–vm
Overrides an external Virtual Machine (VM). You must also pass in any vmargs that are required for this VM. The VM pointed to by this option can cause problems when switched after the fact. IBM supports the VMs packaged with the product as well as IBM Java 6 and Sun Java 6.
–vmargs
Allows additional vmargs to be passed to the VM that implements the Java specifications. No checks are performed on the values. This is not an override, but strictly an addition to the vmargs specified in the rcpinstall.properties file.

Dcommands

See the com.ibm.rcp.core.daemon.package javadoc for information about how to use the daemon.

The com.ibm.rcp.core.daemon class defines an interface that must be implemented by an application developer who uses the com.ibm.rcp.core.daemon.command extension. See the Extension Point Schema documentation in Developing applications for Lotus Expeditorfor more information.

You can use this extension point when you need to forward a command to a plug-in from a desktop command. To do so, follow these steps:
  1. Add the command as an option to the launch command.
  2. Run the launch command. Instead of launching the platform, the daemon forwards the complete launch command to the platform.
  3. The plug-in that registered the extension has its RcpDCommand.execute() method called.
  4. Call the execute method to decode the command line arguments and act on them in some way.
A plug-in that is to receive commands must:
  • Contain the com.ibm.rcp.core.daemon.command extension point in its plugin.xml. A complete example can be found in the Extension Point Schema documentation in Developing applications for Lotus Expeditor.
  • Implement the com.ibm.rcp.core.daemon.RcpDCommand interface, which is defined in the Extension Point Schema documentation in Developing applications for Lotus Expeditor.
To activate the command, launch the platform with rcplauncher.exe -my.plugin#extId.my_command. If the platform is running, the command is forwarded to the plug-in.
If the platform is not running, the command is ignored and the platform is started. If you need to encrypt the command stream sent to the platform, the following property should be added to the rcpinstall.properties file:
-Ddaemonconnect.provider=
			com.ibm.rcp.core.internal.connect.encrypt.EncryptedDaemonConnect 

The daemon thread listens for commands while the platform is running. It examines each parameter for command ID patterns registered using the extension point. See the com.ibm.rcp.core.daemon.package javadoc for more information.

The daemon thread recognizes the following pattern for command IDs:
-plugin-id#[extension-id.]command-id
where the need for the optional [extension-id] element depends on whether the extension ID was specified in the plug-in manifest when the command was registered.
Example: Register the extension point in plugin.xml:
<extension [id="foo"] point="com.ibm.rcp.core.daemon.command">
    <command id="mycmd" class="org.example.MyCommandClass"/>
</extension>
where the extension ID is optional. If the extension ID ("foo") is specified, the RcpD examines the received parameters for matches of the form:
-my.plugin#foo.mycmd
If the extension ID was not specified in the manifest, the RcpD would be looking for:
-my.plugin#mycmd
Since the entire parameter list is sent to each command, it is possible for each command to have any number of arguments:
-my.plugin#mycmd arg1 arg2 arg3...
Example: It is also possible to register for all command-line notifications, regardless of content, as follows:
<extension [id="foo"] point="com.ibm.rcp.core.daemon.command">
    <command id="mycmd" class="org.example.MyCommandClass" matchAll="true"/>
</extension>
If you register a handler to receive all commands, you should not register it to receive individual commands also.
Example: Application's plugin.xml:
<plugin>
   <extension
         point="com.ibm.rcp.core.daemon.command">
      <command
            class="com.jdmiles.command.MyCommandClass"
            id="my_command"
            matchAll="true"/>
   </extension>
</plugin>

Configuring deployment settings

The provisioning system of the client platform provides the feature install and life cycle management. The provisioning system extends the capabilities provided by the underlying Eclipse Update Manager.

The Eclipse Update Manager and the provisioning system provide a number of preferences to control how these functions operate.

Changing deployment preferences

This section describes the deployment preferences you can change.

The following set of preferences are available and managed using Eclipse Preferences. IBM Lotus Expeditor allows many of them to be set by the user using the Install/Update Preferences page. You can set other preferences through manual file updates of the plugin_customization.ini file or through remote management of the org.eclipse.update.core node, the org.eclipse.update.scheduler node, and the com.ibm.rcp.provisioning node. See Managing Eclipse preferences for more information on remote management of Eclipse preferences.

Preferences for org.eclipse.update.core:
updatePolicyURL
Location of the update policy file. This may be a local file or one accessible through an HTTP (or similar) URL. This preference is available to the user using the Install/Update Preference page.

Default: Not specified

org.eclipse.update.core.historySize
Number of history update files to maintain for the platform.

Default: 100

org.eclipse.update.core.checkSignature
Whether to check for signed feature objects during installation.

Default: true

org.eclipse.update.core.automaticallyChooseMirror
Automatically check Mirrors during feature installation.

Default: false

org.eclipse.update.core.updateVersions
Select the features that the scan for updates will select prior to display. Available values are compatible, equivalent, or major. This preference is available to the user using the Install/Update Preference page.

Default: equivalent

Preferences for org.eclipse.update.scheduler:
download
Search for updates and notify when they are available (false) or download new updates automatically and notify when ready to install them (true). Ignored unless enabled preference set to true. This preference is available to the user using the Install/Update Preferences page.

Default: false

enabled
Whether to automatically search for updates.

Default: false

schedule
Determines when to search for new updates. Choices are to search on platform start (on-startup) or on a schedule (on-schedule). Ignored unless enabled preference set to true. This preference is available to the user using the Install/Update Preferences page.

Default: on-startup

hour
Time of day to search for new updates (time specified in HH:00 AM|PM). Note that this value is locale dependent, so a setting for US English is not recognized correctly on another locale. Administrators managing platforms in multiple locales will need to set a locale specific setting. This preference is available to the user using the Install/Update Preferences page.

Default: 1:00 AM

day
Day of the week to search for new updates. Values are Every day, or Every <dayname>. Note that this value is locale dependent, so a setting for US English is not recognized correctly on another locale. Administrators managing platforms in multiple locales will need to set a locale specific setting. This preference is available to the user using the Install/Update Preferences page.

Default: Every day

Preferences for com.ibm.rcp.provisioning. (These preferences are not available through the preferences user interface. See Managing Eclipse preferences for more information on how to change these values.):
feature.history.size
Specifies the number of old versions of a feature to retain on the file system. The default values will depend on the platform configuration. If the platform configuration (install.configuration) is set to user, the default is 0. If the platform configuration is set to multiuser, the default value is -1, indicating that all feature versions are retained. The default value used on device configurations is 0.

As an example, if the value is set to 0, then installing an updated version of a feature will cause the previous version of the feature to be removed. If the value is set to 1, then when an updated version of a feature is installed, a single previous version will be maintained. If there was more than one version already installed on the platform, then the oldest versions will be removed. Only older versions of the currently enabled feature are removed. Versions greater than the currently enabled feature will not be removed.

runDeferredActionsOnStartup
Specifies when deferred actions should run, such as the uninstall of old versions of features. When set to true, the deferred actions will run immediately when the platform starts, and no progress indicator will be displayed. When set to false, the deferred actions will run after the workbench has completed its startup processing, and a progress indicator will be displayed. The default value is false.
updateSiteList
A list of Strings representing update sites separated by the vertical bar (|) character. For example:
  • Windows only
    file:/E:/updatesite|http://www.mycompany.com/myupdatesite|jar:file:/z:/someupdatesite.zip!/
  • Linux only
    file:///updatesite|http://www.mycompany.com/myupdatesite|jar:file:/z:/someupdatesite.zip!/

The sites in this list are in priority order. The first site in the list will be searched first, then the second site, and so on. A feature found on the first site will be used, even if the same feature with a higher version may be available on the second or third site. The default value for updateSiteList is an empty list.

whiteList
A Boolean specifying how the updateSiteList will be used.
If this property is set to true, then the Policy URL searching will be turned off and the useList preference, feature.xml update site, and the bookmarks.xml update site will be ignored.
useFeatureURL
A Boolean specifying whether to include update site URLs provided using feature.xml, provisioning manifest, or provisioning API request in the search list.
This preference determines if the feature.xml provided update site should be searched. The manifest and provisioning API requests are always used if specified. If the whiteList preference is set to true, then this value will be ignored.
useList
A Boolean specifying whether the list of update site URLs defined in updateSiteList are used.
If set to true, and if the whiteList preference is set to false, then the updateSiteList is used. If the whiteList preference is set to true, then this value will be ignored.

Configuring the update search settings

This section describes how the Expeditor platform provides for automatic searching for updates.

There are several ways that the Expeditor platform provides for automatic searching for updates:
  • From the File > Application > Install dialog
  • From the File > Application > Application management dialog (when the Lotus Expeditor product is selected)
  • From an individual feature in the Application Management dialog, if an update site has been configured for that particular feature
  • By enabling Automatic Updates using the Install/Update Preference Page or by programmatically updating the applicable Eclipse preference
The search hierarchy for Automatic Updates or Scan for Updates is as follows:
  • Update Policy URL
  • Update sites specified in individual features

To prevent any updates from occurring based on update sites in individual features, the update policy should always contain a pattern specified as “*”. Otherwise, if a feature is installed that does not match any patterns in the update policy, the individual update site specified by that feature will be used.

Automatic updates will search for feature updates of equivalent, compatible, or major, based on the preference setting org.eclipse.update.core/org.eclipse.update.core.updateVersions.

Specifying discovery sites and bookmarks for features

Bookmarks are update sites defined in the bookmarks.xml file residing in the configuration directory. Contributions to the bookmarks file can be provided through discovery sites defined in individual features. Bookmarks are not used during the automatic search.

Enabling and disabling the Update user interface

The Expeditor product provides access to the update manager user interface for deployment of new features and managing of the current configuration.

In addition, preference pages are provided to enable configuration of the behavior of the provisioning system, such as the platform update policy or scheduling of automatic updates. If desired, you can hide the menu actions and preference pages by using the activity support of the workbench.

Define the following extension to the org.eclipse.ui.activities extension point to define an activity that includes the menu actions and preference pages. This extension definition can be included in any plugin.xml (or fragment.xml) of any plug-in (or fragment) deployed to the client platform.
<plugin>
 <extension
   point="org.eclipse.ui.activities">
  <activity
    id="UIEnabler.installupdatemenu"
    name="Install Update Menu"/>
  <activityPatternBinding
    activityId="UIEnabler.installupdatemenu"
    pattern="com\.ibm\.rcp\.provisioning\.ui/management"/>  
  <activityPatternBinding
    activityId="UIEnabler.installupdatemenu"
    pattern="com\.ibm\.rcp\.provisioning\.ui/install"/>            
  <activityPatternBinding
    activityId="UIEnabler.installupdatemenu"
    pattern="org\.eclipse\.update\.ui/org\.eclipse\.update\.internal\.ui\.preferences\.MainPreferencePage"/>

  <activityPatternBinding
    activityId="UIEnabler.installupdatemenu"
    pattern="org\.eclipse\.update\.scheduler/org\.eclipse\.update\.scheduler\.AutomaticUpdatesPreferencePage"/>

            
 </extension>

</plugin>

After the activity is defined, you can enable or disable the activity to display or hide the actions and preference pages. This example includes both menu actions and preference pages in the same activity, but the activity can be defined to include only the capabilities that are desired to be controlled, such as only the menu actions. After the activity is defined, you can enable or disable the activity as needed.

Configuring feature search order

Lotus Expeditor provides an enhanced set of capabilities for managing and controlling the search order when locating new or updated features to install.

Deployers face the following three challenges in managing the set of features installed on any particular system:
  • To restrict the places a user can go to obtain new or updated features. If a user is allowed to go to any arbitrary update site to download new or updated features, there is a security risk – the integrity of the client platform could be compromised by malicious features.
  • To maintain the currency of the installed set of features. Issues such as network topology changes, renamed servers, third party references, and sites that are inaccessible from user's desktops make this especially challenging. Maintenance through updating of CA XML files can be difficult and time consuming.
  • To ensure that features are updated from the correct location. Users may find they have access to a variety of versions of the same features from different sites and may be confused by which site is the correct one to use. Deployers need the ability to specify the order that Expeditor uses to search for updates for installed features.
The client platform provides an enhanced set of capabilities for managing and controlling the search order when locating new or updated features to install. In addition, the platform now provides the concept of a White List – a restricted set of sites from which to obtain new or updated features. The following preferences are used together to provide flexible control over the update sites from which new features are obtained. See Changing deployment preferences for descriptions of these preferences.
  • com.ibm.rcp.provisioning/updateSiteList
  • com.ibm.rcp.provisioning/useList
  • com.ibm.rcp.provisioning/useFeatureURL
  • com.ibm.rcp.provisioning/whiteList
  • org.eclipse.update.core/updatePolicyURL

The combination of these 5 preferences determines the search order and location for installing feature updates. The following table describes how the settings influence the search order.

Table 1. White list managed settings and their desired outcomes
useFeatureURL useList UpdateSiteList whiteList Policy URL Desired outcome
True/False True/False If empty, this causes no features to be found. True Set/Not set Search the manifest feature URL first if it is in the updateSiteList. Next search the sites in updateSiteList. If search request contains a policy URL, whiteList will erase this value to ensure compliance. Log a message that the policy URL was removed. The sites in feature URL and bookmarks.xml will be ignored. If updateSiteList is empty, no features will be found.
True True Can be empty because feature URL and bookmarks.xml are also used to find features. False Not set Search the manifest feature URL first. Search the sites in updateSiteList next. If updateSiteList is exhausted or empty, then search the feature URL site. If request is from Update UI “Search for new features to install” action, search the sites in bookmarks.xml.
True False Irrelevant False Not set Search the manifest feature URL first. Next use the feature URL to search. If request is from Update UI, search sites in bookmarks.xml.
True False Can be empty because feature URL and bookmarks.xml are also used to find features. False Set Search for features using the policy URL if specified in the search request. Search the manifest feature URL next. If not found, search the updateSiteList. Search the feature URL site next. If request is from Update UI “Search for new features to install” action, search sites in bookmarks.xml.
True False Irrelevant False Set Search for features using the policy URL if specified in the search request. Search the manifest feature URL next. If not found search the feature URL site. If request is from Update UI “Search for new features to install” action, search sites in bookmarks.xml.
False True Could be empty because bookmarks.xml is used to find features also. False Not set Search the manifest feature URL first. Use the updateSiteList to search for features. If request is from Update UI, search sites in bookmarks.xml.
False False Irrelevant False Not set Search the manifest feature URL first. If request is from Update UI “Search for new features to install” action, use bookmarks.xml only to search for features.
False True Could be empty because policy URL and bookmarks.xml are used to find features also. False Set Search for features using the policy URL if specified in the search request. Search the manifest feature URL next. Search the updateSiteList next. If request is from Update UI “Search for new features to install” action, search sites in bookmarks.xml.
False False Irrelevant False Set Search for features using the policy URL if specified in the search request. Search the manifest feature URL first. If request is from Update UI “Search for new features to install” action, search sites in bookmarks.xml.

The default configuration of the platform allows updates to be installed from any update site specified in the provisioning request or using the provisioning API: [useFeatureURL = true, whiteList = false, useList = false, updateSiteList = <empty list>]. While this configuration provides the most flexibility, it also provides the least control over from where new features are obtained. In addition, this configuration relies on the users of the platform and the content of the distributed features to locate new and updated features.

To help control the number of sites from where features can be obtained, the updateSiteList can be defined with a set of update sites. In this configuration [useFeatureURL = true, whiteList = false, useList = true, updateSiteList = <nonemptylist>], in addition to the sites defined by the features, updates and new features can also be found on the set of update sites specified by updateSiteList. The update sites specified by the features will take precedence over the update sites specified by the updateSiteList.

A third setting of the configuration is very similar to using the update policy specified by the org.eclipse.update.core/updatePolicyURL preference. In this configuration [useFeatureURL = false, whiteList = false, useList = true, updateSiteList = <nonemptylist>], features will only be searched for on the update sites specified in the update site list. Whereas the update policy directs specific feature identifiers to specific update sites, this allows the update sites to be specified in a list, without requiring features to be obtained from any one of them. Note that in this configuration, if the updateSiteList is empty, no features will be able to be located, and the feature install requests will fail.

To provide the most control over where new and updated features can be installed from, the configuration [whiteList = true, updateSiteList =<nonemptylist>, useList = true or false, useFeatureURL = true or false ] will restrict updates to come from only the set of update sites specified on the updateSiteList. Note that in this configuration, if the updateSiteList is empty, no features will be able to be located, and the feature install requests will fail.

Note that since there are three Boolean variables, combinations other than those highlighted above are possible, but will result in a configuration in which provisioning requests can never succeed.

In all of the configurations except whiteList=true, the update policy (specified by org.eclipse.update.core/updatePolicyURL) can also be used. If the update policy is specified, then any feature update site remapping will occur prior to applying the preferences as defined above. For example, if a feature com.ibm.sample.feature contains a URL that refers to site http://www.ibm.com, and the update policy contains a mapping of "com.ibm.sample" to http://w3.mycompany.com, the feature search will be directed to http://w3.mycompany.com.

Update manager behavior when useList or whiteList preference is "true":

When the useList or whiteList preference is "true," the Update Manager will automatically add sites specified in the updateSiteList preference to the list of sites to be searched. These sites can be identified in the Update Manager by the "minus sign" that precedes the update site entry. These sites can not be modified or removed but they can be disabled from search by deselecting the site. When the whiteList preference is "true," the updateSiteList sites are the only sites that are available to the user and no bookmark sites will be displayed

When searching the update sites, the searches will occur in a specific order. If the feature is found on a site, and it satisfies the match rules contained in the request, then this feature will be used, regardless of any features that may be contained on any other sites.

The order of precedence for searching is:
  • Policy URL mapped sites (only if the search request has this set and whiteList preference is "false")
  • Feature URL from manifest request (only if manifest has a URL set)
  • updateSiteList sites in order (only if useList or whiteList preference is "true")
  • Feature URL site from feature.xml (only if useFeatureURL preference is "true" and whiteList preference is "false")
  • Bookmark sites in no order (only from Update UI "Search for new features to install" action and if whiteList preference is "false")

For performance reasons, it is therefore recommended that the updateSiteList, if used, be carefully managed to make sure that the update sites contain the features required, and are organized in the best performing order. Unresponsive sites may significantly increase the time required to complete a provisioning request.

To eliminate confusion as to which feature will be found during searches, it is recommended that the update sites either contain different sets of features or that the same versions of all features are maintained across all sites.

Configuring signed plug-in verification

This section describes the signed plug-in policy settings used by the Lotus Expeditor Client provisioning system for controlling access to local or remote Eclipse update sites. Your end users access the update sites to upgrade their base offerings and custom plug-in applications.

Because the provisioning system can access code from a local or remote eclipse update site, signing the jar files posted on the update site and verifying them on the client at download time allows the end user to get reliable information about the code they are about to download. This component allows them to identify who published the code and verify that software has not been tampered with or altered since the time it was uploaded to the update site. In addition, this component validates plug-in time stamps. You can time stamp a plug-in to ensure that when the it was signed, the signing certificate was not expired.

The decisions made by the provisioning subsystem when installing jars from an update site are made by a policy engine which uses policy settings defined as Eclipse preferences to make trust decisions. The policy engine that makes the trust decisions is controlled by a set of Eclipse preferences.

By default, support for verifying signed plug-ins is turned on.

To configure signed plug-in verification, modify the following Eclipse preferences. See Managing Eclipse preferences for setting preference information.
Table 2. Signed plug-ins preferences
Eclipse preference Possible Values
com.ibm.rcp.security.update/VERIFICATION_LISTENER Class implementing the IVerificationListener interface
com.ibm.rcp.security.update/EXPIRED_SIGNATURE_POLICY PROMPT/ALLOW/DENY
com.ibm.rcp.security.update/UNSIGNED_PLUGIN_POLICY PROMPT/ALLOW/DENY
com.ibm.rcp.security.update/UNTRUSTED_SIGNATURE_POLICY PROMPT/ALLOW/DENY
VERIFICATION_LISTENER
This preference setting indicates which Eclipse IVerificationListener implementation will be used by the provisioning system while verifying jar files being provisioned from an Eclipse update site. This subcomponent provides the below two implementations of IVerificationListener interface:
com.ibm.rcp.security.update.DefaultVerificationListener
Set this value for enabling this subcomponent when provisioning is done by launching the platform in headless mode. This can be enabled at install time by adding this preference to the plugin_customization.ini file in the deploy directory of the media kit.
com.ibm.rcp.security.update.ui.PromptVerificationListener
Set this class to implement the user interface to be shown to the end user. Offerings should set this value to when the platform is launched in non-headless mode and it is expected that the end user will make the trust decisions for untrusted code being downloaded by the provisioning system.
EXPIRED_SIGNATURE_POLICY
This preference setting value defines the default behavior for a given IVerificationListener implementation when it encounters a jar file, which is signed, but the certificate used to sign the jar file has expired.
UNSIGNED_PLUGIN_POLICY
This preference setting value defines the default behavior for a given IVerificationListener implementation when it encounters a jar file that is unsigned.
UNTRUSTED_SIGNATURE_POLICY
This setting value defines the default behavior for a given IVerificationListener implementation when it encounters a jar file that is untrusted.

Setting the above policy values to ALLOW or DENY will be interpreted by the IVerification Listener implementation to allow or deny provisioning of features. However, the policy setting of PROMPT will be interpreted by an IVerificationListener implementation based on whether the platform is running in headless mode. For example, the PromptVerificationListener will prompt the users to make the necessary trust decisions while the DefaultVerificationListener treats PROMPT as DENY so that untrusted code never gets provisioned.

For additional information regarding IVerificationListeners and other public APIs related to signed plug-ins, see the Eclipse Javadoc for the package org.eclipse.update.core.

Plug-ins can be signed using either Eclipse tools or the Java keytool.

Preloading certificates for initial install and provisioning of signed plugins

When a signed plugin is installed, it is verified using certificates in the media kit keystore and the IBM keystore. The IBM keystore contains public IBM certificates, which are used to verify IBM signed plug-ins. The media kit keystore contains public certificates used to verify third party plug-ins.

If a third party wishes to provide public certificates (including self-signed certificates) to be used to verify plug-ins at install time, use the following procedure:
  1. Create the following keystore file with no password (using keytool or ikeyman if available). Note: Use the keytool (or ikeyman if available) that is included with the target install JVM. This can also be done programmatically with the target install VM.

    Use the following filename for the given target install VM:

    Desktop EE VM (default):
    .keystore.jks.J9.install
    J2SE VM:
    .keystore.JCEKS.IBM_J9_VM.install
    Macintosh JVM:
    .keystore.JCEKS.Java_HotSpot(TM)_Client_VM.install
  2. Use keytool (or ikeyman if available) to add certificates to the newly created keystore.
  3. Place the keystore file in the desktop\desktop\deploy directory of the Lotus Expeditor install.
Note: If supporting more than one target install VM, repeat steps 1-3 using a different VM's keytool (or ikeyman) and a different keystore file name. The deploy directory can support multiple keystores.

Configuring the Web Container

The Web Container provides a runtime environment for Web applications in which Web applications can be run both disconnected and connected.

Configuring the Web Container properties

The default configuration for the web container listens only for HTTP requests received on localhost on a port dynamically selected during platform startup. If you need to make changes to this configuration, refer to the contents of this section.

The following properties are available for configuration of the web container.

Table 3. Java system properties
Option Default Description Java System Property
HTTP Port 0

Defines the port or list of ports used by the HTTP port listener to listen for requests. A value of 0 indicates that a port will be selected at random when the platform starts. A value of -1 indicates that no listener will be started to listen for HTTP requests.

com.ibm.pvc.webcontainer.port
HTTPS Port -1

Defines the port or list of ports used by the HTTPS port listener to listen for requests. A value of 0 indicates that a port will be selected at random when the platform starts. A value of -1 indicates that no listener will be started to listen for HTTP requests.

com.ibm.pvc.webcontainer.port.secure
HTTP Timeout 60 sec

Defines the value used for socket time-outs

com.ibm.pvc.webcontainer.http.timeout
HTTP Address localhost

Defines the host address(es) that the Web Container listens on. If this property is defined then the Web Container will only listen for requests that come through this IP address(es). The special value ALL indicates all available IP addresses on the device will be used. The value of this property may be a resolved name or IP address (for example, www.ibm.com, 192.168.0.101, localhost).

com.ibm.pvc.webcontainer.http.address
Note: Deprecated in Expeditor 6.2. Use the virtualhost configuration file to define Web application access rules
Min HTTP Threads 4

Defines the minimum number of threads to be started to listen for requests. Valid values are in the range of 0 to 63.

com.ibm.pvc.webcontainer.http.minThreads
Max HTTP Threads 20

Defines the maximum number of threads to be started to listen for requests. Valid values are in the range of 2 to 63.

com.ibm.pvc.webcontainer.http.maxThreads
Max Keep Alive Connections 20

Use this property to specify the maximum number of concurrent keep alive (persistent) connections across all HTTP transports.

com.ibm.pvc.webcontainer.http.maxKeepAliveConnections
Max Keep Alive Requests 50

Use this property to specify the maximum number of requests that can be processed on a single keep alive connection.

com.ibm.pvc.webcontainer.http.maxKeepAliveRequests
Keep Alive Timeout 20 sec

Use this property to specify the maximum number of seconds to wait for the next request on a keep alive connection.

com.ibm.pvc.webcontainer.http.keepAliveTimout
MIME Mapping configuration file mimemap.properties

Specifies the MIME mapping file to be used by the Web Container.

By default, the Web Container will use the mimemap.properties file that is located in the Web Container plug-in directory.

com.ibm.pvc.webcontainer.mimemap.configfile
Encoding configuration file encoding.properties

Specifies the character set encoding file to be used by the Web Container.

By default the Web Container will use the encoding.properties file located in the Web Container plug-in directory. Users can use this property to supply their own character set encoding file.

Users can specify an absolute path or a path relative to the working directory.

com.ibm.pvc.webcontainer.encoding.configfile
Converter configuration file converter.properties

Specifies the character converters to be used by the Web Container.

By default the Web Container will use the converter.properties file located in the Web Container plug-in directoryUsers can use this property to supply their own character converter file.

Users can specify an absolute path or a path relative to the working directory.

com.ibm.pvc.webcontainer.converters.configfile
Virtual host configuration file N/A

Specifies the location of the virtual host configuration file. This configuration file can be used to control access to web applications registered with the Web Container by port or hostname

com.ibm.pvc.webcontainer.vhost.configfile
Global Session Timeout N/A Specifies the global session timeout value. This value will override the session timeout setting specified at the application level. Value is an integer and is in minutes. com.ibm.pvc.webcontainer.http.sessionGlobalTimeout
Static File Directory N/A Specifies the location of the static files. The files in this directory can be accessed via a URL using a path relative to the root context “/” com.ibm.pvc.webcontainer.staticFileDirectory

If your machine is disconnected from the network (Linux only), then you need to manually add the following entry to the /etc/hosts file:

127.0.0.1 <your_machine_hostname>

This will allow the Web Container to function correctly when you are disconnected from the network.

Configuring the Virtual Host properties

The Web Container provides administrators with the capability to restrict access to Web applications to a specific port or list of ports. Refer to this section if you need to restrict access to certain Web applications.

Use the com.ibm.pvc.webcontainer.vhost.configfile system property to specify a configuration file that assigns a port(s) to Web applications. For example, if Web application A is mapped to port 80, then it can only be accessed from port 80; accessing Web application A from any other port will result in a 404 error.

The configuration file contains a series of application-port mappings. An application can be mapped to a port or a list of ports. An example configuration file would look like this:
/foo=localhost:80
/foo2=*:80
/foo3=*:*
/foo4=localhost:[80,8777,9999]
/foo5=[80,8777,8999]
/foo6=80
/foo7=xyz.com:*
/foo8=xyz.com:8777
/foo9=xyz.com:[80,8777]
  • foo is accessible only from localhost on port 80
  • foo2 is accessible from any external machine but only on port 80
  • foo3 is accessible from any external machine on any port
  • foo4 is accessible only from localhost on ports 80, 8777 and 9999
  • foo5 is accessible only from localhost on ports 80,8777 and 8999
  • foo6 is accessible only from localhost on port 80
  • foo7 is accessible from any external machine on any port IF the hostname of the machine the web application is hosted on is xyz.com
  • foo8 is accessible from any external machine on port 8777 IF the hostname of the machine the web application is hosted on xyz.com
  • foo9 is accessible from any external machine on ports 80 and 8777 IF the hostname of the machine the web application is hosted on is xyz.com
The following set of rules apply for the Virtual Host configuration file:
  • To protect a servlet, non-J2EE Web application (like WebServices dispatcher servlet), you will need to specify the servlet name similar to what you would do for a J2EE Web application that has a context root (for example, to secure the Web services servlet ws specify /ws=[9000, 9050] if you want to restrict Web services access to ports 9000 and 9050).

Channel Framework Configuration File – This file should be used to configure channels, channel chains and channel factories. Refer to Using the Channel Framework configuration file for more information on the steps involved in configuring the channel framework using system properties and also an example configuration file.

Configuring the Web Container to use a dynamic port

If the value of the com.ibm.pvc.webcontainer.port Java system property is equal to 0, then the Web Container selects a random port when the Web Container plug-in is started. This allows for multiple instances of the Web Container to be running at the same time on the same machine.

Lotus Expeditor Client uses a dynamic port by default.

Note: This port will be broadcast to all plug-ins that register a com.ibm.pvc.webcontainer.listener.HttpSettingListener service. For more information about the com.ibm.pvc.webcontainer.listener.HttpSettingListener service, refer to Locating the Web Container ports using the HttpSettingListener Service in Developing Applications for Lotus Expeditor. When using a dynamic port, the range of the port value is 1-65535. When specifying the value of a Web Container port, administrators must make sure that there is no conflict with any other server on the system. For example, administrators should be careful when setting the Web Container port to 80 since port 80 is frequently used by HTTP servers.

Configuring HTTPS

When using the Lotus Expeditor on the desktop, the secure hypertext transfer protocol (HTTPS) is a communications protocol used to encrypt data between computers over the Web.

HTTPS uses a Secure Socket Layer (SSL) to transfer encrypted HTTP data. Refer to Configuring SSL for the Web Container for the required steps.

Configuring the Web Container using the SocketConfigService

Third-party bundles can use the com.ibm.pvc.webcontainer.service.SocketConfigService service to dynamically configure the Web Container ports at run time. Review this section if you need to dynamically configure the Web Container ports at run time.

Bundles should use a ServiceTracker to track the com.ibm.pvc.webcontainer.service.SocketConfigService object.

The following example shows how to invoke the com.ibm.pvc.webcontainer.service.SocketConfigService startTransport and stopTransport methods from a bundle's ServiceTracker.
import com.ibm.pvc.webcontainer.service.SocketConfigService;
import com.ibm.pvc.webcontainer.service.SocketConfigException;
...

private BundleContext context = null;
private ServerSocket socket = null;

public MyServiceTracker(BundleContext bc) 
{
  	context = bc;
}

public Object addingService(ServiceReference reference) 
{
   SocketConfigService service = (SocketConfigService) context.getService(reference);
   if(service != null) {
        try {
            // create a ServerSocket
            socket = new ServerSocket(9999);

            // configure Web Container to listen on port 9999
            service.startTransport(socket);
            ...
        } catch (SocketConfigException e) {
             // handle exception
        }
        ...
   }
   ...
}

public void removedService(ServiceReference reference, Object service) 
{
   if(service != null) {
        // shutdown transport
        service.stopTransport(socket);
   }
}

Enabling and configuring the Channel Framework

The Channel Framework Architecture (CFA) is a highly flexible and scalable solution for client and server transports and provides common networking services, protocols, and I/O operations for the Expeditor Web Container.

Taking a protocol stack abstraction to building a transport, individual channels within this architecture may be thought of as protocol layers in a network stack. This architecture provides extended plugability along the entire chain of events involved in handling communication with the server and processing of the content of the communication at various steps in the server.

The CFA defines a set of interfaces that can be used to implement two main types of objects, channels and channel chains. Channels are used to transport data between the network and the Web Container server component. Channels are an encapsulation of the logic for processing some part of a data stream or for interfacing with a component. The data stream may be part of an inbound request to an application server or an outbound request from an application server. Channel chains consist of a set of channels that are linked together and used to transport data from the network to a component or from a component to the network. By defining a standard mechanism for combining channels, it becomes possible to plug in custom channels that support requirements unique to a particular customer or environment.

In the CFA, a component that is at the beginning or the end of a channel chain is known as the channel framework user (CFU). In an inbound channel chain, the request originates at the network and ends at the CFU. In an outbound channel chain, the request originates at the CFU and ends at the network. The Expeditor Web Container is a CFU. CFUs may have many inbound channel chains leading to them and many outbound channel chains leading from them.

Types of channels

Channels are classified into the following types:

  • Connector channels are those channels closest to the network interface. A connector channel is the lowest channel in the channel protocol stack. An example of a connector channel is a TCP (Transmission Control Protocol) channel.
  • Protocol channels are responsible for abstracting information that is transferred through them. When reading information, a protocol channel will generally parse the information into high-level structures that map to constructs which are specific to the protocol. When writing information, a protocol channel will take information provided in protocol-specific structures and map it to the structures needed by the channel below it in the stack. There may be zero or more protocol channels in the link between the connector channel and the application channel. An example of a protocol channel would be an HTTP (HyperText Transfer Protocol) channel.
  • Application / Acceptor channels are the top-level channels. These channels are generally built on top of specific protocols in order to draw the correct data out of them. An example of an application channels is the one included for the Expeditor Web Container.
  • Filter channels can only appear in the interior of a chain. Filter channels do not perform protocol conversions, and thus should accept and emit the same data type. Filter channels may be used for such applications as logging, SLA enforcement, etc.

The Channel Framework service is responsible for managing the channel framework lifecycle. It is responsible for the correct behavior of channels and channel chains at server startup and shutdown.

Enabling and configuring the Channel Framework using Eclipse extensions

The following steps describe how to enable the Web Container's Channel Framework using Eclipse extensions.
Create an Eclipse plug-in and specify the Eclipse extensions in the plug-in's plugin.xml descriptor. Refer to the Extension Point Schema documentation in Developing Applications for Lotus Expeditor for more information on the extension that you can specify or configure. A sample plugin.xml descriptor file looks like this
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin>	
	<!-- Register the TCP connector channels -->
	<extension point="com.ibm.rcp.channelframework.service.channel">
<channel name="TCP_OUT"		 		  factory="com.ibm.ws.tcp.channel.impl.TCPChannelFactory">
	    </channel>
    </extension>
    
	<extension point="com.ibm.rcp.channelframework.service.channel">      
<channel name="TCP_IN" 				 factory="com.ibm.ws.tcp.channel.impl.TCPChannelFactory">
      		<property name="hostname" 
      				  value="localhost"/>
      		<property name="port" 
      		          value="11111"/>
		</channel>
	</extension>
	
	<extension point="com.ibm.rcp.channelframework.service.channel">      
		<channel name="TCP_IN_2" 
				 factory="com.ibm.ws.tcp.channel.impl.TCPChannelFactory">
      		<property name="hostname" 
      				  value="*"/>
      		<property name="port" 
      		          value="9898"/>
		</channel>
	</extension>
	
	<extension point="com.ibm.rcp.channelframework.service.channel">      
		<channel name="TCP_IN_3" 
				 factory="com.ibm.ws.tcp.channel.impl.TCPChannelFactory">
      		<property name="hostname" 
      				  value="localhost"/>
      		<property name="port" 
      		          value="15000"/>
		</channel>
	</extension>
	
	<extension point="com.ibm.rcp.channelframework.service.channel">      
		<channel name="TCP_IN_4" 
				 factory="com.ibm.ws.tcp.channel.impl.TCPChannelFactory">
      		<property name="hostname" 
      				  value="*"/>
      		<property name="port" 
      		          value="5061"/>
		</channel>
	</extension>
	
	<!-- Register the HTTP protocol channels -->
	<extension point="com.ibm.rcp.channelframework.service.channel">
		<channel name="HTTP_IN" 
				 factory="com.ibm.ws.http.channel.inbound.impl.HttpInboundChannelFactory">
			<property name="persistTimeout" value="5000" />
			<property name="readTimeout" value="5000" />
			<property name="writeTimeout" value="5000" />
			<property name="maxKeepAliveRequests" value="30" />
			<property name="keepAliveEnabled" value="true" />
		</channel>
	</extension>
	
	<extension point="com.ibm.rcp.channelframework.service.channel">
		<channel name="HTTP_OUT" 
				 factory="com.ibm.ws.http.channel.outbound.impl.HttpOutboundChannelFactory"/>
	</extension>
	
	<!-- Register the SSL channels -->
	<extension point="com.ibm.rcp.channelframework.service.channel">
		<channel name="SSL_2" 
				 factory="com.ibm.ws.ssl.channel.impl.WSSSLChannelFactory">
		</channel>
	</extension>	
		
	<!-- Register the UDP connector channels -->
	<extension point="com.ibm.rcp.channelframework.service.channel">
		<channel name="UDP" 
				 factory="com.ibm.ws.udp.channel.impl.UDPChannelFactory"/>
	</extension>
		
	<!-- Register the Web Container application channel -->
	<extension point="com.ibm.rcp.channelframework.service.channel">
		<channel name="WC_APP" 
				 factory="com.ibm.ws.webcontainer.channel.WCChannelFactory"/>
	</extension>
	
	<!-- Register the test channel chains -->
	<extension point="com.ibm.rcp.channelframework.service.chain">
		<chain name="TEST INBOUND CHAIN" 
			   type="INBOUND"
			   group="com.ibm.pvc.webcontainer">
		   	<channel name="TCP_IN" order="0" type="CONNECTOR"/>
			<channel name="HTTP_IN" order="1" type="PROTOCOL"/>
			<channel name="WC_APP" order="2" type="ACCEPTOR"/>
	    </chain>
	</extension>
	
	<extension point="com.ibm.rcp.channelframework.service.chain">
		<chain name="TEST INBOUND CHAIN 2" 
			   type="INBOUND"
			   group="com.ibm.pvc.webcontainer">
		   	<channel name="TCP_IN_2" order="0" type="CONNECTOR"/>
			<channel name="HTTP_IN" order="1" type="PROTOCOL"/>
			<channel name="WC_APP" order="2" type="ACCEPTOR"/>
	    </chain>
	</extension>
	
	<extension point="com.ibm.rcp.channelframework.service.chain">
		<chain name="TEST INBOUND CHAIN 3" 
			   type="INBOUND"
			   group="com.ibm.pvc.webcontainer">
		   	<channel name="TCP_IN_3" order="0" type="CONNECTOR"/>
		   	<channel name="SSL_2" order="1" type="PROTOCOL"/>
			<channel name="HTTP_IN" order="2" type="PROTOCOL"/>
			<channel name="WC_APP" order="3" type="ACCEPTOR"/>
	    </chain>
	</extension>
</plugin>
  • All the SSL properties should continue to be specified in the SSL configuration file of the Web Container. The location of this file is specified using the com.ibm.pvc.webcontainer.ssl.configfile system property. (refer to Configuring SSL for the Web Container).
Note: The SSL channel is ONLY supported on J2SE. It does not work on DesktopEE.

Enabling and configuring the Channel Framework using system properties

Channels, channel factories and channel chains can be configured using the system properties in this section. All system properties must be specified in the Channel Framework configuration file. Refer to Using the Channel Framework configuration file – the location of this file is specified using the com.ibm.rcp.channelframework.configfile system property

Table 4. TCP Channel properties
Option Default Description Java System Property
Factory TCP_FACTORY (both Inbound and Outbound) Responsible for creating or finding a channel. com.ibm.rcp.channelframework.channel.factory.<TCP_channel_name>
Hostname N/A Host name on which the inbound channel will listen. com.ibm.rcp.channelframework.channel.hostname.<TCP_channel_name>
Port N/A Port on which the inbound channel will listen com.ibm.rcp.channelframework.channel.port.<TCP_channel_name>
Max Open Connections

Min - 1

Max - 20000

The maximum number of connections allowed for an inbound channel com.ibm.rcp.channelframework.channel.port.<TCP_channel_name>
Table 5. HTTP Channel properties
Option Default Description Java System Property
Factory

Inbound: HTTP_IN_FACTORY

Outbound: HTTP_OUT_FACTORY

Responsible for creating or finding a channel. com.ibm.rcp.channelframework.channel.factory.<HTTP_channel_name>
Persist timeout 30000 Time to wait for additional requests on a socket (ms) com.ibm.rcp.channelframework.channel.persistTimeout.<HTTP_channel_name>
Read timeout 60000 Time to wait for a read to complete (ms) com.ibm.rcp.channelframework.channel.readTimeout.<HTTP_channel_name>
Write timeout 60000 Time to wait for a write to complete (ms) com.ibm.rcp.channelframework.channel.writeTimeout.<HTTP_channel_name>
Maximum requests per connection 100 Maximum requests allowed on a single HTTP connection com.ibm.rcp.channelframework.channel.maxKeepAliveRequests.<HTTP_channel_name>
Keep-alive connection True Controls whether or not to default to a persistent connection as opposed to a connection that will close after one request/response exchange. com.ibm.rcp.channelframework.channel.keepAliveEnabled.<HTTP_channel_ name>
Table 6. SSL Channel properties
Option Default Description Java System Property
Factory SSL_FACTORY (both Inbound and Outbound) Responsible for creating or finding a channel. com.ibm.rcp.channelframework.channel.factory.<SSL_channel_name>
Protocol SSL Optional. Specifies the protocol to use. com.ibm.ssl.protocol. <SSL_channel_name
Keystore type JKS Optional. Specifies the type of keyStore to use. com.ibm.ssl.keyStoreType.<SSL_channel_name>
Keystore location N/A Mandatory. Specifies the location of keyStore on the file system. com.ibm.ssl.keyStore.<SSL_channel_name>
Keystore password N/A Mandatory. Specifies the password to open the keyStore. com.ibm.ssl.keyStorePassword.<SSL_channel_name>
Truststore type Fully-qualified path to file on the filesystem. Mandatory. Specifies the type of trustStore com.ibm.ssl.trustStoreType.<SSL_channel_name>
Truststore location Plain-text password for keyStore Mandatory. Specifies the location of trustStore on the file system. com.ibm.ssl.trustStore.<SSL_channel_name>
Truststore password Plain-text password for trustStore Mandatory. Specifies the password to open the trustStore. com.ibm.ssl.trustStorePassword.<SSL_channel_name>
Client authentication required false Mandatory. Specifies whether or not the client application requires authentication. com.ibm.ssl.clientAuthentication.<SSL_channel_name>
Enabled cipher suite list N/A Mandatory. Enabled cipher suites. com.ibm.ssl.enabledCipherSuites.<SSL_channel_name>
Table 7. Webcontainer Application Channel properties
Option Default Description Java System Property
Factory WC_APP_FACTORY (both Inbound and Outbound) Responsible for creating or finding a channel. com.ibm.rcp.channelframework.channel.factory.<WC_APP_channel_name>
Table 8. Channel chain properties
Option Default Description Java System Property
Chain name N/A The name of the chain. com.ibm.rcp.channelframework.chain.name.<chain_id>
Chain group com.ibm.pvc.webcontainer. The name of the group the chain belongs to. Should be set to the CFU identifier (for example, com.ibm.pvc.webcontainer). com.ibm.rcp.channelframework.chain.group.<chain_id>
Channel list N/A List of channels in the chain (separated by ‘:' and specified in order starting with connector channel. com.ibm.rcp.channelframework.chain.channelList.<chain_id>
Chain type N/A The type of chain (inbound or outbound) com.ibm.rcp.channelframework.chain.type.<chain_id>
Table 9. Channel Factory properties
Option Default Description Java System Property
Factory class N/A The factory class. Must be a valid classname, class package must be on the bundle classpath com.ibm.rcp.channelframework.factory.class.<factory_name>

Using the Channel Framework configuration file

The following steps describe how to configure the Web Container's Channel Framework support.
Create the Channel Framework configuration file. Refer to Enabling and configuring the Channel Framework using system properties for more information on properties that can be specified or configured. The location of the Channel Framework configuration file is specified using the com.ibm.rcp.channelframework.configfile property.
The sample Channel Framework configuration file below shows how to configure two separate HTTP / HTTP channel stacks:
# factory properties
com.ibm.rcp.channelframework.factory.class.HTTP_TEST_FACTORY=com.ibm.ws.http.channel.inbound.impl.HttpInboundChannelFactory
com.ibm.rcp.channelframework.factory.class.TCP_TEST_FACTORY=com.ibm.ws.tcp.channel.impl.TCPChannelFactory
com.ibm.rcp.channelframework.factory.class.WC_TEST_FACTORY=com.ibm.ws.webcontainer.channel.WCChannelFactory
com.ibm.rcp.channelframework.factory.class.SSL_TEST_FACTORY=com.ibm.ws.ssl.channel.impl.WSSSLChannelFactory

# channel properties for TCP channel(s)
com.ibm.rcp.channelframework.channel.factory.TCP_TEST=TCP_TEST_FACTORY
com.ibm.rcp.channelframework.channel.port.TCP_TEST=9999
com.ibm.rcp.channelframework.channel.hostname.TCP_TEST=localhost
com.ibm.rcp.channelframework.channel.factory.TCP_TEST_2=TCP_TEST_FACTORY
com.ibm.rcp.channelframework.channel.port.TCP_TEST_2=12222
com.ibm.rcp.channelframework.channel.hostname.TCP_TEST_2=localhost

# channel properties for HTTP channel(s)
com.ibm.rcp.channelframework.channel.factory.HTTP_TEST=HTTP_TEST_FACTORY
com.ibm.rcp.channelframework.channel.persistTimeout.HTTP_TEST=7500
com.ibm.rcp.channelframework.channel.readTimeout.HTTP_TEST=7500
com.ibm.rcp.channelframework.channel.writeTimeout.HTTP_TEST=7500
com.ibm.rcp.channelframework.channel.maxKeepAliveRequests.HTTP_TEST=7500
com.ibm.rcp.channelframework.channel.keepAliveEnabled.HTTP_TEST=true
com.ibm.rcp.channelframework.channel.factory.HTTP_TEST_2=HTTP_TEST_FACTORY
com.ibm.rcp.channelframework.channel.persistTimeout.HTTP_TEST_2=7500
com.ibm.rcp.channelframework.channel.readTimeout.HTTP_TEST_2=7500
com.ibm.rcp.channelframework.channel.writeTimeout.HTTP_TEST_2=7500
com.ibm.rcp.channelframework.channel.maxKeepAliveRequests.HTTP_TEST_2=7500
com.ibm.rcp.channelframework.channel.keepAliveEnabled.HTTP_TEST_2=true

# channel properties for SSL channel(s) (remaining SSL properties including 
# keystore, truststore locations are defined in the SSL config file)
com.ibm.rcp.channelframework.channel.factory.SSL_TEST=SSL_TEST_FACTORY

# channel properties for Webcontainer application channel(s)
com.ibm.rcp.channelframework.channel.factory.WC_TEST=WC_TEST_FACTORY
com.ibm.rcp.channelframework.channel.factory.WC_TEST_2=WC_TEST_FACTORY

# chain properties
com.ibm.rcp.channelframework.chain.name.1=TEST HTTP CHAIN
com.ibm.rcp.channelframework.chain.group.1=com.ibm.pvc.webcontainer
com.ibm.rcp.channelframework.chain.channelList.1=TCP_TEST:HTTP_TEST:WC_TEST
com.ibm.rcp.channelframework.chain.type.1=INBOUND

com.ibm.rcp.channelframework.chain.name.2=TEST HTTPS CHAIN
com.ibm.rcp.channelframework.chain.group.2=com.ibm.pvc.webcontainer
com.ibm.rcp.channelframework.chain.channelList.2=TCP_TEST_2:SSL_TEST:HTTP_TEST_2:WC_TEST_2
com.ibm.rcp.channelframework.chain.type.2=INBOUND
  • All the SSL properties should continue to be specified in the SSL configuration file of the Web Container. The location of this file is specified using the com.ibm.pvc.webcontainer.ssl.configfile system property. (refer to Configuring SSL for the Web Container).
  • Launch the Lotus Expeditor Runtime. The Web Container will then proceed to initialize the Channel Framework provider and use the provider to configure each channel specified in the configuration file and subsequently enable the channel chains also specified in the configuration file. All SSL properties will also be provided to the Channel Framework provider.
  • Access any registered and active web application on the specified ports.

Configuring the Portlet Container

The Portlet Container provides a runtime environment for JSR 168 portlet applications in which JSR 168 portlets can be instantiated, used and finally destroyed.

The Portlet Container allows users and developers alike to access and run portlet applications either disconnected (offline) or connected (online).

No configuration of the Portlet Container is necessary.

The Portlet Container is an additional extension processor which leverages Web Container functionality and reuses the Web Container settings (server address and server port, for example). See Configuring the Web Container for more information.

You can change the images and style sheet used by the portlet container when rendering portlets. See Configuring the Portlet Container branding for more information.

Configuring portlet preferences

You can remotely manage and update the default set of portlet preferences.

The Portlet Container uses Eclipse Preferences to persistently store modified and updated portlet preferences. See Managing Eclipse preferences for more information about how to remotely manage Eclipse preferences.

Configuring mobile Web services

No local configuration is needed to deploy mobile Web services. Mobile Web services providers listen on the same port of the Web container.

Note that if a mobile Web services client application results in a runtime exception with the message Parsing of the specified WSDL failed, followed by an explanation, you must ensure that the WSDL is accessible through a browser. This exception can be the result of a firewall message in HTML-form requiring authentication, or it can be due to an invalid WSDL. If the WSDL is valid, authenticating with the firewall before running the mobile Web services client application or hosting the Web service or WSDL outside the firewall might be needed.

Configuring Apache Axis Web services clients

Apache Axis is an open source implementation of the SOAP. It has been enabled to provide runtime support for the JAX-RPC based clients in Lotus Expeditor.

Configuring Apache Axis client proxy settings

Apache Axis client runtime requires that you set VM properties when connecting through an HTTP proxy.

Apache Axis client runtime requires the following JVM properties to be set when connecting through an HTTP proxy. Apache Axis client does not recognize the proxy settings provided by the Eclipse preferences in the Lotus Expeditor environment.
  • -Dhttp.proxyHost – Host name of proxy server
  • -Dhttp.proxyPort -- Port on server of proxy
  • -Dhttp.proxyUser -- Optional user name for proxy authentication
  • -Dhttp.proxyPassword -- Optional proxy server password

Configuring managed settings

The managed settings framework allows you control over the runtime behavior of client applications by letting you set the values of the settings that the applications are reading out of the Eclipse preference store.

If you also designate these settings as read-only, any changes that the client applications make to the settings are prevented or are later overwritten with your values, depending on how the client accesses the settings. If the client program knows about managed settings and accesses them through the ManagedSettings Eclipse preference scope, any changes to read-only settings are prevented. For other plug-ins, which access the settings in the traditional way, changes can occur but are later overwritten with your values. Updates are run regularly to add any of your new settings or settings changes to the preference store on the client.

The managed settings framework can retrieve policy, preferences, or any other name and value pairs from any back-end system for which there exists a managed settings provider. Providers contain the knowledge of the specific back-end system. Lotus Expeditor includes providers to retrieve settings both from Portal Policy Manager and from an XML file residing on an HTTP server. If there is no provider available for your back-end system, you can write your own. See Adding a managed settings provider for more information.

You can manage client settings by completing the following procedures:
  1. Specifying settings
  2. Configuring providers
  3. (Optional) Setting the managed settings update schedule
  4. Ensuring that the managed settings plug-in gets started

Specifying settings

You can specify the desired values of client setting using the back-end administration system of your choice.

If your back-end administration system is Portal Policy Manager, you can use the Policy Type Editor for Eclipse Preferences to set the values. See Managing Rich Client Preferences using the Policy Type Editor for Eclipse Preferences for more information. All values from the Portal Policy Manager are treated as if they are specified as read-only. If your back-end administration system is IBMLotusDomino, you specify your settings in the policy subsystem of the Lotus Domino administration client.

Eclipse preferences are accessed using a qualifier (typically a plug-in name), and optionally a scope, which determine the storage location of the preference. To have your settings values read by the client applications, they need to be stored in the same place that the client is looking for them. There are two possible ways to determine this information:
  • Look in the documentation of the application to see if a list of settings has been published or to request a list from the application developer.
  • Figure out the names of the qualifiers and settings yourself by changing values in the preference panels and other user interface controls provided by the application and examining the resulting changes in the Eclipse Preference store.
The managed settings framework enables administrators to control settings in the following scopes:
  • Configuration – Preferences that are stored per installation of the platform. They are shared between workspaces.
  • Instance – Preferences that are stored per workspace or per running instance of the platform.
  • It might be possible for custom scopes to be managed as well, depending on their implementation.

ManagedSettingsScope is a custom scope, for use by the managed settings framework and managed settings-aware applications. Its data is obfuscated to discourage user tampering. Applications that access their settings using this scope instead of using the standard Eclipse scopes are prevented from changing read-only settings. Read-only settings are stored in the managed settings scope and the associated standard scope.

A Setting Group is a group of related settings. When the managed settings framework retrieves a setting from a back-end system, the setting group it belongs to is the unit that is retrieved, not the individual setting. The structure of a settings group depends on the back-end system that generates the settings contained by it and the implementation of the provider associated with that back-end system. For example, for the Portal provider, a setting group is equivalent to a policy type.

If you are specifying managed settings in the Portal Policy Manager using the Policy Type Editor for Preferences, there are separate attributes for scope and qualifier that you can set explicitly. For instructions, see Managing Rich Client Preferences using the Policy Type Editor for Eclipse Preferences. For this provider, a setting group maps to the PreferenceSet, which maps to the policy name. When setting up your preference sets, it is important for deletion tracking that all settings with the same qualifier go in the same preferenceSet. All settings that are retrieved from the Portal Policy Manager are treated as read-only.

If you are specifying managed settings with the XML File provider, make the setting group name match the qualifier (typically the plug-in ID). If the scope is not instance scope, add a prefix to the name of the scope plus a forward slash character (/) to the name of the setting group.

For example:
<settingGroup name="org.eclipse.ui" lastModDate="20060131">
      <setting name="showIntro" value="false" isLocked="false"/>
</settingGroup>

<settingGroup name="configuration/com.isv.my.plugin"" lastModDate="20060131">
      <setting name="use_large_icons" value="true" isLocked="true"/>
      <setting name="sortOrder" value="descending" isLocked="false"/>
</settingGroup>
If isLocked is specified as true, the setting is treated as read-only. For more information about the XML file provider, see Configuring the XML file provider.

If you are using a different back-end administrative settings system and your environment allows you to control the name of the setting groups (for whatever the concept of a setting group happens to be for that system), it is most efficient to name the setting group after the qualifier that is used to access the settings on the client. If the settings need to be stored in a scope other than instance scope,add a prefix to the scope name and a forward slash character (/) to the name.

For example, if you specify a setting group name of org.eclipse.help.ui, the framework stores all the settings for that group in instance scope using a qualifier of org.eclipse.help.ui. If you specify a setting group name of configuration/org.eclipse.core.internal.preferences.osgi, the framework stores all the settings for that group in configuration scope using a qualifier of org.eclipse.core.internal.preferences.osgi.

If it is not feasible to name the setting group to match the qualifier, you can specify the qualifier by adding a prefix to each setting name, separating the qualifier, and setting name with a forward slash character (/). For example, you could name the setting group, All My Eclipse Preferences and name one of its settings, org.eclipse.core.help.base/bookmarks. You could name another setting, org.eclipse.ui/showIntro. As a result, both settings, bookmarks and showIntro are retrieved together as part of the same setting group, but the former is stored with a qualifier of org.eclipse.core.help.base and the latter with a qualifier of org.eclipse.ui.
  • Adding a prefix to the scope to the setting group name – The scope applies to all the settings in the setting group. For example: configuration/org.eclipse.core.runtime
  • Adding a prefix to the scope to the setting name – If youadd a prefix to the scope to an individual setting, you must also specify the qualifier for the setting, even if it matches the setting group name. For example: configuration/org.eclipse.core.help.base/bookmarks
The following table contains example values of settings specified by an administrator:
Table 10. Example values
Setting name Group/qualifier = com.isv.existing.plugin
use_large_icons true
sort_order descending
com.isv.existing.plugin.helper/color_scheme ocean
configuration/com.isv.existing.plugin/max_windows 5
The following resulting locations are created in the standard scopes of the Eclipse Preference store based on the administrator settings in the table:
Root 
|-	instance 	
  |- com.isv.existing.plugin  
    |- use_large_icons = true   
    |- sort_order = descending  
  |- com.isv.existing.plugin.helper   
    |- color_scheme = ocean 	
|-configuration   
  |- com.ibm.existing.plugin      
    |- max_windows = 5 

If this naming scheme for specifying scopes and qualifiers is not feasible in your back-end settings system, for instance, if there is a character limit that is too short, you can write your provider so that it translates between the format that you are able to use and the format that is described.

Any forward slash characters (/) in your setting name other than those characters that delineate the scope and qualifier are treated as subnodes of the qualifier. If your intent is to have a literal forward slash characters (/) in the setting name, you need to use two forward slash characters (//) instead.

Limitations on qualifiers

The following are the limitations on qualifiers:
  • It is important that a qualifier does not exist in more than one setting group.
  • Qualifier names cannot be "instance," "configuration," "default," "ManagedSettings," or any other names that are used as scope names.

Update behavior

If you remove settings from the setting group, they remain on the client, but any read-only settings are changed to readable. If you remove a whole setting group, all the settings in that setting group remain on the client, but any read-only settings are changed to readable.

If you change the value of a non-read-only setting and then user has modified the setting, your update is not applied, unless you also change the setting to read-only.

Configuring providers

To plug in to the managed settings framework, the back-end management system that populates the Eclipse preference store with the settings for the application must have a corresponding managed settings provider.

A managed settings provider is a plug-in that knows how to pull settings from an associated back-end management system and format them appropriately for the framework to read them. Lotus Expeditor Client provides providers for settings specified by the Portal Policy Manager and for settings that are specified in XML files. If your application gets its preference settings from a back-end system other than WebSphere Portal or an XML file, you can create a custom provider for it. See Adding a managed settings provider.

You must configure the file provider associated with settings specified in XML files. For details, see Configuring the XML file provider.

You do not need to configure the provider for the Portal Policy Manager, which is the back-end administrative system used by the WebSphere Portal-administered client. Instead, you must create an account that identifies the WebSphere Portal Server and stores authentication information for connecting to it. See Managing accounts for more information.

Configuring the XML file provider

The XML file provider is responsible for getting the preference settings from an XML file. The file provider needs to have an XML file containing the managed setting data and must know the location of that XML file.

To configure the file provider:
  1. Format the XML file as follows:
    • It must contain a <ManagedSettings> element that contains one or more <settingGroup> elements. Each <settingGroup> element must contain one or more <setting> elements.
    • Each <settingGroup> tag must have the following attributes:
      • name – Use the same name as the qualifier (typically the plug-in name, but it can be anything) that its settings are associated with.
      • lastModDate – Specify the date using the java.text.SimpleDateFormat format. The syntax is YYYYMMDDThhmmssZ, where YYYY=year, MM=month, DD=day, hh=hours, mm=minutes, ss=seconds. The values to the right of the T are optional.
        Important:
        Every change to a setting group must be accompanied by a change to the lastModDate attribute, or the new values are not updated. If no lastModDate is specified, the values are always updated, even if they are not new.
    • Each <setting> tag must have the following attributes:
      • name – Use a name that identifies what the setting does.
      • value – Provide a default value for the setting.
    • Each <setting> tag might also have the following attributes:
      • isLocked – Boolean. The default value is true. If true, the setting is read-only and any changes that a user or application makes to the value set by you, the administrator, are prevented or later overwritten. If this attribute is set to false, the administrator setting is treated as a default value that can be changed.
      • overwriteUnlocked - Boolean. The default value is false. By default, a setting that is specified as being unlocked is treated as a default and does not overwrite any existing value on the client. This approach avoids undoing changes that the user might have legitimately made. If this setting is set to true, however, the unlocked value is overwritten with this new value even if it means clearing the existing value of the user.
    • For example:
      <ManagedSettings>
      
        <settingGroup name="com.ibm.workplace.mail.policy" lastModDate="20060131">  
            <setting name="alwaysEncryptEmail" value="true" isLocked="true"/>
            <setting name="saveCopyinSentFolder" value="false" isLocked="false"/>
        </settingGroup>
      
        <settingGroup name="desktop_settings" lastModDate="20060131">  
            <setting name="logOffAfter" value="30" isLocked="true"/>
            <setting name="autoSaveAfterNMinutes" value="5" isLocked="true"/>
        </settingGroup>
      
      </ManagedSettings>
      See the com.ibm.rcp.managedsetttings.provider.file plug-in to see the schema.
  2. Set the initial location of the XML file in the plugin_customization.ini file using a key of com.ibm.rcp.managedsettings.provider.file/URL.
    For example:
    com.ibm.rcp.managedsettings.provider.file/URL=http://www.ibm.com/settings.xml
    or
    com.ibm.rcp.managedsettings.provider.file/URL=file://c:/data/mysettings.xml
    You can update the plugin_customization.ini file in the desktop/deploy/ directory on a CD-structure or the one provided with the download applet or portlet using the instructions provided with it.
  3. If you would like to later change the URL for the file provider, you can update the existing XML file to add a new setting group of com.ibm.rcp.managedsettings.provider.file and a setting of URL. The next update runs on the existing URL, but the update after that runs with the new URL. If the new URL is unreachable at the time of the update that is setting it, it is not saved and the original URL continues to be used. The URL is not changed until it is updated at a time that the URL is reachable.
    Note: If the XML file is being hosted by an HTTP server on which authentication has been enabled and there is no associated account set up for the server, the user is prompted for a name and password the first time that the provider runs. Because the provider runs in the background, the user is likely to be confused by this display. You can prevent the authentication prompt from displaying by including code in the application that creates an account for this URL during its setup. See Managing accounts for more information.
    Note: During communication with the portal, the default policy provider assumes that the portal is configured with the default custom directory. When retrieving updates for the specified user, the default provider uses the default dn (Distinguished Name) suffix for the default directory.
    "uid=<username>,o=Default Organization"
    If the portal is configured with a different user directory, however, the default dn might not work. To provide a directory-specific dn suffix, you can update the plugin_customization.ini file using a key of com.ibm.rcp.managedsettings.provider.portal/dnSuffix.

    For example:

    com.ibm.rcp.managedsettings.provider.portal/dnSuffix=ou=customers,dc=ibm,dc=com

Federation

Managed settings allow for the simultaneous use of more than one provider.

For instance, you could specify the setting values for one plug-in in the Portal Policy Manager and for another in the XML file provider. The potential exists, though, that the same setting group or qualifier can be defined on both the Portal Policy Manager and in the XML File. This approach is highly discouraged, both because of the ambiguity and for efficiency reasons. If you determine that this approach is happening, fix it as soon as possible. To handle this situation, framework forces the results to be deterministic by using the weight of the provider to determine which setting value is applied. The lowest weight wins. You can determine the default weight of the providers by looking in the ManagedSettingProvider extension point in their plugin.xml files. The default weight of the file provider is set to 300. The default weight of the Portal provider is 200. If necessary, you can change the weight by creating a managed setting for it, using a qualifier of com.ibm.rcp.managedsettings and a setting name of <provider_id (typically plug-in ID)>-weight.

Configuring the managed settings update schedule

The framework uses a scheduled background job to call each provider and tell it to retrieve updated settings from its associated back-end systems and then pass them to the framework to update the values stored on the client.

The provider mechanism also includes a mechanism for a provider to inform the framework when it has new updates, instead of waiting for the poll interval to elapse. If the provider you are using has this capability, you do not need to be concerned about this setting. Neither of the providers shipped with Lotus Expeditor have this capability, but other providers could.

By default, the scheduled update job runs every 720 minutes (12 hours). To change this value, do one of the following:
  • If your settings are being populated by the Portal Policy Manager, use the administrative console to edit the value of the com.ibm.rcp.managedsettings/UpdateIntervalInMinutes setting.
  • If your settings are being populated by the file provider, create a setting group called com.ibm.rcp.managedsettings and a setting of UpdateIntervalInMinutes.
  • If your settings are being populated by a different back-end system, create a name-value pair to set the update interval. Use a qualifier of com.ibm.rcp.managedsettings and a setting of UpdateIntervalInMinutes.

Ensuring that the managed settings plug-in gets started

For your settings to be applied to the client, the plug-in com.ibm.rcp.managedsettings must be started at runtime.

If you are using the Portal-Managed client, this application happens automatically. It also happens automatically if any of the plug-ins in the application call any of the methods in the managed settings plug-in. If you are providing setting values for an application that has no managed settings-aware plug-ins, however, you need to ensure that the plug-in gets started. To do so, use one of the life cycle plug-ins. See Managing life cycle for more information.

Configuring the network layer

You can configure the platform proxy settings and the network status polling interval using Eclipse preferences.

Configuring the network status polling interval

Update the polling interval to configure the network layer to your environment.

If the network is down, the network layer polls the system to determine when the network is back up. The polling interval preference value is com.ibm.rcp.net.http/local_resource_monitor_interval.

See Managing Eclipse preferences for more information about how to query or modify preference values.

Note: If your system is connected using a device emulator, such as VMWare, or other connections that share your LAN or wireless network connection, the netstatus API always returns true even after you disconnect the LAN cable and wireless. This step occurs because of the existence of the virtual adaptor. If you would like your application to be notified of a true offline state (or plan to disconnect the system), go to Start > My Network Places, right-click Properties, and disable the shared connections. The Netstatus API returns the correct status.

Configuring the platform proxy settings

Proxy settings are global, that is, the whole runtime shares the same proxy settings. The HTTP/HTTPS connection is stateless and uses the proxy settings set when the application opens the connection.

The proxy settings are defined as Eclipse preferences in IBM Lotus Expeditor and can be set manually (programmatically or in the plugin_customization.ini file) or through the Network Connections preference page. For information on managing these Eclipse preferences, see Managing Eclipse preferences.

Configuring platform proxy settings manually

The proxy settings defined as Eclipse preferences in IBM Lotus Expeditor can be set manually, either programmatically or in plugin_customization.ini.

The following Eclipse preferences are defined:
com.ibm.rcp.net.http/http.ProxyHost
Indicates the proxy server host. The String default is null.
com.ibm.rcp.net.http/http.ProxyPort
Indicates the proxy server port. The integer default is 80.
com.ibm.rcp.net.http/http.nonProxyHosts
Indicates the hosts to connect directly to and not through the proxy server. The value can be a list of hosts, each separated by a vertical bar (|). For example, http.nonProxyHosts=“www.foo.com|localhost".
com.ibm.rcp.net.http/http.IsSecureProxy
Indicates whether the proxy needs user ID and password. The Boolean default is false.
com.ibm.rcp.net.http/http.manualProxyEnabled
Indicates that a proxy was manually configured.
Note: Both http.manualProxyEnabled and http.browserSettingsEnabled might not be set to true at the same time. For more information, see Using Windows proxy settings.
com.ibm.rcp.net.http/http.browserSettingsEnabled
Specifies that the client uses the Windows system proxy settings. For more information, see Using Windows proxy settings.
Note: Both http.manualProxyEnabled and http.browserSettingsEnabled might not be set to true at the same time.

For secure proxy servers, credentials can be specified through the Network Connections preference page or programmatically. For more information, see Configuring the proxy settings for Lotus Expeditor.

NTLM proxy configuration

NTLMv1 and NTLMv2 proxy authentication is supported by Expeditor on Windows platforms only.

NTLM proxy authentication supports integrated Windows authentication. That is, the Windows credentials of the current user are automatically obtained from the platform and used for authentication. For this reason, the user must not specify server credentials in the Accounts preferences page, and the com.ibm.rcp.net.http/http.IsSecureProxy preference is set to false.

A user might choose not to take advantage of integrated authentication and instead specify the user name and password for the NTLM proxy in accounts. The account must be configured with the following values:
  • Account name = PROXY.ACCOUNT
  • Auth type = PROXY.NTLM
  • User name = user name and domain for NLTM proxy server in the following format:

    DOMAIN\username Password = password for the preceding user name

A user is prompted for credentials only if the credentials provided in Accounts are invalid or if the credentials (provided or automatically obtained) are out of sync with Active Directory.

For information about programmatically configuring proxy settings, see .

Using Windows proxy settings

On Microsoft Windows systems, the user can also configure the client to use the Windows system proxy settings that can be configured in the operating system or Internet Explorer.

To use the proxy settings configured in Windows, the user can select the "Use browser settings" option on the Network Connections preference page. This option indicates that the Windows system browser proxy configuration can be used by the platform.

Note: The user can also set this preference in plugin_customization.ini. For more information, see Configuring platform proxy settings manually.

If the platform is configured to use browser settings, a user is prompted for credentials for any proxy server that requires authentication. Authentication information is not stored in Accounts.

An NTLM proxy can be configured manually (as described in Configuring platform proxy settings manually) or can be configured through the Windows system browser.

Configuring the Web browser application

You can configure the Integrated Browser Application with a defined Eclipse preference for your environment. For example, you can specify not to display the Web Browser preference page in the IBM Lotus Expeditor Preference dialog.

The following Eclipse preferences are defined:
com.ibm.rcp.ui.browser.launcher/showPreferencePage
Specifies whether to display the Web Browser preference page in the IBM Lotus Expeditor Preference dialog. The default Boolean value is true.
com.ibm.rcp.ui.browser.launcher/allowUserDefinedHomePage
Specifies whether to display the "set home page" UI on the Web Browser preference page. The default Boolean value is true.
com.ibm.rcp.ui.browser.launcher/adminHomePage
Indicates the home page set by the administrator. The default string value is “about:blank”.
com.ibm.rcp.ui.browser.launcher/enableApplet
Specifies whether to enable Java2 applet support. The Boolean default is true.
com.ibm.rcp.ui.browser.launcher/ENABLE_HISTORY
Specifies wheter to enable the browser history support or not. The default value is true.
com.ibm.rcp.ui.browser.launcher/PERSISTING_HISTORY_DAYS
Specifies the days that browser history can be kept

See Managing Eclipse preferences for more information about how to query or modify preference values.

Configuring platform synchronization

Use the Lotus Expeditor platform to manage and configure synchronization.

The Synchronization page provides users the ability to quickly view all the synchronizable applications with their synchronization status. Each synchronizable application is displayed in a row with its name, on and off state, priority, last-run time, scope, summary, server, and status. This page also provides users the ability to start and stop synchronization and a quick way to set synchronization schedules and application-specific options.

The Synchronization Schedules page is in the platform preferences dialog. It provides users the ability to set two sets of schedules for normal and high-priority applications, respectively. It also provides the synchronization triggers settings applied to all the synchronizable applications.

You must meet these prerequisites to synchronize:

Enabling synchronization and changing priority

If an application that can be synchronized is installed, you can open the Synchronization page from the Launcher to enable or disable synchronization or change priority of an application.

Click the check box under the Enabled column for an application to enable or disable the synchronization of it.

Click the check box under the High Priority column for an application to change between High Priority and Normal Priority for an application. You can also make this selection by right-clicking the application and selecting (or clearing) Use the High-Priority Schedule for this Application.
Note: Synchronization is not presented as an option in the Launcher when there are no items to synchronize. There are items to synchronize when there is an available WebSphere Portal Server that is configured correctly in platform preferences.

Configuring auto-synchronization schedules and triggers

Open the platform preferences dialog, and click the Synchronization page to configure the auto-synchronization schedules and triggers.

You can check and clear the boxes separately to enable and disable the following schedules and triggers:

  • Normal-priority synchronization schedule
  • High- priority synchronization schedule
  • Synchronize when I start the client trigger
  • Synchronize when I reconnect after being disconnected trigger
  • Synchronize when I go offline trigger
  • Synchronize when I shut down the client trigger

Check Prompt me to have a confirmation dialog prompt displayed before the platform performs synchronization. You can also personalize the schedules by changing the time settings, repeat setting, and days-of-the-week settings.

Configuring platform security

The desktop client platform can use either the IBM J9 Virtual Machine (VM) that implements the Java specifications with DesktopEE class libraries or the IBM J9 VM with the Java 2 SE 5.0 class libraries. The security configuration options are different depending on the VM that is used.

The Lotus Expeditor Client installs the J9 with DesktopEE as the default VM, and Java 2 SE 5.0 can be installed later. Other products that use this platform might provision only Java 2 SE 5.0 and not DesktopEE.

When using the Lotus Expeditor Client on devices, DB2e can use SSL while synchronizing with a server by specifying https in the connection URL.

Refer to the following URL for information about the security capabilities of the VM on Microsoft Windows:

http://www-128.ibm.com/developerworks/java/jdk/security/50/secguides/securityguide.win32.html

Refer to the following URL for information about the security capabilities of the VM on Linux:

The following URL is the index page for information about the security aspects of the IBM J2SE 5 VM:
http://www-128.ibm.com/developerworks/java/jdk/security/50/secguides/securityguide.win32.html 

The use of JCE within the platform follows the standard patterns of JCE usage.

Because the platform uses multiple inbound and outbound communication mechanisms, depending on the type of communication required, there are specific configuration steps needed to configure JSSE to support SSL communications. Refer to the appropriate section according to the wanted communication mechanism.

The Lotus Expeditor Client does not support the use of Java 2 Security to grant or prevent code access based on identity.

Configuring for DesktopEE

The following Ciphers are provided using JCE in DesktopEE:
  • AES
  • DES
  • DESede
  • Blowfish
  • PBEWithMD5andTripleDES
  • PBEWithMD5andDES
The following CipherSuites are supported for SSL Connections:
  • SSL_RSA_WITH_3DES_EDE_CBC_SHA
  • SSL_RSA_WTH_DES_CBC_SHA
  • SSL_RSA_WITH_NULL_SHA
  • SSL_RSA_WITH_NULL_MD5
  • SSL_RSA_WITH_RC4_128_SHA
  • SSL_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_AES_128_CBC_SHA

The JAAS component provides a means for principal-based authentication and authorization

The DesktopEE key tool can only be used to create or operate on JKS keystores. You cannot use it to build JCEKS keystores. JCEKS keystores are currently not supported on DesktopEE.

DesktopEE contains some preinstalled certificates in the file lib\security\cacerts. This file is preinstalled with a number of root CAs and is used for SSL server certificate validation, signed JARverification, and midlet verification.

Switching from DesktopEE to J2SE

See Changing to a different runtime and class library for information about switching from DesktopEE to J2SE.

Keystore considerations when switching VMs

Keystore files that are created by the Java 2 SE 5.0 VM are not compatible with DesktopEE. Similarly, keystore files created with DesktopEE are not compatible with Java 2 SE 5.0. For this reason, IBM Lotus Expeditor maintains one keystore file for each VM. Because of this arrangement, when switching VMs, you must reset all the passwords that were stored in the keystore of one VM and the keystore password itself. None of the data stored in keystore file of one is transferred to the keystore file of the other VM. It is important to note that it is possible to have two different sets of stored credentials; one is accessible only to DesktopEE, and one is accessible only to Java 2 SE 5.0.

Specifying the default platform login configuration

A login configuration tells the application which LoginModule to use to authenticate users. A LoginModule describes the interface implemented by authentication technology providers.

The Lotus Expeditor Client defines a default configuration that can be used if no alternate configuration is defined by the application.

It also provides the following platform login configurations that you can use:
  • SSO-KS – Stacks the SSOLoginModule on top of the KeyStoreLoginModule class to support single sign-on to the keystore.

Follow these steps to specify third-party login configurations:

In the plugin_customization.ini file in the <install dir>/rcp directory, set the value for the following preference:
  • com.ibm.rcp.security.auth/loginConfigName – Specifies the name of the Configuration to use by default when performing a platform login using the ILoginContext.login() method. The default value for Lotus Expeditor is SSO-KS.
For example:
com.ibm.rcp.security.auth/loginConfigName=SSO-KS

Configuring SSL for the platform

If you need to use Secure Sockets Layer (SSL) with a self-signed test certificate or a certificate that does not have a root certificate contained in the default manager keystore, you are prompted, denied, or allowed, depending on how you configure your managed preferences value for com.ibm.rcp.security.jceproxy/ssl.unknowncert.action.

Three possible values are as follows:
ALLOW
Pass the SSL connection for sites with untrusted certificates.
DENY
Fail the SSL connection for sites with untrusted certificates.
PROMPT
If Lotus Expeditor is running in headless mode, treat PROMPT equal to DENY. If Lotus Expeditor is running with UI enabled, the user is prompted with the following choices:
  1. Do not trust this certificate or its certifying authority. Stop the current operation.
  2. Trust this certificate for this session; only.
  3. Trust this certificate.
The default value is PROMPT. To change this value, you must change the value of the com.ibm.rcp.security.jceproxy/ssl.unknowncert.action Eclipse preference. See Managing Eclipse preferences for setting preference information.

The Lotus Expeditor trust manager is configured by default to support SSL using the cacerts keystore file. Additionally, the trust manager looks into the platform keystore. To reconfigure the default configuration, set the following system properties. See Configuring Java system properties for information on how to set the properties.

You can specify the following properties for the client:

		-Djavax.net.ssl.keyStore=path_to_keystore_file 
		-Djavax.net.ssl.keyStoreType=keystore_type 
		-Djavax.net.ssl.keyStorePassword=keystore_password
		-Djavax.net.ssl.trustStore=path_to_truststore_file 
		-Djavax.net.ssl.trustStoreType=truststore_type 
		-Djavax.net.ssl.trustStorePassword=truststore_password

For more information about setting these properties, and configuring SSL for the VM, refer to the following URL:

Configuring SSL for the Enterprise Management Agent

Secure Sockets Layer (SSL) connections are based on the existence of digital certificates to promote secure data exchange between server and client. In Lotus Expeditor, the Enterprise Management agent supports both normal and SSL connections between the client and a Lotus Expeditor server. We recommend that you purchase commercial certificates for which public key certificates are already available on the client devices. This purchase greatly simplifies using secure connections because new certificates do not have to be deployed to the clients. You can also use self-signed certificates that you create. The procedures for deploying certificates to desktops and devices are different.

Configuring for the desktop

If you plan on running the Enterprise Management Agent application to connect to a Client management server located behind a secure URL, for example HTTPS, you must set up the Lotus Expeditor Client with an appropriate default configuration.

The Enterprise Management Agent runtime does not provide any SSL-specific configuration capabilities and relies on the default platform settings.

Refer to Configuring SSL for the platform for more information.

Configuring for devices

Although the installation steps are different for various device platforms, you can use the same certificate to support all platforms.

To configure SSL for Microsoft Windows Mobile 5.0 or Microsoft Windows CE 5.0, you must create a certificate and deploy it to both servers and clients.
  1. For instructions on creating certificates, refer to Obtaining a certificate in Using Lotus Expeditor Server and using the IBM Key Management Utility (ikeyman) tool.
    Note:
    • When you create the certificate, the value for the Common Name (cn= value) field must match the server address the Enterprise Management Agent uses to connect with the Client Management server.
    • Ensure that the dates for which the certificate is valid are correct.
  2. To configure the Lotus Expeditor Server for SSL communication, refer to Configuring Device Manager for SSL and Securing Lotus Expeditor Server for SSL in Using Lotus Expeditor Server.
  3. You must distribute the certificate created by ikeyman to the client devices. Use the keytool.exe from the Lotus Expeditor Client for Desktop to import the certificate into a cacerts file that can then be distributed to clients. This file replaces the existing file in the \eclipse\plugins\com.ibm.pvc.wece.device.win32.arm_6.2.0-<date>\jre\lib\security folder, so the file can be managed to not destroy any certificates previously deployed.
  4. After the certificate has been deployed to the client, the user can open Application ManagerPreferences, select the HTTPS option, and fill in the corresponding account information.
  5. The user can press the Test Connection button to make sure that entered information is correct and click Command > OK to connect with the Client Management server.

Configuring client-side SSL support

To access a server that requires client certificate authentication for SSL connections, the Lotus Expeditor Client keystore must contain a personal certificate signed by an authority that is trusted by that server.

The self-signed certificate of the client must be in the platform keystore, the JRE keystore, or another keystore that is specified with system properties at runtime:

  • javax.net.ssl.keyStore
  • javax.net.ssl.keyStorePassword
  • javax.net.ssl.keyStoreType

The platform keystore is located in the Lotus Expeditor client workspace after the client has been initialized. The password to this keystore is the Base64 encoded version of the password you use to log in to your client. The platform keystore created in the DesktopEE environment is not compatible with the platform keystore created in the J2SE environment. It is recommended that you access the platform keystore programmatically. More information on how to programmatically access the platform keystore can be found in the Developing Applications for Lotus Expeditor documentation.

The JRE keystore can be found at <java_home>/lib/security/cacerts, with a default password of "changeit".

Configuring SSL for Web Services

If you plan on running Web Services applications that connect to Web Services located behind a secure URL, for example HTTPS, you must set up Lotus Expeditor Client with an appropriate default configuration.

The Web Services runtime does not provide any SSL-specific configuration capabilities and relies on the default platform settings.

Refer to Configuring SSL for the platform for more information.

Configuring SSL for the Web Container

This section describes how to configure SSL for the Web Container.

When using Lotus Expeditor on the desktop, perform the following steps to enable the Web Container to serve requests using a secured socket:

  1. Configure the Web Container.
    1. Create an SSL configuration file and set the following properties
      Table 11. SSL configuration properties
      Property value optional/mandatory Description
      com.ibm.ssl.protocol SSL [default], SSLv3, TLS, TLSv1 optional Specifies the protocol to use
      com.ibm.ssl.keyStoreType SSO-KS [default], PKCS12 optional Specifies the type of keyStore to use
      com.ibm.ssl.keyStore Absolute or relative path to file on the file system. If relative path is specified, path must be relative to the current working directory. mandatory Specifies the location of keyStore on the file system
      com.ibm.ssl.trustStoreType SSO-KS [default], PKCS12 optional Specifies the type of trustStore
      com.ibm.ssl.trustStore Absolute or relative path to file on the file system. If relative path is specified, path must be relative to the current working directory. mandatory Specifies the location of trustStore on the file system
      com.ibm.ssl.keyStorePassword Plain-text password for keyStore mandatory Specifies the password to open the keyStore
      com.ibm.ssl.trustStorePassword Plain-text password for trustStore mandatory Specifies the password to open trustStore
      com.ibm.ssl.clientAuthentication true | false mandatory Specifies whether the client application requires authentication. The default is false.
    2. Set the system property com.ibm.pvc.webcontainer.ssl.configfile to point to the SSL configuration file created in (a).
    3. Set the HTTPS port using ConfigurationAdmin or using the system property com.ibm.pvc.webcontainer.port.secure.
      Note: The Web Container secures requests only if the HTTPS port is set and the SSL configuration file is supplied to the Web Container. If the port is not set, the Web Container defaults to running the requests on the HTTP port.
      Example: If the com.ibm.pvc.webcontainer.port.secure system property is set to 9000 and you have defined an SSL channel SSL_TEST using either the Channel Framework extensions or system properties, then the SSL configuration file looks as follows:
      com.ibm.ssl.clientAuthentication.9000=true
      com.ibm.ssl.trustStorePassword.9000=password
      com.ibm.ssl.keyStorePassword.9000=password
      com.ibm.ssl.trustStore.9000=../sampleTrust1.jks
      com.ibm.ssl.keyStore.9000=../sampleKeys1.jks
      com.ibm.ssl.clientAuthentication.SSL_TEST=true
      com.ibm.ssl.trustStorePassword.SSL_TEST=password
      com.ibm.ssl.keyStorePassword.SSL_TEST=password
      com.ibm.ssl.trustStore.SSL_TEST=../sampleTrust1.jks
      com.ibm.ssl.keyStore.SSL_TEST=../sampleKeys1.jks
      Note: Both the secure transport and channel are configured to use the same keystore and truststore files in this sample. The password for both of these files is "password".
  2. Create the external keyStore and trustStore repositories:
    1. Use iKeyman or the key tool command-line utility, which is provided with the JDK, to create the keyStore and trustStore files. Location of these files is specified using the SSL configuration file.
    2. Use iKeyman or the key tool command-line utility to generate key entries and certificates and store them in the keyStore and trustStore files.
  3. Export and import the certificate:
    Note: This step is performed only if Web applications deployed to the Web Container use the HttpsURLConnection class.
    1. Use the key tool command-line utility to create a self-signed certificate for the server, for example, localhost. To do so, open a Command Prompt window and change the directory to the directory where you have the key file, for example, c:\temp\ for the file trustkey.jks. Then type key tool -export -alias server -keystore trustkey.jks -file server.cer to generate a server.cer file.
    2. Export the server certificate from the Web Container keyStore, and import it into the JRE keystore, which is used by the Lotus Expeditor URL handler, at:
       $Expeditor_INSTALL_DIR\rcp\eclipse\plugins\$runtime_jre\jre\lib\security\cacerts
      The $runtime_jre could be one of the following:
      com.ibm.rcp.j2se.win32.x861.5.0.SR2-yyyymmdd
      com.ibm.rcp.j2se.linux.x861.5.0.SR2-yyyymmdd
      where yyyymmdd is the year, month, and date.

      To export the server certificate, change the directory to <install_dir>\rcp\eclipse\plugins\<runtime_jre_dir>\jre\lib\security. Import the certificate that you generated by typing keytool -import -trustcacerts -alias server -keystore cacerts -file <filename> where <filename> is the absolute path to the server certificate created in step 3b.

When the Web Container is configured to enable SSL support, the Web Container deletes the SSL configuration file and store the configuration in a webcontainer.properties file (passwords are encrypted) in the user configuration directory.

Configuring SSL for ISync

The DB2® Everyplace® Sync technology (ISync) allows for the use of SSL to connect from the client to the DB2 Everyplace Sync server, if both client and server are SSL-enabled in a compatible configuration.

Using DB2 Everyplace Java Sync Client for Derby

When using the pure Java IBM Apache Derby ISync implementation, there are no ISync-specific SSL configuration steps required. The IBM Apache Derby Java ISync provider assumes that the client platform has already been configured to support the SSL outbound connections.

Refer toConfiguring SSL for the platform for more information.

The Apache Derby synchronization codepage configuration isync.encoding values of ASCII, UTF-8, or UTF8 are not supported when using the DesktopEE Java runtime environment. The default code page for your client platform is used if the isync.encoding property is not set and functions as expected. If UTF-8 or ASCII encoding must be used, then the Java 5 runtime environment is required.

Using DB2 Everyplace native synchronization

When using the native DB2 Everyplace native database and synchronization implementation, some operating system-specific tasks are required to prepare the client for synchronization with the DB2 Everyplace Sync server. Refer to Secure Sockets Layer and DB2 Everyplace mobile devices in the DB2 Everyplace Information Center.

These configuration steps can be applied to the device as well as the desktop.

Using SSL from applications

This section describes using SSL from applications, specifically creating SSL connections to servers and creating SSL sockets from incoming connections.

Creating SSL connections to servers

The default platform configuration for SSL for creating connections to servers is handled as described in the following section:

.

Applications that need to create their own SSL connections to a server can use the same platform configuration.

Applications need only to create a URL specifying HTTPS as the wanted protocol, and the appropriate HttpsUrlConnection object is created. Applications either rely on the default configuration or configure the security information about a per-instance basis. Changing the default configuration might have adverse effects on other applications running in the platform and on the connection capabilities of the components provided with the platform.

Creating SSL sockets for incoming connections

The default SSLServerSocketFactory that provides SSLServerSockets is based on the settings provided in the java.security file for the platform. Refer to the articles listed in Configuring platform security for more information on when and how to update this file. Applications rely on the default configuration.

Applications attempting to open SSLServerSockets for their own usage must be aware that the Web Container component of the platform can also attempt to open SSL Server Sockets. Changing the default configuration might have adverse effects on other components provided with the platform.

Enabling FIPS-compliant JCE and JSSE providers

This section describes how to enable Federal Information Processing Standards (FIPS)-compliant JCE and JSSE providers.

You must switch to J2SE to run FIPS. Enabling use of FIPS-compliant JCE and JSSE providers requires updates to the java.security configuration file.

The java.security configuration file is contained in the following directories:
For J2SE on Windows:
installdir\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.x86_1.5.0.version\jre\lib\security
For J2SE on Linux
installdir/rcp/eclipse/plugins/com.ibm.rcp.j2se.linux.x86_1.5.0.version/jre/lib/security

Refer to http://www-128.ibm.com/developerworks/java/jdk/security/50/FIPShowto.html for more information on enabling FIPS-compliant providers.

Configuring the platform help

Based on your product requirements, you can either remove the Help menu completely or remove the Help Contents and About menu items under Help using activities.

To remove the Help Menu completely, use the following activity:
<extension point="org.eclipse.ui.activities">
    <activity id="activity.help.menu" name="hideHelpMenu" />
    <activityPatternBinding activityId="activity.help.menu" 
    pattern="com\.ibm\.rcp\.platform\.personality/help" />
</extension>
To remove the Help Contents menu item under Help:
<extension point="org.eclipse.ui.activities">
    <activity id="activity.help.contents" name="hideHelpContents" />
    <activityPatternBinding activityId="activity.help.contents" 
    pattern="com\.ibm\.rcp\.platform\.personality/helpContents" />
</extension>
To remove the About dialog:
<extension point="org.eclipse.ui.activities">
  <activity id="activity.help.about" name="hideHelpAbout" />
  <activityPatternBinding activityId="activity.help.about" 
  pattern="com\.ibm\.rcp\.platform\.personality/about" />
</extension>

Configuring the Lotus Expeditor sidebar

Use the sidebar to perform tasks in other applications on the side without distracting from your work in the current application.

The sidebar is located on the left or right side of the client window and contains one or more panels that correspond to installed applications. For more information, see Sidebar in Developing Applications for Lotus Expeditor.

Disabling menus and menu items

Eclipse Activities (defined through the org.eclipse.ui.activities extension) can be used to hide contributed menus and menu items.

By defining an activity, a menu or menu item is associated with the activity, and unless the activity is enabled, the menu or menu item is not displayed. To define the activity, you need to know the pattern that matches the wanted menu or menu items. A table listing the Expeditor contributed menus and menu items is provided in Lotus Expeditor top-level menus section of Developing Applications for Lotus Expeditor.

For example, to hide the File > Application > Reset menu action, first locate the correct pattern in the table, then define an extension that includes the pattern:
<extension point="org.eclipse.ui.activities">
<activity id="activity.reset.menu" name="hideReset"/>
<activityPatternBinding activityId="activity.reset.menu" 
pattern="com\.ibm\.rcp\.platform\.personality/resetPerspective"/> 
</extension> 
You can use the same strategy to disable other menus and menu items in Lotus Expeditor by specifying the appropriate pattern for that element. For example to remove the File menu, use pattern="com\.ibm\.rcp\.platform\.personality/file". To obtain the appropriate IDs to use in the pattern, see IMenuConstants.java in the User Interface and Personality Framework Javadoc.

Modifying platform configuration files

The client platform contains several configuration files that might require updates to successfully deploy and run applications.

The following options can be used to modify the properties files:
  • Features that are deployed to a client platform can contain code that runs to perform tasks during the life cycle of a feature. This code is known as an installer handler. You can use a global installer handler provided by the client platform or you could create your own installer handler to modify the properties files. See Using the global install handler.
  • You can use tasks provided by the Client Management server to query and modify specific elements of managed properties files. For the client platform, the rcpinstall.properties, config.ini, plugin_customization.ini, and rcplauncher.properties files are defined by default to be managed by the Client Management server. You can also enable additional files to be managed by using the com.ibm.rcp.props.dm.managedFile extension point.
If you are using the WebSphere Portal administered client capabilities to deploy features, the install handler option is the recommended update model. The WebSphere Portal administered client capabilities do not permit querying of current values of the properties on the client systems.

Updating the rcplauncher.properties file

This section describes how you can update one or more elements of a user Lotus Expeditor Client platform by modifying the rcplauncher.properties file.

The rcplauncher.properties file is managed through install handlers. It contains properties that are required by the launcher for global actions.

Without correct values in this, file the platform does not start. Any other properties in this file are ignored. This file cannot be modified except through install handlers.

File locations:
  • ${rcp.home}/rcp/rcplauncher.exe
  • ${rcp.home}/rcp/rcplauncher.properties
A typical rcplauncher.properties file looks like this file:
rcp.install.id=1156180825640
The branding properties (product and osgi.splashPath) are managed from the rcplauncher.properties.
osgi.splashPath=platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personali
ty.branding,platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personality.b
randing.nl1,platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personality.b
randing.nl2,platform\:/base/../rcp/eclipse/plugins/com.ibm.rcp.platform.personality.b
randing.nl3 
product=com.ibm.rcp.platform.personality.branding.DefaultProduct
The calculation used to locate the user workspace is externalized in this file.
rcp.data=$(env.APPDATA)/Lotus/XPD

This value can be customized in the installer.

The rcp.install.id property is a unique number generated by the installer. It is used to ensure that there are no collisions between multiple installations of the platform. This number is copied to the new rcpinstall.properties file of the user.
provisioning.manifest=file\:/${rcp.home}/rcp/deploy/install.xml
The definition of the base install chosen by the administrator is defined in this file. When a new user starts the platform for the first time the configuration is provisioned to this level.
provisioning.manifest.version=1156180825640
This configuration is the version of the provisioning.manifest file being used. The number typically starts with the current rcp.install.id. When a user starts the platform and the launcher determines that the manifest version is not identical to the level in the uservrcpinstall.properties, a provisioning cycle is initiated. The level provisioned for a user is written to the rcpinstall.properties file of the user by the provisioning component.
install.configuration=user
This level is set by the original installation and should never be changed. This level is copied to the new user rcpinstall.properties file.
update.policy.managed=true
This property is an internal property and should not be changed. It can be ignored in future versions of rcplauncher.
rcp.base.location=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.1.0.0-20060817
This property points to the base plug-in that contains:
  • base rcpinstall.properties file – Initial values represent what is in the core set of features. All changes above this level are caused by the running of install handlers.
  • base platform executable file and classes located and run from this location.
  • rcplauncher.exe is located here but is copied to <install dir>/rcp/rcplauncher.exe by the plug-in install handler.
  • Platform.xml and config.ini are here and are used to seed the initial configuration directory.
This property is copied to a new user rcpinstall.properties file. From that point forward, it is allowed to get out of sync with the rcplauncher.properties value. That change can happen if a user chooses to run with a different version.
provisioning.application=com.ibm.rcp.provisioning.application.ProvisioningApplication
This is an internal property and should not be changed.
jvm.location=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.dee.win32.x86_6.5.0.<builddate>/jre/bin/j9w.exe
This property points to the Virtual Machine (VM) that implements the Java specifications that are used by new users. When creating a user initial configuration, this property becomes the vm property in the user rcpinstall.properties. This property and the vm property are managed by feature install handlers. From that point forward, the user is allowed to choose a different VM version or possibly even a different VM. The vm property can be managed by an install handler.
jvm.location can point to an executable, a DLL, default.ee, or nothing. If jvm.location=, the Eclipse executable locates the VM used. It selects the system VM. In most cases, the system VM is the DLL version. When the VM is launched as a DLL, Expeditor has only the Eclipse executable process running. When the VM is launched as an executable, Lotus Expeditor has the Eclipse process and a child Java process running. The actual Eclipse process that is running might have been renamed. Check the property eclipse.name. This property identifies the actual process name.
jvm.feature.id=com.ibm.rcp.dee.win32.x86.feature
jvm.feature.version=6.1.0.0-20060812
jvm.parent.feature.id=com.ibm.rcp.jvm.feature
jvm.parent.feature.version=1.0.0.0-20060930
These are internal properties and are managed by install handlers. They are used for correcting the initial platform.xml.
Note: If the Lotus Expeditor Client is using an external VM, the jvm.feature* and jvm.parent.feature* properties are blank, as no VM features are used. The jvm.location property is set to the specified location of the Java executable, defined at installation time with the EXTERNAL_JVM_LOCATION property.
Microsoft Windows has a 256-byte limit on command length that can be stored in the properties for an icon. If you are customizing launch icons to contain personalities or Dcommands, for example, this limit can be easily exceeded. As a work-around, you can define the arguments as properties in the rcplauncher.properties file. The launch command has to contain only the following code:
rcplauncher.exe –config launchconfigone

rcplauncher.exe –config launchconfigtwo
When the launcher notices the -config launchconfigone arguments, it substitutes the properties stored in the rcplauncher.properties file as if they had been included on the command line.
For example, if the actual command is rcplauncher –console -application com.ibm.MyApplication -nl de –path “path with spaces and {DBCS}” –vmargs -Dmyproperty=test, the following properties are stored in rcplauncher.properties:
config.launchconfigone.1 = -console
config.launchconfigone.2 = -application
config.launchconfigone.3 = com.ibm.MyApplication
config.launchconfigone.4 = -nl

config.launchconfigone.5 = de
config.launchconfigone.6 = -path
config.launchconfigone.7 = path with spaces and \uxxxx\uxxxx… 
config.launchconfigone.8 = -vmargs 
config.launchconfigone.9 = -Dmyproperty=test

Where a space exists between elements on a full command line, the elements are represented as separate config arguments. In the preceding example, the elements -nl de are separated by a space on the command line, so that they become separate config arguments.

Notes:
  • The property file does not ensure that these arguments stay in order. The numbering scheme ensures that the arguments can be restored correctly. The number must start with 1 and be numbered consecutively.
  • The path must be entered on the command line surrounded with quotation marks. Not only is that not required to be in the file, it is not allowed. Quotation marks can be added if they are part of the arguments, but do not add additional quotes.
  • The path can contain non-ASCII or non-ISO8859-1 characters. Any non-ASCII characters must be escaped with \uxxxx. You can generate these values with a Unicode 16 editor and convert them with the Java program native2ascii.
  • The vmargs must be entered in the rcpinstall.properties as vmarg.xarg=-Xarg. For this file, however, enter the properties only as described previously. The value is always exactly as it is contained on the command line – except as noted.
  • Using the –config argument does not restrict adding additional arguments on the actual command line. The launcher does not guarantee the order of combining the properties and the command-line arguments (except for the overrides noted in the text that follows). The launcher maintains the order of the specified properties from the file.
Some of the arguments that can be entered on the command line or in the config.xxx properties have an override priority. The VM, application, product, personality, and plug-in customization properties have the following override priority:
  1. Command line.
  2. config.xxx property.
  3. Property in rcpinstall.properties.
The workspace has the following priority:
  1. –data on the command line.
  2. –data in the config.xxx property.
  3. rcp.data property in the rcplauncher.properties.
The locale has the following priority:
  1. –nl on the command line.
  2. –nl in the config.xxxx property.
  3. com.ibm.rcp.core.locale in rcpinstall.properties. This property is normally set from a preference page and replaces the value set by Priority 4.
  4. com.ibm.rcp.core.locale in rcplauncher.properties. This property is normally set by the installer and populates the default language for a user rcpinstall.properties file.
  5. The locale calculated by the platform.
The BIDI value has the following priority:
  1. –dir on the command line.
  2. –dir in the config.xxx property.
  3. com.ibm.rcp.core.bidi in rcpinstall.properties. This property is normally set from a preference page and replaces the value set by Priority 4.
  4. com.ibm.rcp.core.bidi in rcplauncher.properties. This property is normally set by the installer and populates the default language for a user rcpinstall.properties file.
  5. Directory calculated by the platform when –nl is specified.
The vmarg.<name>=<value> has the following priority:
  1. Command line
  2. config.xxx property
  3. Property in rcpinstall.properties
  4. Property in jvm.properties

This file can be populated with config properties from an install handler.

The installer creates and populates the rcplauncher.properties file. Users should not change this file. Only ISVs and developers can change the file; however, they should not change the installed values. Administrators can add config properties.

For information about how to manage this file, see the following sections:
Managing using a Client Management server
Managing properties files
Managing Rich Clients using the Portal server
Managing property files
Managing using another management system
Managing Java properties

To enable the flexibility to change the drive that IBM Lotus Expeditor is launched from, the rcpinstall.properties should not contain absolute path references to files or directories in the install directory.

Rather than specifying the absolute location of the install directory, the string ${rcp.home} is used to reference the install directory, and ${rcp.data} is used to refer to the workspace directory. Upon launch, the launcher replaces the value of these tokens with the correct location of the IBM Lotus Expeditor install directory and workspace directory before passing the arguments to the Java executable for IBM Lotus Expeditor.

When adding new properties to rcpinstall.properties, or changing existing properties, it is important that ${rcp.home} or ${rcp.data} is used when referring to the install or workspace directories, and to not use any absolute path references.

The rcp.data property is written by the installer at installation time and should not be modified. The rcp.data property gives a versatile way to specify where the workspace is to be located. See Installing the Lotus Expeditor Client for shared launching from a network drive for information about how to specify this value before installing. This value is copied to rcpinstall.properties of each user and overrides the default algorithm for calculating the workspace location.

The default value for rcp.data for is rcp.data=${env.APPDATA}/Lotus/XPD

If you are upgrading from IBM Lotus Expeditor 6.1, the default rcp.data keeps the original algorithm. For Windows, it appears as:
rcp.data=${env.HOMEDRIVE}${env.HOMEPATH}/IBM/RCP/${prop.rcp.install.id}/${env.USERNAME}/
The placeholder ${env.system environmental variable”} is used to specify the use of a system environmental variable.

The placeholder ${prop.”rcplauncher_property”} is used to specify the use of a property from rcplauncher.properties.

The installer can also write the following properties to the rcplauncher.properties:
  • com.ibm.rcp.core.locale
  • com.ibm.rcp.core.bidi
For more information about these properties, see Updating the rcpinstall properties file. These properties allow the installer to specify a default language other than English for each use. These properties are copied to the rcpinstall.properties for each user when their configuration is created.

Updating the jvm.properties file

This section describes how you can update the jvm.properties file.

The jvm.properties file that is packaged with IBM supported JVM features generally is considered read-only. It is possible, however, to override these values, as outlined in Updating the rcplauncher.properties file.

The ${rcp.home}/rcp/deploy/jvm.properties file is used when using an external JVM. Because it is populated with only a minimal set of properties, it is expected that it will be modified. You can add other properties that are appropriate for the JVM that you are using. These additional values are not added to the command line or rcpinstall.properties because they are JVM-specific.

If you are using the default JVM you see a property like this one:

vmarg.Dshare=-Xshareclasses:name=xpdplat,controlDir=${prop.jvm.shareclasses.loc},
groupAccess,keep,singleJVM,nonfatal

This property enables the shared classes. If you are debugging with the SDK you might want to disable this property. There are several ways to do this task:

  • Comment out the line with #.
  • Use .\rcplauncher.exe -vmargs vmarg.Dshare=.
  • Add arguments like these arguments to rcplauncher.properties and launch with .\rcplauncher.exe -config rdebug:
    config.rdebug.1=-debug 
    config.rdebug.2=-console 
    config.rdebug.3=-pb4l 
    config.rdebug.4=-vmargs 
    config.rdebug.5=-Xdebug 
    config.rdebug.6=-Xnoagent 
    config.rdebug.7=-Djava.compiler=NONE 
    config.rdebug.8=-Xdbg:transport=dt_socket,server=y,suspend=n,address=9999 
    config.rdebug.9= vmarg.Dshare=

The third option allows you to turn this behavior off or on from the command line. This ability lets you pause the launch and allow attaching a remote debug session on port 9999. Press Enter in the console window to continue the launch.

Updating the rcpinstall properties file

This section describes how you can update the rcpinstall.properties file.

The rcpinstall.properties file resides in the location ${rcp.data}/.config. See Overriding the workspace directory location for more information.

This file must meet all requirements of a Java property file. Any non-ASCII characters must be escaped with \uxxxx. You can generate these values with your favorite Unicode 16 editor and convert with the Java program native2ascii. See the Javadoc for java.util.Properties.load() for more information.

The rcpinstall.properties file can contain the following properties:
Note: Unless indicated otherwise, all properties appear only once within the rcpinstall.properties file. If a property appears more than once, there is no guarantee which property is used.
Note: Any modifications to rcpinstall.properties that are not made using installhandlers are lost on platform upgrade.
Table 12. rcpinstall.properties
Property Description
vm=<VM executable file> If this property exists it must point to an executable, a DLL, or a default.ee. If this property is missing, the Eclipse launcher attempts to locate the system JVM. Anytime the file is generated for a user, this property is populated based on the jvm.location property in rcpinstall.properties.
rcp.install.id=<id> This property is required. It is a unique ID that the installer creates for each installation.
Xbootclasspath.prepend=<path> This property specifies the -Xbootclasspath/p:path. See the documentation for the Java application launcher.
Xbootclasspath.append=<path> This property specifies the -Xbootclasspath/a:path. See the documentation for the Java application launcher.
-D<prop>=<value> See the documentation for the Java application launcher. Additional system properties can be added at the bottom of the file.
library.path.append=<path> This property modifies PATH (on Windows) or LD_LIBRARY_PATH (on Linux).
library.path.prepend=<path> This property modifies PATH (on Windows) or LD_LIBRARY_PATH (on Linux).
application=<application plugin id> This property is equivalent to the Eclipse runtime property eclipse.application. You can override this property for the user and multi-user configurations by using the -application argument on the command line.
product=<product id> This property is equivalent to the Eclipse runtime property eclipse.product. You can override this property for the user and multi-user configurations by using the -product argument on the command line.
personality=<personality id> This property allows you to customize the look and feel depending on the wanted applications. You can override this property for the user and multi-user configurations by using the -personality argument on the command line.
plugincustomization=<path to customization file> This file is provided by the initial install. New values can be appended to this file. You can override this property for the user and multi-user configurations by using the -plugincustomization argument on the command line.
install.configuration={multiuser, service, user, userpb, lockdown} This property is required. It specifies the configuration installed by the installer. After a platform has been installed, this value is not to be changed.
vmarg.<name>=<value> This property is the preferred method for setting -X and -D parameters. When this method is used, it is possible to change a value or turn it off from five different levels. (See the override hierarchy in Updating the rcplauncher.properties file.) For an example of overriding a jvm property, see Updating the jvm.properties file. The value is passed unaltered as a vmarg to the VM. The name is used only as a unique identifier of the vmarg within this file. Syntax of the argument is not checked.
library.preload=<value> This property has been populated by the installer if needed.
com.ibm.rcp.core.locale Optional: This property is added by the launcher through public methods. It can be overridden on the command line with –nl localearg.
com.ibm.rcp.core.bidi Optional: This property is added by the launcher through public methods. It can be overridden on the command line with –dir dir.
env.set.system env variable This property can be used to set a system environmental variable. If the variable exists, it is replaced. For instance, env.set.XXX=a new variable sets XXX to “a new variable”.
<any java.util.logging configuration settings> Optional: Any of the standard java.util.logging configuration settings can be made in this file such as logger level configuration entries and handler listings. For a complete list of java.util.logging configuration values, see Configuring platform logging and tracing.

An example of a typical rcpinstall.properties file might look like the following code.

In this example, lines have been split to enable readability. In the actual file, the lines must not be split unless '\' is used. The line continuation character ('\') can be used with the following restrictions related to <prop>=<value>:
  1. It must be the last character on the line. There can be no trailing white space.
  2. If the <value> is split, do not insert white space before the continuation character.
  3. Any white space at the beginning of a continued line is discarded.
#Wed Feb 01 08:42:42 CST 2006
# Note: this file has been formatted to aid readability. In the real file order is
# not guaranteed and comments will be stripped.

Xbootclasspath.append=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.1.1.20070222
0600/rcpbootcp.jar 
-Dcom.ibm.pvc.webcontainer.port=0 
-Declipse.registry.nulltoken=true 
-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www.protocol 
-Djava.util.logging.config.class=com.ibm.rcp.core.internal.logger.boot.LoggerConfig 
library.path.append=${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.win32_6.1.1.200702
220600/os/win32/x86;${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.os.linux_6.1.1.200702
220600/os/linux/x86  

# Framework extensions for logging and jxe support 
-Dosgi.framework.extensions=com.ibm.rcp.core.logger.frameworkhook,com.ibm.jxesupport  

# Eclipse plugin_customization.ini override 
plugincustomization=${rcp.home}/rcp/plugin_customization.ini  

# Exclude Eclipse logging hook and JXE support hook 
-
Dosgi.hook.configurators.exclude=org.eclipse.core.runtime.internal.adaptor.EclipseLog
Hook,com.ibm.jxesupport.CDSHookConfigurator  

# Java security file location 
-Djava.security.properties=file:${rcp.home}/rcp/eclipse/plugins/com.ibm.rcp.base_6.1.1
.200702220600/rcp.security.properties  

# Java Core dump location. Note this is temp fix for only VM environmental variables 
# This ability is not supported in the general case in 6.1 
env.set.IBM_JAVACOREDIR=${rcp.data}/logs 
env.set.IBM_COREDIR=${rcp.data}/logs 
env.set.IBM_HEAPDUMPDIR=${rcp.data}/logs  

# JSR47 Logging Configuration 
handlers=java.util.logging.ConsoleHandler 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.encoding=UTF-8 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.encoding=UTF-8 
java.util.logging.ConsoleHandler.encoding=UTF-8 
.level=WARNING 
SystemOut.level=INFO 
SystemErr.level=INFO 
com.ibm.rcp.core.internal.logger.frameworkhook.level=CONFIG 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.level=WARNING 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.level=FINEST 
java.util.logging.ConsoleHandler.level=FINEST 
java.util.logging.ConsoleHandler.formatter=com.ibm.rcp.core.internal.logger.boot.RCPF
ormatter  

# RCP Logging Configuration 
#com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=com.ibm.rcp.core.inter
nal.logger.boot.RCPFormatter 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=com.ibm.rcp.core.intern
al.logger.cbe.CBE101Formatter 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.size=4000000 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.count=6 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.append=false 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.pattern=error-log-%g  

# RCP Trace Configuration 
#com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=com.ibm.rcp.core.int
ernal.logger.boot.RCPFormatter 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=com.ibm.rcp.core.inte
rnal.logger.cbe.CBE101Formatter 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.size=4000000 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.count=6 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.append=false 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.pattern=trace-log-%g  
For information about how to manage the rcpinstall.properties file, see the following sections:
Managing using a Client Management server
Managing properties files
Managing Rich Clients using the Portal server
Managing property files
Managing using another management system
Managing Java properties

To enable the flexibility to change the drive that IBM Lotus Expeditor is launched from, the rcpinstall.properties do not contain absolute path references to files or directories in the install directory.

Rather than specifying the absolute location of the install directory, the string ${rcp.home} is used to reference the install directory, and ${rcp.data} is used to refer to the workspace directory. Upon launch, the launcher replaces the value of these tokens with the correct location of the IBM Lotus Expeditor install directory and workspace directory prior to passing the arguments to the Java executable for IBM Lotus Expeditor.

When adding new properties to rcpinstall.properties, or changing existing properties, it is important that ${rcp.home} or ${rcp.data} is used when referring to the install or workspace directories, and to not use any absolute path references.

Configuring platform logging and tracing

The Lotus Expeditor Client platform uses the Java Runtime Environment java.util.logging logging framework for persistence of all the platform and application log and trace messages.

The default configuration of the platform logging framework is stored in the user workspace/.config/rcpinstall.properties file. For information about updating this file, see Updating the rcpinstall properties file.

System Default Configuration

The default configuration for the client platform registers three handlers: a console handler, a log handler, and a trace handler. The encoding for the file-based handlers (log and trace) is set to UTF-8 while the console encoding defaults to the platform encoding method for all log messages. The number of files (count) to be persisted for each of the handlers defaults to 6, and the maximum size (size) for each of the files before they are rotated defaults to 4000000 bytes. The size can be set individually for both the log and trace handlers and has a minimum size of 100K bytes. The default message level filter for the console handler and the trace handler is FINEST, allowing all messages that are logged to be captured by these handlers and processed appropriately. The log handler defaults to WARNING to ensure that the system log, which is intended for the user, is not overrun with informational messages and trace messages during normal execution. This setting allows the user to more easily identify possible problems in the log file in the case where the application or the platform is not functioning as expected.

One important note is that while the standard java.util.logging settings are used for most of the configuration, the one variation is the pattern setting. The pattern for the Lotus Expeditor Client is expected to be a relative name from the user workspace or logs directory and does not support the %h replacement defined by java.util.logging to relocate these log files.

If the platform is started with a console, all log and trace messages are routed to the console handler and displayed using the standard text format using the RCPFormatter. The standard log and trace files are written by default in CommonBaseEvent XML format using the CBE101Formatter.

The default rcpinstall.properties file also includes a small collection of default java.util.logging logger level configuration as well. There are two special named loggers defined to handle system.err and system.out messages, called SystemOut and System.err. The loggers default to the INFO level, meaning that system.err and system.out messages do not appear by default in the system.log file but do appear in the system trace file.

The default settings for the java.util.logging framework are shown here:
# JSR47 Logging Configuration 
handlers=java.util.logging.ConsoleHandler 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.encoding=UTF-8 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.encoding=UTF-8 
.level=WARNING 
SystemOut.level=INFO 
SystemErr.level=INFO 
com.ibm.rcp.core.internal.logger.frameworkhook.level=CONFIG 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.level=WARNING 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.level=FINEST 
java.util.logging.ConsoleHandler.level=FINEST 
java.util.logging.ConsoleHandler.formatter=com.ibm.rcp.core.internal
.logger.boot.RCPFormatter  

# RCP Logging Configuration 
#com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=
com.ibm.rcp.core.internal.logger.boot.RCPFormatter 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.formatter=
com.ibm.rcp.core.internal.logger.cbe.CBE101Formatter 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.size=4000000 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.count=6 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.append=false 
com.ibm.rcp.core.internal.logger.boot.RCPLogHandler.pattern=error-
log-%g  

# RCP Trace Configuration 
#com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=
com.ibm.rcp.core.internal.logger.boot.RCPFormatter 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.formatter=
com.ibm.rcp.core.internal.logger.cbe.CBE101Formatter 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.size=4000000 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.count=6 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.append=false 
com.ibm.rcp.core.internal.logger.boot.RCPTraceHandler.pattern=trace-
log-%g

While the JRE java.util.logging APIs are used for the actual persistence of messages to disk, several logging APIs are available in the Lotus Expeditor Client platform. The client platform provides the following logging APIs: java.util.logging APIs, eclipse logging APIs, the OSGi LogService APIs, and Apache Commons logging APIs. The core logging framework of the Lotus Expeditor Client platform captures the messages from all these APIs and federates them into one single log using the java.util.logging persistence and formatting framework. To simplify configuration of these federated messages, dynamic named loggers are created for the non-java.util.logging components when messages of the appropriate level are generated and logged. The named loggers are created with the bundle symbolic name of the OSGi bundle that is logging the message as the name of the java.util.logging logger. This logger can be configured using the standard java.util.logging logger level configuration using the rcpinstall.properties file or dynamically using the OSGi console command setlogrlev.

Updating the config.ini file on desktops

This section describes the properties provided in the default config.ini file.

The config.ini file is located in the <configurationdir>/.config directory. The installer provides information and values for this file that the platform needs.

The .config directory resides in the workspace directory defined by the pattern in the rcplauncher.properties file.

The following is a list of properties found in the config.ini file:

osgi.parentClassloader
The definition of the parent class loader for OSGi bundles.

Current® Setting: ext

Default setting: boot

osgi.bundles

A comma-separated list of bundles that are installed and optionally started after the system is running. For more information about the syntax for this property, refer to the Platform Plug-in Developer's Guide and to Eclipse (http://help.eclipse.org/help32/index.jsp).

Current Setting:
osgi.bundles=org.eclipse.equinox.common@2:start, \ 
org.eclipse.core.jobs@4:start,\ 
org.eclipse.equinox.registry@4:start,\ 
org.eclipse.core.runtime.compatibility.registry,\ 
org.eclipse.equinox.preferences@4,\ 
org.eclipse.core.contenttype@4,\ 
org.eclipse.core.runtime@4:start,\ 
org.eclipse.update.configurator@3:start, \ 
../../rcp/eclipse/plugins/com.ibm.rcp.lifecycle.platform@5:start

Default Setting: <none>

osgi.bundles.defaultStartLevel

Assigns the default start level to any bundles that do not explicitly have a start level assigned.

Current Setting: 10

Default Setting: 4

osgi.startLevel

Sets the top start level for the framework to attempt to start.

Current Setting: 15

Default Setting: 6

eclipse.exitOnError

Indicates whether the workbench exits immediately if it receives a Framework ERROR event.

Current Setting: false

Default Setting: true

For information about how to manage the config.ini file, see the following sections:
Managing using a Client Management server
Managing with a Client Management server
Managing Rich Clients using the Portal server
Managing property files
Managing using another management system
Managing Java properties

Updating the config.ini file on devices

On devices, the config.ini file is located in the \eclipse\configuration directory. This file can be modified to set Java system properties, which are typically not specific to single applications.

See Updating a property value in a property file for more information on setting properties on user devices.

Updating the plugin_customization.ini file

The plugin_customization.ini file sets the default value of the preferences used on the client system.

The plugin_customization.ini is a Java properties file that contains preference settings. Each preference is identified by a node name and a key. Some preferences can define nodes between the root node and the key.

The format of each line is the following:
root nodename/[optional intermediate node/] preference name=preference value
To add a new default preference, add a new line to the file specifying the node names, preference name, and value.

For example, to set an update policy file, first identify the node associated with the preference (org.eclipse.update.core), the preference name (updatePolicyURL), and the desired value (http://w3.myserver.com/policy.xml).

Then add the line org.eclipse.update.core/updatePolicyURL=http://w3.myserver.com/policy.xml

As a Java properties file, content is expected in ISO-8859-1 encoding. Any characters not in the ISO-8859-1 encoding are specified using Unicode escape syntax. Refer to the Javadoc for the java.util.Properties class for more information.

The plugin_customization.ini file resides in the install dir /rcp directory. The default settings in the file are as follows:
com.ibm.rcp.security.auth.ui/ssoEnabled=false 
com.ibm.rcp.platform/portalServerAddress= 
com.ibm.rcp.platform/portalEnabled=false 
com.ibm.rcp.security.auth.ui/ssoAllowed=true
Properties include the following.
Note: The ssoEnabled and ssoAllowed values can be set only before the platform is run. After the platform is run, these options can no longer be changed.
com.ibm.rcp.security.auth.ui/ssoEnabled=true|false
Determines whether users have the option of turning single sign-on on or off. The default value is true, indicating that single sign-on is enabled. If set to false, single sign-on is disabled. The value of this preference is relevant only if ssoAllowed is true.
com.ibm.rcp.platform/portalServerAddress=address
com.ibm.rcp.platform/portalEnabled=true|false
com.ibm.rcp.security.auth.ui/ssoAllowed=true|false
Determines whether users have the option of using single sign-on. The default value is true, indicating that users can use single sign-on. If set to false, users cannot use single sign-on. You can set this preference value during the client installation or later using a managed setting. This preference is not surfaced to users.
org.eclipse.help.base/help_home=/org.eclipse.help.base/doc/rcp_help_home.html
Defines the home page that is displayed when the Help Contents are opened. It is useful if you want to replace the home page for product- or application-related content.
com.ibm.rcp.security.auth/loginEnabled=value
Values are as follows:
Deny
When a single sign-on login is detected, the client displays a "Failed to log in" message and forces the user to exit the platform. This value is the default value.
Note: In restricted workbench mode, the user cannot recover the password because the desktop is locked down by Lotus Expeditor. It is recommended that the administrator uses the Delete policy for restricted workbench users.
Delete
Deletes the keystore (without prompting the user) and creates a new one. The user might experience data loss but is not forced to exit the platform.
Prompt
Prompts whether to delete the keystore and continue or exit. If the user does not delete the keystore, the user cannot access the platform.
For information about how to manage the plugin_customization.ini file, see the managing properties files topic in the following sections:
Managing using a Client Management server
Managing properties files
Managing Rich Clients using the Portal server
Managing property files
Managing using another management system
Managing Java properties

Enabling platform single sign-on

Single sign-on (SSO) authenticates users by prompting them for a user name and password a single time. Enabling platform single sign-on gives users secure access to the platform keystore without displaying additional authentication prompts.

To enable platform single sign-on, perform the following step:
In the plugin_customization.ini file in the install_dir/rcp directory, set the values for the following preferences to true:
  • com.ibm.rcp.security.auth.ui/ssoAllowed – Boolean value. Determines whether users have the option of using single sign-on. You can set this preference value during the client installation or later using a managed setting.
  • com.ibm.rcp.security.auth.ui/ssoEnable – Boolean value. Determines whether users have the option of turning single sign-on on or off. If set to true, single sign-on is used. If set to false, single sign-on is disabled. The value of this preference is relevant only if ssoAllowed is true.
For example:
com.ibm.rcp.security.auth.ui/ssoEnabled=true 
com.ibm.rcp.security.auth.ui/ssoAllowed=true
Notes:
  • The ssoEnabled and ssoAllowed values can be set only before the platform is run. After the platform is run, these options can no longer be changed.
  • To assist in managing SSO password lockouts on Microsoft Windows, Lotus Expeditor provides the SSOResetPolicy preference. For more information, see Updating the plugin_customization.ini file.
  • In a multi-user environment, platform single sign-on must be configured for each individual user.
  • SSO cannot be enabled while switching JVMs.

Managing secure keystore

The Java KeyStore is the standard storage abstraction for security-sensitive information such as keys, certificates, and passwords.

The Java keystore is accessed by the Login Modules to retrieve and store passwords as part of the login process. The Java KeyStore is also accessed by the Accounts API to change passwords outside of the login process.

The Java KeyStore must be unlocked to access any data stored inside it. The KeyStore can be unlocked using Platform Login. By default, Lotus Expeditor calls the Platform Login to unlock the keystore at startup time. This default can be changed programmatically to unlock the KeyStore when needed.

Here is an example of how to programmatically Call the SecurePlatform login to unlock the Java Keystore:
import com.ibm.rcp.security.auth.SecurePlatform;  

public void doLogin() {
try {

                 SecurePlatform.getLoginContext().login();
} 
catch (LoginException e) {
                 // Login failed… exit platform or take corrective action
}
}

Depending on how Lotus Expeditor is configured, calling SecurePlatform login prompts the user for a keystore password, or it gets the password from another secure source and uses it to unlock the KeyStore (see Enabling platform single sign-on).

After the Java Keystore is unlocked, the Accounts API and the JAAS Login Modules can access secure data such as passwords stored in the Keystore. The Keystore can also be accessed programmatically by calling SecurePlatform.getKeyStore(). All Lotus Expeditor applications have access to the Java Keystore and can use it to store their own data.

Managing problem determination artifacts

Configure the Problem Determination Artifact Manager to ensure that the file system artifacts used for resolving errors are appropriately managed.

The Lotus Expeditor client runtime, while designed to run for extended periods without a restart, in some cases can experience unexpected error conditions. When these unexpected error conditions occur, in some cases Java heap dumps and core dumps can be generated to provide problem determination information for the service and support teams. Problem determination data can be critical in resolving these unexpected errors.

In other cases, problem determination can be more explicitly gathered by executing the IBM Support Assistant collection mechanisms built into the product. Both of these two cases produce file system artifacts in well-known locations on the client platform.

Over time, Java heap dumps and core dumps and ISA data collection jars can come to consume large amounts of disk space. To ensure that the file system space is managed appropriately, older files are deleted periodically. An aging algorithm is used to allow the files to remain for a configurable number of days to allow them to be referenced during a problem determination session, but after they have exceeded an age limit, they are deleted. This aging period can be administratively configured and can also be administratively disabled. The default period is five days.

The Problem Determination Artifact Manager provides this capability for the Lotus Expeditor runtime client.

Changing the Problem Determination Manager default interval

You can change the Problem Determination Manager default interval to define when file system artifacts are removed.

To change the Problem Determination Manager default interval, do one of the following:
  • Using a text editor, open the <install dir>/rcp/plugin_customization.ini file and modify the com.ibm.rcp.core.pd.manager/interval property for the interval in days, and save the file.

    For example, com.ibm.rcp.core.pd.manager/interval=120.

  • If you manage the client using the Client Management server:
    1. Launch the administrative console to create a configuration job for the com.ibm.rcp.core.pd.manager/interval preference.
    2. Schedule the job for the client device.
    When the user launches the client platform, the device agent polls the server and receives the configuration job. The Eclipse preference is updated.

Disabling the Problem Determination Artifact Manager

This option lets you disable the Problem Determination Artifact Manager.

To disable the Problem Determination Artifact Manager, do one of the following steps:
  • Using a text editor, open the <install dir>/rcp/plugin_customization.ini file, set the com.ibm.rcp.core.pd.manager/interval property to 0, and save the file.

    For example, com.ibm.rcp.core.pd.manager/interval=0.

  • If you manage the client using the Client Management server:
    1. Launch the administrative console to create a configuration job for the com.ibm.rcp.core.pd.manager/interval preference, setting it to 0.
    2. Schedule the job for the client device.
    When the user launches the client platform, the device agent polls the server and receives the configuration job. The Eclipse preference is updated.

Managing accounts

You can store, access, and use properties that are required to make a connection to, and communicate with, a remote service.

The Accounts API provides a way to store, access, and use properties that are required to make a connection to, and communicate with, a remote service. Some examples of accounts include: An HTTP account that is used to connect to a Web-based service. This account contains a URL for the location of the service, and a user name and password to log on to the service. An Instant Messaging account that is used by an IM client to connect to an IM server, such as IBM Lotus Sametime. This account includes a server name, user name, and password to connect to the IM server. The account can also be used to store user preferences such as the text people see when the u IM status is Away. An account can be used to store both connection properties and properties or preferences specific to that connection. In the case of IM, the user can have multiple IM accounts, both for business and personal use. The Away status message can be stored in the account, so that it can be set to a different value for each account.

The Accounts API provides a way to get, add, update, remove, and listen for changes to an account. Accounts can be obtained by unique id, name, or any other property, and a get account by server method provides for partial matches. The Accounts API also provides integration with the Java Authentication and Authorization Service (JAAS). (For more information about JAAS, refer to http://java.sun.com/products/jaas/overview.html) A properly constructed account can provide a login context service that obtains and validates the credentials needed to connect to a remote service. Certain accounts also obtain LTPA and session cookies. By using the Accounts integration with JAAS, an application has the validated passwords and cookies needed to communicate with the remote service.

All accounts except for the Home Portal Account can be managed using the Accounts user interface. The Home Portal Account can be managed using the Home Portal Account user interface.

For more information, refer to Accounts framework in Developing Applications for Lotus Expeditor.

Creating accounts

An account holds a set of properties (name/value pairs) used by an application to connect to a remote service.

You can have an account to connect to your personal mail server using POP3 to get your e-mail, an account to connect to an IBM WebSphere Portal Server to access composite applications, or an LDAP account to do name look-up from the corporate directory. Some accounts might exist on the client, either created by applications or provisioned from IBM LotusDomino or WebSphere Portal. Be careful when editing, removing, or creating new accounts, as these steps can cause some applications to no longer function. If you are not sure what to do, ask your administrator.

The following advanced properties for HTTP accounts are primarily used to specify additional properties needed to authenticate with either a WebSphere Portal Server directly or an HTTP/Portal server protected by Tivoli® Access Manager or Site Minder. Knowing what to enter for these properties requires specific knowledge of the HTTP infrastructure of an organization, and users are advised not to modify these properties unless they are given specific instructions from their administrator. This section provides enough information to use these properties, but it assumes some knowledge of the authentication mechanism being used.

Authentication types

HTTP Basic (default)
HTTP Basic is simple user name and password authentication. The authentication is done at the URL specified by the Server value, and all other advanced properties are ignored. This approach is analogous to opening a Web browser to the URL and the browser displaying a dialog asking for a user name and password.
J2EE Form (advanced)
J2EE-FORM is a standard way of authenticating with a Web application server, such as WebSphere and Portal servers. A form is submitted to a URL that contains a user name and password. For WebSphere and Portal servers, an LTPA token is returned, which can be used for future authentication. J2EE-FORM uses the Authentication URL (auth URL) property to connect to a servlet. The auth URL is used in one of the following two ways:
  • If the auth URL is a complete and valid URL (for example, http://myportalserver.com/wps/j_security_check), then the auth URL is used to locate the servlet.
  • If the auth URL is a partial URL (for example, /wps/j_security_check), then it is appended to the root of the Server value.

    For example, if the server value is http://myserver.com/mycontextroot and the auth URL is /wps/j_security_check, then the URL used is http://myserver.com/wps/j_security_check.

Portal Form (advanced)
Portal Form is a more advanced version of J2EE-FORM. The auth URL is set to a slightly different location. This auth URL generates both an LTPA token for authentication and a JSession cookie for session data. Portal form is used to communicate with portlets because J2EE-FORM does not provide the session cookie. Use J2EE-FORM to communicate with servlets hosted on Portal and WebSphere servers.
Tivoli Access Manager Form and Site Minder Form (advanced)
Tivoli Access Manager Form and Site Minder Form are used when the HTTP resource is protected by one of these technologies. The HTTP resource is configured to accept the authentication token provided by Tivoli Access Manager or Site Minder. These auth types work in the same way as Portal form, except that a form is submitted that is specific to either Tivoli Access Manager or Site Minder. The result of the authentication is a cookie that can be used to authenticate with any of the protected HTTP resources, including WebSphere and Portal servers.

An account with the Tivoli Access Manager Form or Site Minder Form authentication type can be further configured to correctly interact with a Tivoli Access Manager or Site Minder server that has a custom configuration. The following properties can be set in a Tivoli Access Manager or Site Minder account:

custom_user_key
The custom user name key as specified in the Site Minder Login Form
custom_password_key
The custom password key as specified in the Site Minder Login Form
custom_target_key
The custom target key as specified in the Site Minder Login Form
custom_target
The custom target value to be returned to the Site Minder server as part of the login form response (POST)
use_target_as_authurl
Directs the Tivoli Access Manager, Site Minder, or Portal-Form login module to use the URL requested by the URL handler as the auth url. When this option is specified, the custom_target and authentication URL account preferences are ignored. The value of this field is set to true or false.
The following list details the only supported Site Minder configurations:
  • HTML form-based login
  • HTML form-based login over SSL
  • HTML form-based login over SSL with X509 client certificate verification
  • Customized username and password labels on login form
  • Persistent and non-persistent sessions
The following Site Minder configurations are NOT supported by Lotus Expeditor:
  • Basic authentication
  • Basic authentication over SSL
  • Basic authentication over SSL with X509 client certificate verification
  • Windows integrated authentication
  • Custom authentication schemes
  • JavaScript or other non-standard HTML forms
  • Password change services
  • Impersonation
  • Additional form attributes required for authentication

Servers with a login form that is not named login.fcc will not have session expiration support from Lotus Expeditor

User Name Token (advanced)
User Name Token is an authentication mechanism used by Web Services. This authentication type is used only by child accounts that have selected the Use name and password of an existing account. User name token is used only if the Web Service does not accept any other form of authentication because it requires sending the user name and password on every request. This authentication type is rarely used and is to be avoided if possible.
TAM SPNEGO (advanced)
Tivoli Access Manager SPNEGO is supported on Microsoft Windows operating systems only. It uses Active Directory to get a token based on the operating system log-in of the user. It then uses that token to authenticate with TAM, rather than using a user name and password. Apart from that difference, the result of the authentication is the same as for TAM Form.

Authentication URL

The authentication URL is used only by J2EE-FORM and PORTAL Form because it needs to know where the authentication servlet is located. The value for this property can either be a complete URL or a path relative to the root of the server URL.

The authentication URL is required only by J2EE-FORM and PORTAL Form because it needs to know where the authentication servlet is located. The value for this property can be either a complete URL or a path relative to the root of the server URL. If the authentication URL is set for TAM Form or Site Minder Form, Lotus Expeditor connects to the authentication URL to authenticate with the server. If the authentication URL is not set for TAM Form or Site Minder Form, Lotus Expeditor uses the Account server property as the authentication URL.

Home Portal URL

Some applications require this value to interact properly with a WebSphere Portal Server. When accessing a Portal server through a Web browser, by default the following URL is used:
http://myportalserver.com/wps/myportal
The Home Portal URL in this case is the myportal part. Because this part is configurable by the system administrator, the default value can be altered as needed in the advanced properties.

Enterprise Management Agent Accounts

Device User Name
The identity of a user machine for connecting to a Client Management server.
Device User Password
The password of a user machine for connecting to a Client Management server.
Server Address
The server address consists of two parts: a URI and the path to the DM Servlet to contact for enrollment. Use one of the following to specify the Client Management server address:
  • IP address
  • Host name
  • Host name plus domain name
SyncML/DM is the data synchronization protocol that the agent and server use to communicate. When the server has been configured to require authorization using SyncML/DM, append the following value to the Server Address:
dmserver/OMADMServletAuthRequired
If SyncML/DM authorization is not required by the server, append the following value to the Server Address instead:
dmserver/OMADMServlet

Managing Eclipse preferences

The platform and application plug-ins can use Eclipse preferences for storage of configurable information. Examples can include window settings, server locations, and synchronization settings.

Eclipse is an open source community committed to implementation of a universal development platform.

Eclipse preferences are managed in a tree format. The first nodes after the root are called scopes. The scopes each define a subtree. The default scopes provided by Eclipse are default, instance, configuration, and project. Under each of the scopes, the preferences tree is typically organized by plug-in identify. Associating preference keys and values with a particular plugin will help to eliminate naming collisions.

The product adds an additional scope called ManagedSettings. See Configuring managed settings for more information.

Instance scope is stored per workspace, while the configuration scope is stored in the configuration directory. Because the platform install configuration sets the configuration directory to be a directory in the workspace, instance and configuration scopes are effectively equivalent.

You can search preferences by name, and the scopes can be searched in a particular order. A typical search order would be instance, configuration, then default scopes.

How are preferences set?

Preferences are set through the code, often as a result of interactions with preference pages. However, plug-ins can internally use preferences, and not surface those preferences through user interactions.

How are default preference values set?

The following list describes the several ways in which default preference values can be set for a particular plug-in. They are listed in the order in which they are processed. A default preference set at the lowest level (for example, Runtime defaults) is over-ridden by the same preference set at a higher level (for example, Product defaults).
Runtime defaults
These are specified by code, such as contained in a plug-in class or in a preference initializer supplied as an extension to the org.eclipse.core.runtime.preferences extension point
Bundle defaults
Default values specified in preferences.ini files in the plug-in.
Product defaults
Default values specified in the customization file supplied by the product.
Command line defaults
Default values specified in a plug-in customization file specified on the command line.

Once the developer has created the plug-in, at application assembly time, the assembler might choose to add preferences.ini files to the plug-in to override whatever the developer may have set.

Once plug-ins are deployed to a client system, it is strongly discouraged that the plug-in contents are updated. Therefore, after deployment of the plug-ins, the only applicable way to override preference default values is through the command line plug-in customization file. See Updating the plugin_customization.ini file.

For the client platform, the plugin_customization.ini is contained in the <installdir>/rcp directory.

After the client platform has been deployed, this file can be changed through the following methods:

How are project, instance and configuration preference values set?

Settings in the project, instance and configuration scopes are typically made as a result of user interactions, such as through the preferences dialog. The plug-in code will need to use appropriate methods to search install and configuration scopes prior to using the default values.

Project preference values are typically not used by most platform and application components. Project level preferences are most often associated with code creation or application assembly tools that maintain a concept of projects, such as the Eclipse SDK.

Project, instance and configuration preference values can be queried after deployment using the preferences jobs supplied by the Client Management server. See Getting an inventory of Eclipse preferences for more information.

You can add, update, or remove project, instance, and configuration preference values using the following mechanisms:

What about user-defined or custom scopes?

Applications can define additional custom scopes for storing preferences. The ManagedSettings scope defined by this product platform is an example of a custom scope. The preferences jobs and policy settings are used by the Eclipse preferences APIs to query and effect changes on the preferences values. The APIs will typically work for other scopes, unless the other scopes are providing additional restrictions. If an application is providing their own custom scope for preferences, the management operations supplied by the Client Management server or the policy settings may not always perform successfully. Refer to the application for more information on how to manage values in its custom scope during deployment and post-deployment operations.

Managing OSGi preferences

The client platform includes an implementation of the OSGi Preferences service for use by OSGi-related applications.

The OSGi Preferences service implementation provided by Eclipse uses the standard Eclipse preferences service persistence mechanism for storage of preference values.

OSGi preferences are accessible only to the plug-ins that created the preference, and are associated with the bundle number of the plug-in. If the bundle number changes, the preferences will no longer be accessible. Operations such as starting the platform with the –clean option can cause bundles to be re-numbered. For this reason, OSGi preference usage is not encouraged.

How are preferences set?

Preferences are set directly through the code, often as a result of interactions with a user.

How are default preference values set?

Default preference values are always set by the service that is defining the preferences. The service may provide alternatives for setting the default values.

How can the preference values be changed after deployment?

You can query OSGi preference values after deployment using the preferences jobs supplied by the Client Management server. Preference values for OSGi preferences are located at /configuration/org.eclipse.core.runtime.preferences.OSGiPreferences.xx where xx is the bundle number. See Getting an inventory of Eclipse preferences for more information.

You can add, update, or remove project, instance and configuration preference values using the following mechanisms:

Since the storage mechanism contains some referential aspects, if a plug-in has not already created settings value, it is not recommended that you create a new OSGi preferences tree for the plug-in, but that you only modify values for the existing tree. Changes to OSGi Preference values may not be available until the next platform restart.

Managing UserAdmin settings

The client platform includes an implementation of the OSGi UserAdmin service. The UserAdmin service provides a mechanism for storing user definition, user credentials, user roles, and group information.

The UserAdmin service uses the OSGi Preferences mechanism for storage of this information. Since the OSGi Preferences mechanism uses the bundle number of the UserAdmin service to store user information, if the bundle number changes, the UserAdmin definitions will no longer be accessible. Operations such as starting the platform with the -clean option can cause bundles to be re-numbered.

The UserAdmin service is primary mechanism that can be used by the Web container for storing user and role related information.

How are user definitions created?

User definitions are created programmatically leveraging the User Admin APIs.

How can user definitions be changed after deployment?

You can query UserAdmin settings after deployment using the preferences jobs supplied by the Client Management server. UserAdmin settings are located at /configuration/org.eclipse.core.runtime.preferences.OSGiPreferences.xx where xx is the bundle number of the UserAdmin bundle (org.eclipse.equinox.useradmin). See Getting an inventory of Eclipse preferences for more information.

Use the following mechanisms to add, update, or delete user settings:

Since the storage mechanism contains some referential aspects, if the UserAdmin bundle has not already created any settings, it is not recommended that you create a new UserAdmin preferences tree for the plug-in, but that you only modify values for the existing tree. Changes to UserAdmin settings may not be available until the next platform restart.

Managing ConfigurationAdmin settings

The client platform includes an implementation of the OSGi ConfigurationAdmin service. The ConfigurationAdmin service provides a mechanism for configuration information for a service.

The ConfigurationAdmin service uses the OSGi Preferences mechanism for storage of this information. Because the OSGi Preferences mechanism uses the bundle number of the ConfigurationAdmin service to store user information, if the bundle number changes, the ConfigurationAdmin definitions will no longer be accessible. Operations such as starting the platform with the –clean option can cause bundles to be re-numbered.

How are user definitions created?

ConfigurationAdmin settings are primarily created through code. In addition, you can use the Admin Utility for OSGi to create user definitions.

How can ConfigurationAdmin settings be changed after deployment?

You can query ConfigurationAdmin settings after deployment using the preferences jobs supplied by the Client Management server. Configuration settings are located at /configuration/org.eclipse.core.runtime.preferences.OSGiPreferences.xx where xx is the bundle number of the ConfigurationAdmin bundle (com.ibm.osg.service.cm). See Getting an inventory of Eclipse preferences for more information.

Use the following mechanisms to add, update, or delete user settings

Since the storage mechanism contains some referential aspects, if the ConfigurationAdmin bundle has not already created any settings, it is not recommended that you create a new ConfigurationAdmin preferences tree for the plug-in, but that you only modify values for the existing tree. Changes to ConfigurationAdmin settings may not be available until the next platform restart.

Managing life cycle

This section describes the life cycle of the client platform.

Understanding life cycle

Plug-ins present in the client platform have a defined life cycle and states. Plug-ins are present in one and only one state at a time.

Plug-in life cycle

The defined states are as follows:
Note: Information in this section applies to using the Lotus Expeditor Client on a device, except where noted.
Installed
The underlying framework has added the plug-in. Under normal operation, a plug-in registered by the Eclipse update components will enter a resolving process and transition to the resolved state. If a plug-in is present in the platform, but is in installed state, then either the plug-in has dependencies that have not been met, or another plug-in with an identical Bundle-SymbolicName has been selected by the framework. A plug-in in installed state cannot share packages, nor can it contribute extensions or extension points.
Resolved
All of the prerequisites of the plug-in have been met. A plug-in may contribute packages, extensions, and extension points to the platform.
Starting
The plug-in has been requested to start and the framework is in the process of starting the plug-in. Start operations should be fast, so any plug-in that remains in a starting state is indicative of a plug-in that is failing to use best practices in its BundleActivator class. Plug-ins that are resolved and that have a bundle activation policy of lazy will enter the Starting state. The console window may show bundle state as <<LAZY>>. This indicates a bundle in the Starting state waiting for a class access to transition to active.
Stopping
The plug-in has been requested to stop and the framework is in the process of stopping the plug-in. Stop operations should be fast, so any plug-in that remains in a stopping state is indicative of a plug-in that is failing to use best practices in its BundleActivator class.
Active
The plug-in has been started.
Uninstalled
The plug-in has been uninstalled and may not be used.

Fragment life cycle

Fragments are associated with a host plug-in. Since a fragment cannot be individually started and stopped, a fragment follows the life cycle associated with its host plug-in. Fragments are attached to their host plug-in during the resolution process.

Platform life cycle

When the platform is requested to start, the underlying framework will begin the initialization and startup process. To bootstrap the platform, a small number of plug-ins and fragments will be individually installed and started. This set of plug-ins is defined by the osgi.bundles property. The default value of this property is defined in the configdir\config.ini file.

The remainder of the plug-ins and fragments for the platform will be installed next. The set of plug-ins and fragments to install will be determined based upon the platform configuration. If the framework is using a managed only configuration, the set of plug-ins and fragments will be determined based upon the platform configuration defined in the platform.xml file residing in the configdir. If the framework is not using a managed only configuration, the set of plug-ins and fragments will be discovered by the Update Configurator component from the defined eclipse extension directories.

Once the installation of the plug-ins into the framework has completed, a resolver step will run and will attempt to resolve all of the plug-ins and fragments.

After the resolver step has completed, the framework will begin the process of starting the plug-ins. The framework uses settings known as Start Levels to organize the startup of the plug-ins. The framework exists at a specified level and the plug-ins are assigned to start at a specific level. The framework begins at level 0 with no plug-ins started. Next, the Framework will move to start level 1. All plug-ins assigned to start level 1 will then be started in some order. The framework will progress through each of the levels until it reaches the designated framework start level. The designated framework start level is determined by the osgi.startLevel property. The plug-ins that are started during the start level processing are those which have had a start level specifically assigned, and which have been marked to persistently start. A plug-in is marked for persistent start if it has been explicitly started by code that invokes the start() method on a Bundle object.

A specific set of plug-ins must always be started (active) for the platform to execute properly. The plug-ins required at startup are specified in the config.ini file in the configuration directory. The osgi.bundles property defines the set of plug-ins required at startup.

For any plug-in specified in this property, if it must start prior to the update configurator plug-in, then it must be able to resolve using only the plug-ins specified by this property. Any plug-in specified to start after the update configurator plug-in can use any other plug-ins installed by the update configurator or by the platform definition. Plug-ins in this property should generally be limited to those essential for startup.

After the framework has processed all of the required start levels, the framework will start running an application. An application as used here is a class referenced by an extension to the org.eclipse.core.runtime.applications extension point. Multiple plug-ins may define extensions to the org.eclipse.core.runtime.applications extension point. The actual application used at startup will be the application specified as a specific startup argument, or the application specified for a particular product.

This application defines the controlling characteristics of the platform, such as whether it will contain a workbench and provide a graphical user interface, or whether it will run to perform a specific task and then exit.

As the application runs, it requires the packages, extensions, extension points, and services contributed by the plug-ins in the platform. These plug-ins can automatically start when needed, based on the bundle activation policy. The bundle activation policy is defined by the manifest property Bundle-ActivationPolicy. The current allowed value is lazy. Previous versions of Lotus Expeditor used different manifest properties, such as Eclipse-LazyStart, or Eclipse-AutoStart. These properties have been deprecated, and the property Bundle-ActivationPolicy should be used instead. If a bundle has a bundle activation policy of lazy, defined using either the new or deprecated property, then when a request to obtain a class from that plug-ins class loader is detected, if that plug-in is not already in the active state, then the framework first attempts to start the plug-in to transition it from the resolved to active state. As part of the starting process, the BundleActivator start method is invoked to perform any required initialization for the plug-in. If the plug-in does not have a policy of lazy, then classes can be resolved from the plug-in without actually attempting to start the plug-in. If no activation policy is specified, the default is assumed to be none.

After the application is completed its task, the framework begins the exit process. In reverse order of the start levels, the plug-ins in the platform are called to stop; thus, allowing the plug-ins to perform any needed cleanup operations to free resources.

This product has added some additional capabilities into the startup processing beyond the capabilities provided by the underlying Eclipse frameworks. First, the com.ibm.rcp.lifecycle.platform plug-in has been added to the osgi.bundles property. This plug-in processes configuration information to select a set of plug-ins, assign those plug-ins a start level, and mark those plug-ins for persistent start.

Secondly, the platform has defined the com.ibm.rcp.lifecycle.application.startBundles extension point, as well as APIs provided in the com.ibm.rcp.lifecycle.application package, to enable applications to allow assemblers and deployers the ability to specify that certain plug-ins must be started when an application starts. This extension point is defined to assist in the startup of plug-ins that provide services and that do not export any packages. Since they do not export packages, there will be no normal class references to these plug-ins, so the presence of the Eclipse-LazyStart attribute will have no effect. The set of plug-ins to start with an application is set uniquely per application. The APIs will attempt to start each of the plug-ins specified by the extension point. Using framework techniques, the APIs will attempt to start the plug-in, invoking the start() method on the plug-in only if the Eclipse-LazyStart: true attribute is not set. When the application completes its tasks, the APIs will attempt to stop each of the plug-ins that it has started.

When using the Lotus Expeditor Client on desktops, the default application provided by the client platform, identified as com.ibm.rcp.personality.framework.RCPApplication, provides support for personalities. Each personality can be thought of as a mini application. Correspondingly, there is a com.ibm.rcp.lifecycle.personality.startBundles extension point which provides the ability to start (and stop) plug-ins that are associated with a specific personality. All of the same characteristics for plug-in startup for a specific application discussed in the previous paragraph can be applied to plug-in startup for a specific personality. For more information, see Using Personalities in Developing Applications for Lotus Expeditor.

The Lotus Expeditor Client for Devices only supports the com.ibm.rcp.lifecycle.application.startBundles extension point. However, this extension point may also be used similarly to the personality.startBundles extension point to start plug-ins when the Lotus Expeditor Client environment starts on the device. See Understanding application lifecycle in Developing Applications for Lotus Expeditor for more details.

Other notes on plug-in startup behavior

The webcontainer provides an extension point com.ibm.pvc.webcontainer.application that allows local web and portlet plug-ins to identify themselves via their context root to the webcontainer without requiring the plug-in to be started. When the webcontainer receives an HTTP request, if the plug-in that provides a local web or portlet application for that context root is not yet started, it will be started by the webcontainer. This will only apply to applications that have a specific context root. Applications that contribute behavior to the / context root will not be automatically started. Applications in this category include those applications that use the OSGi HttpService to provide servlet applications.
Note: By using the XPDT_SKIP_EXT_UPDATE = true property in their development environment, developers can prevent the com.ibm.pvc.webcontainer.applicationextension from getting added to the plugin.xml of the Client Services Web Project. This property can also be used with the WAB tools.

What's the difference between a bundle and a plug-in?

The term plug-in originated with Eclipse. The term bundle originated from the OSGi Alliance specifications. Eclipse changed to use an OSGi framework as its underlying componentization model. For purposes of this startup section, there is no difference between a bundle and a plug-in.

How should I set the activation policy?

The recommendation is to set all plug-ins to have a lazy activation policy. This will allow the plug-ins to be started in an automatically (or lazy) manner, and not require them to be explicitly started and marked for persistent start.

Why should I avoid having my plug-ins marked for persistent start?

Plug-ins marked for persistent start will be started each and every time that the platform starts. This can result in slower startup performance. In addition, if the platform has no need of the contributions of the plug-in, the plug-in will still consume resources, contributing to poorer runtime performance or increased memory consumption.

Contributing plug-ins to the personality life cycle

You can start a plug-in when a specific personality is started.

In the majority of cases, plug-ins that are exporting packages for use by other plug-ins, and contain the Bundle-ActivationPolicy: lazy (or Eclipse-LazyStart: true) attribute, are started automatically by the framework when there are requests for a class from that plug-in. In cases where a plug-in does not provide packages for use by other plug-ins, or the plug-in needs to start prior to later package references, then use this mechanism to start the plug-in with a personality.

Personalities allow you to customize the look and feel depending on the desired applications. Applications can have completely different requirements in terms of the plug-ins that are used, so when starting a personality, it is advantageous for resource reasons to start only what is needed. Because the Lotus Expeditor Client allows multiple personalities to run when using the default RCPApplication, you can control which plug-ins start based on a specific personality.

To contribute a plug-in when a specific personality is started:
  1. Identify the target personality (com.ibm.rcp.platform.personality is the ID of the default personality used by the RCPApplication).
  2. Add the plug-in to start either by adding the com.ibm.rcp.lifecycle.personality.startBundles to the service providing bundle or to another bundle independent of both the personality bundle or the service providing bundle.
The plug-in starts when the target personality is started.
A plug-in that needs to start DB2 Everyplace could define the following extension to start the com.ibm.db2e plug-in when the com.ibm.rcp.platform.personality starts:
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
  <extension
    point="com.ibm.rcp.lifecycle.personality.startBundles">
      <personality id="com.ibm.rcp.platform.personality">
         <bundle id="com.ibm.db2e"/>
      </personality>
  </extension>
</plugin>

Contributing plug-ins to the application life cycle

You can start a plug-in when a specific Eclipse application is started.

In the majority of cases, plug-ins that are exporting packages for use by other plug-ins, and contain the Bundle-ActivationPolicy: lazy (or Eclipse-LazyStart: true) attribute, are started automatically by the framework when there are requests for a class from that plug-in. In cases where a plug-in does not provide packages for use by other plug-ins, or the plug-in needs to start prior to later package references, use the com.ibm.rcp.lifecycle.application.startBundles extension point to associate a plug-in with an Eclipse application. The Eclipse application must use the com.ibm.rcp.lifecycle.application.BundleControl API to process the extension point information and start the requested bundles. Refer to the com.ibm.rcp.lifecycle.application.BundleControl Javadoc in Developing Applications for Lotus Expeditor for this class for more information and short sample code. The default application used by the client platform (com.ibm.rcp.personality.framework.RCPApplication) supports use of this extension point.

To contribute a plug-in to the application life cycle:
  1. Identify the target application (com.ibm.rcp.personality.framework.RCPApplication is the ID of the default application).
  2. Add an extension point to the bundle containing the application, add the extension point to the bundle containing the service, or add or modify some other bundle to add the extension point.
The plug-in starts when the target application is started.
A plug-in that needs to start DB2 Everyplace could define the following extension to start the com.ibm.db2e plug-in when the com.ibm.rcp.personality.framework.RCPApplication starts:
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
  <extension
    point="com.ibm.rcp.lifecycle.application.startBundles">
      <application id="com.ibm.rcp.personality.framework.RCPApplication">
         <bundle id="com.ibm.db2e"/>
      </application>
  </extension>
</plugin>

Platform users using the default com.ibm.rcp.personality.framework.RCPApplication can associate additional plug-ins to be started, as shown in the example above, and do not need to provide their own application. If the platform is not using the default application, plug-ins will need to be associated with the application used to start the platform. Bundles may be associated with more than one application. Since only one Eclipse application is used at startup, only the plug-ins associated with that application will be started.

Contributing plug-ins to the platform life cycle

You can start a plug-in when the platform is started.

Contributing plug-ins to the platform life cycle enables you to control which plug-ins are to start when the platform is started. In the majority of cases, plug-ins that are exporting packages for use by other plug-ins, and contain the Bundle-ActivationPolicy: lazy (or Eclipse-LazyStart: true) attribute, are started automatically by the framework when there are requests for a class from that plug-in. In cases where a plug-in does not provide packages for use by other plug-ins, or the plug-in needs to start prior to later package references, then use this mechanism to start the plug-in with the platform. The primary reasons why plug-ins need to be started with the platform is that they contain providers that are invoked by the base Java classes, and must be registered prior to attempting to use the base Java class resources.

You have two methods of changing the platform startup configuration:
Note: It is possible to define a set of startup bundles that result in a platform that will not start. While you may extend the set of bundles started at platform startup, it is not recommended to change the start levels or set of default bundles.
  • Deploy a new fragment to the com.ibm.rcp.lifecycle.platform host. If a fragment to the com.ibm.rcp.lifecycle.platform.plugin does not already exist, create a new fragment containing the file customStartLevels.properties. The contents of the defaultStartLevels.properties from the com.ibm.rcp.lifecycle.platform bundle are copied to the customStartLevels properties. See Packaging applications for deployment for more information on deploying fragments to the system.
    org.eclipse.equinox.log=1
    com.ibm.rcp.core.logger=3
    com.ibm.pvc.jndi.provider.java=5
    com.ibm.rcp.osgiagent.scheduler=10
    com.ibm.osg.service.osgiagent.NativeInstallWatchDog=10
    com.ibm.rcp.net.http=10
    com.ibm.rcp.provisioning=10
    com.ibm.rcp.core.pd.manager=10
    New customStartLevels.properties:
    org.eclipse.equinox.log=1 
    com.ibm.rcp.core.logger=3 
    com.ibm.pvc.jndi.provider.java=5 
    com.ibm.rcp.osgiagent.scheduler=10 
    com.ibm.osg.service.osgiagent.NativeInstallWatchDog=10 
    com.ibm.rcp.net.http=10 
    com.ibm.rcp.provisioning=10
    com.ibm.rcp.core.pd.manager=10
    com.yourcompany.yourbundle=10
    The new bundle is added to the list of bundles.
  • Use system properties.
    The following system property would be expected to be used to make major changes to the default start levels specified by the platform provider:
    • com.ibm.rcp.lifecycle.platform.defaultStartLevels – specifies the property file that contains the applicable start levels for the platform.

    This property would be expected to be used to make major changes to the default start levels specified by the platform provider.

    The following properties would be expected to be used to add minor modifications to the default start levels specified by the platform provider:
    • com.ibm.rcp.lifecycle.platform.startLevel.<startLevel>.include – applied after the start levels properties file has been processed. The <startLevel> is a specific start level to be modified from the value specified in the properties file. The value is a comma separated list of bundles to be excluded at this particular start level. The special id [services] may be used to start bundles containing Export-Service tag in their manifest.
    • com.ibm.rcp.lifecycle.platform.startLevel.<startLevel>.exclude – applied after the start levels properties file has been processed. The <startLevel> is a specific start level to be modified from the value specified in the properties file. The value is a comma separated list of bundles to be excluded at this particular start level. The special id [services] may be used to start bundles containing Export-Service tag in their manifest.
    • com.ibm.rcp.lifecycle.platform.startLevel.<startLevel>.replace -- applied after the start levels properties file has been processed. The <startLevel> is a specific start level to be modified from the value specified in the properties file. The value is a comma separated list of bundles to be started at this particular start level. The special id [services] may be used to start bundles containing Export-Service tag in their manifest. This value replaces the value contained in the properties file.

    See Updating the rcplauncher.properties file for more information on setting system properties.

If you need to make minor additions or changes to the default property set, such as when testing, then the system properties may be sufficient. If you need to make more significant changes, or need to deploy changes to many systems, a new fragment may be a better option.

The plug-in starts when the platform is started.

Configuring and administering micro broker components

Micro broker configuration and administration are managed using the administration interface of the broker. The Java classes that compose the broker provide a set of methods that enable application developers to tailor many factors that affect the behavior of the broker. These range from the size of the store used to manage the data flowing through the broker, to complex configuration of interconnects to other messaging systems. This section provides an overview of the administration interface. Detailed information is available in the relevant Javadoc.

Components that can be administered

The administration interface provides access to the following major components:
Broker
A BrokerFactory object provides methods to create and delete brokers in the same Java Virtual Machine in which the BrokerFactory resides or to log in and out of a remote broker for administrative purposes. The interface also allows brokers to be started, restarted, and stopped. All other objects, such as the bridge, are accessible from the broker object or from objects obtained from the broker object.
Bridge
Provides methods to create all associated bridge component definitions, pipes, flows, notifications, and transformations. It also provides methods for adding, deleting, starting, stopping, and listing all pipes.
Communications
Provides methods to create listener definitions, including TCP and Local listeners. These definitions can be added to the broker using this class, and other methods to get Clients and Listeners are also provided.
Persistence
Provides methods to get the log size and the current object store size.
Trace
Provides methods to get and set the trace level, send the trace output to a file, and perform an FFDC.
Pipe
Provides methods to start and stop the pipe.
Flow
Provides methods to define the sources (topics, queues, or both) and target (topic or queue) for a connection to another broker.
Client
Provides methods to disconnect and flush the client along with getter methods for client properties such as its name, connection time, number of subscriptions.
Listener
Provides methods to start, stop, restart, and remove the listener as well as the list of clients using the listener.
MessagingEngine
Provides methods to see and clear retained publications, see subscriptions, and access available queues.
Subscription
Provides methods to get the topic, QoS, and client ID of the subscription and delete it.
Queue
Provides methods to query queue properties, clear messages, and delete the queue.
The other administration classes consist of definition objects that allow objects to be defined and created and specific administration exceptions.

Accessing the broker administration interface

Access to the administration interface is gained by way of a BrokerFactory, an instance of which can easily be obtained as shown in the examples that follow. From an administrative perspective, there are two types of broker. These brokers are referred to as local and remote brokers and represented by their corresponding LocalBroker and RemoteBroker Java objects.

Local or remote access

A LocalBroker is a reference to a broker running in the same JVM as the administration application, and the administrative interface interacts directly with the broker. In contrast, a RemoteBroker reference is used to administer a broker running in a separate JVM, which could be either on the same system or on a different machine, using a TCP network connection.

References to both LocalBrokers and RemoteBrokers can be obtained from the BrokerFactory interface:

LocalBroker:
      String brokerName = “myBroker”;
      BrokerFactory factory = BrokerFactory.INSTANCE; 
      LocalBroker broker = factory.getByName(brokerName);      

RemoteBroker:
      String brokerAddress = “tcp://localhost:1883”;
      BrokerFactory factory = BrokerFactory.INSTANCE; 
      RemoteBroker broker = factory.getByAddress(brokerAddress);      

Most administrative tasks can be performed on both local and remote brokers, but there are a few significant differences:

  • Brokers can be created or deleted only in the local JVM (that is, you can create only a LocalBroker).
  • You can start only a LocalBroker, but both broker types can be restarted or stopped.
  • You have to log on to a RemoteBroker to use the administrative interface. You do so by providing a valid user ID and password. The broker must be running before you can log on and administer it remotely. A valid user ID for administration purposes is defined in the broker password file (micro-pwd) and has been granted both "connect" and "admin" permissions in the broker access control file (micro-acl.xml).
  • A LocalBroker can be accessed even if it is not running. Certain requests, such as getVersion(), getName(), and getDefinition(), do not require a broker to be running in order to provide useful information, but many other requests throw an exception unless the broker is started before using these methods.

For full details, see the Javadoc for the BrokerFactory, Broker, LocalBroker, and RemoteBroker interfaces.

Creating and starting a broker

Use this example to create and start a default broker.

This example shows how to create and start a default broker:
String brokerName = “myBroker”;
BrokerFactory factory = BrokerFactory.INSTANCE;
BrokerDefinition def = factory.createBrokerDefinition(brokerName);
LocalBroker broker = factory.create(def);
broker.start();
Many settings in the BrokerDefinition are fixes after the broker is created; you cannot modify the broker after it is created. This example shows how to change some of the defaults and then create a broker:
BrokerDefinition def = 
factory.createBrokerDefinition(brokerName);
def.setPort(1884);
PersistenceDefinition pd = def.getPersistenceDefinition();
pd.setLogSize(100000);
pd.setMaxObjectStoreSize(100000);
        
pd.setPersistenceType(PersistenceDefinition.FULL_PERSISTENCE);
def.setPersistenceDefinition(pd);
broker = factory.create(def); 

Configuring the broker

To create a broker, the following information is required:
Table 13. Required broker information
Parameter Description
name A unique identifier for the broker.
Specify the following information to change the default behavior:
Table 14. Changing the default behavior
Parameter Default Description
Admin password Admin The password for connecting to a remote broker. This parameter is used with the user name.
Admin user name Admin The user name for connection to a remote broker. This parameter is used with the password.
Data directory The value of the osgi.instance.area system property or the current directory if the system property has not been set. The broker needs a location to store configuration data and runtime information, such as publications and subscriptions.
Maximum message size 50 KB The maximum message size that is processed by the broker. The size is specified in kilobytes. If a message is received that exceeds this amount, it is ignored and an error is written using the OSGi log service.
Maximum number of clients -1 (unlimited) The maximum number of simultaneous clients that can be connected to the broker. If a client attempts to connect after the maximum has been reached, it is refused.
Port 1883 The port number the broker listens on for TCPIP connections.
Persistence definition See persistence table in the text that follows. The persistence definition holds all the information for how the broker stores its data.
Message Expiry Default 180 days If a message is received by the broker without a message expiry value set, then this default value is used. The default value means that messages are expired and thus removed after that time.
Default persistence information:
Table 15. Default persistence information
Parameter Default Description
Maximum transaction log size 3000 KB (3 MB) The maximum size of the transaction log in kilobytes. See text that follows for further details.
Maximum data store size The maximum size of the data store in kilobytes. See text that follows for further details.
Minimum data store size 3000 KB (3 MB) The minimum size of the data store in kilobytes. See text that follows for further details.
Persistence type Full persistence See persistence type explanations for valid options.
Queuing definition information:
Table 16. Queuing definition information
Parameter Default Description
Dynamic Queue Creation Enabled True Whether to allow the creation of dynamic queues.
Queue Expiry Enabled True Whether to allow dynamic queues to be automatically expired.
Dynamic Queue Expiry Default 28 days The default period of inactivity to wait before expiring a dynamic queue.
Maximum Depth Default 1000 messages The default maximum depth for all queues.
Creating the transaction log

The broker uses a transaction log to hold information about open transactions. An open transaction is created when sending a message to or from an MQTT client and when a transaction is created using a JMS client before it is committed or rolled back.

There are a number of factors on which to base the size of the transaction log. These factors include the size of the messages being processed, the number of clients connected, and the rate at which messages are sent. The higher these numbers, the larger the size of the transaction log is.

Creating the data store

The broker uses a data store to hold information about publications and subscriptions. The more publications and subscriptions the broker handles, the more space this store requires. The reason for having a minimum size as well as a maximum size is that there is a processor usage when increasing the store size. When the store is first created, it is takes up the minimum size and is then filled, rather than starting off with a zero-size file. It grows as more information needs to be stored. This growth also ensures that a store of at least the minimum size is available, as the maximum size can be set to a size greater than the available space.

Setting persistence
Persistence defines if and when data is stored to disk. There are three different types of persistence that can be used:
Full persistence
Full persistence provides protection against crashes. Data is constantly saved as messages are processed.
Shutdown persistence
Shutdown persistence provides no protection against crashes. Data is saved during a clean shutdown and reloaded at startup.
Memory persistence
Memory persistence writes no state to disk. When the micro broker is shut down, no information is saved.
Which persistence to use?

If data needs to be persisted between stopping and starting the micro broker, you must use shutdown or full persistence. To protect data in the event of an abnormal shutdown, you must use full persistence. Another consideration is the level of Quality of Service at which messages are being published. For Quality of Service 0 messages, memory persistence is acceptable. However, if Quality of Service 1 or Quality of Service 2 is being used, full persistence must be enabled to ensure the delivery of those messages that might be in flight when the micro broker is shut down.

Using the bridge

A key feature of the micro broker is its ability to connect to other messaging servers, such as other micro broker or enterprise messaging servers at the back end of the solution architecture.

This capability is provided by the bridge component of the micro broker. Applications can configure the bridge to connect the micro broker to a remote messaging server using a bidirectional link. This link allows messages sent to the micro broker to be routed to the remote broker, and messages sent to the remote broker can be routed to the micro broker.

In its simplest form, the bridge allows topics within a micro broker to be mapped directly to topics within the remote broker or messages sent to queues within the micro broker similarly to be routed to queues in the remote broker. More complex processing of messages flowing over the bridge is possible because of the transformation framework available to the bridge. Using this application, you can define additional processing logic to be run against each message to change its content, topic, or other message properties.

Components of the bridge

The bridge consists of the following main components:
  • Pipes, which represent the entity that owns a connection between the micro broker and a remote broker
  • Inbound and outbound flows, which represent the directional flow of messages between the micro broker and a remote broker within a pipe
  • Transformations, which can be defined for individual flows that modify messages in transit
  • Notifications, which can be defined to indicate particular events within the bridge, such as when a connection has been established
  • Connections, which define the characteristics of the specific endpoint for the pipe, such as a connection to MQ
These components are all administered using the micro broker administrative API, details of which can be found in the administrative API Javadoc.
Pipes

A pipe is the component that binds a connection with a set of flows and any associated transformations and notifications. The connection defines the remote messaging system with which messages are exchanged.

A name has to be specified when a pipe is created. This name must be unique because it is used to construct the clientID for both the local and remote connections. For the local connection, client ID is the name of the pipe appended to bridge:. This clientID makes it easy to avoid any clashes with regular local clients by avoiding clientIDs that start with the string "bridge:". At the remote broker, the clientID is simply the pipe name. Thus, a pipe called myPipe has a client ID of bridge:myPipe on the local micro broker and myPipe on the remote broker. Therefore, if two brokers are connected through a bridge and both contain a pipe with the same name, there are no clashes.

Care must be taken, however; if two brokers each have a pipe with the same name and are connected to a third broker, there would then be a clash.

Note: When a pipe is connecting to a remote broker, it is treated as a regular client, and as such, the clientID cannot exceed 23 characters. When creating a pipe, a name of greater than this length is not accepted.

After the pipe has started, it subscribes to its defined topics and connects to its defined queues both locally or remotely. If the remote connection of the pipe is broken, messages continue to be queued at both ends until the connection is re-established. If the connection is stopped, it stops consuming messages within the micro broker. Stopping the remote connection is handled using transmission control.

When a pipe is deleted, an attempt to purge the pipe is also made. This attempt ensures that no state data is held at either the local or remote end. Failure to delete the pipe cleanly can cause another pipe connecting with the same name to a remote endpoint to receive messages it had not subscribed to. There is an option to force a delete without ensuring a cleanup, but this option is recommended only as a last resort if the remote endpoint has changed, for example, and could never be connected to.

Flows

A flow defines a list of queues and topics that one side of the pipe listens or subscribes to (known as the sources), the queue or topic the messages from the sources are sent to (known as the target), the transformations that are applied to any messages transferred along this flow, and other message properties such as the quality of service (QoS) at which the messages from the sources to the target are sent.

Within flows, QoS is defined according to the MQTT scheme as an integer in the range 0 to 2 where:
  • QoS 0 means that messages are delivered at most once and not persisted
  • QoS 1 means that messages are delivered at least once and are persisted but might be duplicated
  • QoS 2 means that messages are delivered once only and are persisted
As with MQTT, the subscribing QoS for publish and subscribe governs the QoS at which the bridge receives the message. If a flow is consuming messages using a QoS 0 subscription, even if the publisher published the message at QoS 2, the bridge sees the message as QoS 0.

The only required property on a flow is to set at least one source queue or topic. If a target is not set, it defaults to be the same as the source.

Flows are added to pipes as either inbound or outbound flows. For an outbound flow, the sources are on the local micro broker, and the target is another message system (messages are going out from the local micro broker). On an inbound flow, the sources are on another messaging system, and the target is the local micro broker (messages are coming into the local micro broker).

As an example, two flows are created. Flow A has source topics “stock/IBM” and “stock/XYZ” and a target topic of “stock/myStocks”. Flow B has a source topic of “temp/#” and no target but a transformation that addsthe prefix “house/” to all incoming topics. Flow A is an incoming flow, and Flow B an outgoing flow. When the pipe is running and connected, messages published to “stock/IBM” and “stock/XYZ” on the remote messaging system are sent to the local micro broker over a flow. A client connected to the local micro broker needs to subscribe to topic “stock/myStocks” to receive these messages. Publishing messages to the local micro broker on topics that match “temp/#”, such as "temp" or "temp/external", causes them to be sent to the remote messaging system by Flow B. Clients connected to the remote messaging system need to subscribe to “house/temp/#” in order to receive the messages.

Any transformations that change the topic take precedence over the target property. If Flow B has specified a target, it is not used.

Certain flow properties are valid only if the flow is used along with an appropriate connection. For example, some JMS properties can be set on a flow, such as a JMS message selector. These properties are not valid when the flow is used in a pipe with an MQTT connection.

If a queue is used as the source of a flow, the flow is given exclusive read access to the queue. This allowance means that clients can only put messages on the queue; they cannot get messages from it.

If two flows are added to the same pipe in the same direction (for example, two inbound flows on a pipe), care must be taken to ensure that they do not contain the same source queue and topic. In this case, only one message is received, and it is sent according to the properties of the flow that was processed last. Overlapping subscriptions are handled in the same way that the micro broker handles them for client subscriptions, with the message matching the most specific topic receiving the message. For example, Flow A had “stock/#” as a source, and Flow B had “stock/IBM/#” as its source. Messages arriving on topic “stock/IBM/closingprice” match Flow B, and the message is delivered to the Flow B target, and not the Flow A target.

There are some restrictions on the sources and targets of flows that need to be adhered to:

Inbound flows:
  • If the Connection type is MQTT V3, all sources must be topics.
  • If the target of a flow is JNDI, the connection must be a JNDI connection (if the local side JNDI is implemented).
  • Only JNDI connections can have JNDI sources for the flows.
  • If the target of a flow is not set for a specific type of connection, the case source on the message is used as the target.
Outbound flows:
  • If the Connection type is MQTT V3, the target must be a topic (no JNDI and queues).
  • If the target of a flow is JNDI, then the connection must be a JNDI connection.
  • If the sources of a flow are JNDI, then the connection must be a JNDI connection (if the local side JNDI is implemented).
  • The target of a flow needs to be set only if the source is a topic and the connection type is MQTT V3 or V5.
Transformations:
  • Transformations can change the target destination type or the name, in which case the target destination revalidates with the preceding rules.
  • The transformation cannot change the source of a message.
Transformations

One or more transformations can be defined and then attached to pipes and flows, or both. These transformations then are able to modify messages as they pass through the pipe.

They are able to affect one or more elements of the message, the message body, message properties, and the target topic or queue name, but they cannot affect the target destination defined by the pipe connection. For more information about how a message can be read and altered, see the Javadoc for the BridgeMessage interface.

Transformations can be attached to either a flow or pipe. If they are attached to a pipe, they become the default transformations that are used for any flows defined in that pipe that do not have their own transformations specified. If a flow does have its own set of transformations, they are applied to messages passing along the flow and the defaults are ignored.

Transformations applied to a pipe are either inbound or outbound and become the default transformation for inbound and outbound flows. Messages that pass through a pipe and flow combination with no transformations attached to either pipe or flow are passed through as-is, although the target topic can be changed if the flow definition requires it.

The application developer has much flexibility when it comes to designing transformations. As well as the simple case discussed previously, multiple transformations can be applied sequentially to messages as they pass along a flow, and transformations also are able to pass parameters between themselves. These parameters (or properties) must not be confused with message properties. If a message has come from a destination that supports message properties, these properties are accessible by transformations through which the message passes. Any properties that are added or removed by the transformations become part of the message. Transformation properties exist only for the lifetime of the message while it is in the transformation. By setting transformation properties, one transformation can modify the behavior of a later one in a sequence of transformations being applied to a message.

The order in which transformations are applied to a message is defined by the order in which they are added to a TransformationDefinitionList, attached to a pipe or flow, which is achieved using the Administration API.

Some predefined transformations are supplied with the micro broker. These perform basic operations such as prefixing a topic, suffixing a topic, and setting a target name.

The bridge supports all JMS message types. As for MQTT messages, transformations can modify both the message content and the type of a JMS message as it flows through the bridge. This modification is achieved using the PayloadFactory and MessagePayload interfaces provided in the com.ibm.micro.payloads package in the com.ibm.micro.utils bundle. If an attempt to modify the message payload in an unsupported way is made, the message is sent as a BytesMessage and an error is reported.

Notifications

A notification is a message that is sent when a bridge event occurs. There are three types of bridge event that can generate a notification.

  • A pipe opens a connection.
  • A pipe closes a connection under program control (that is, the application requests that the pipe be stopped).
  • A pipe is closed due to losing the connection or another error.

To generate these notification messages, a notification object must be defined. A notification specifies which of the three events are of interest, the text to be sent when each specific event occurs, and other properties such as the quality of service at which the notification messages are sent. For example, if only connect and normal disconnect events are of interest and they are essential, a notification object is created that defines the text to be received for connect and disconnect events. Connection opened and Connection closed are set as the appropriate text strings, and the QoS is set to 2. Any connection lost events do not generate a notification.

A notification object is added to a pipe as either a local or a remote definition. A local definition sends the messages to the local micro broker, and a remote definition sends messages to a remote messaging system. If the remote connection is not a broker (that is, not an MQTT connection), the remote definition is ignored as only MQTT connections support the notification messages. At least one of the messages must be set for the notification to be valid, but not all have to be set.

Notifications are optional components. Pipes can also have either one or both of the local and remote notifications set. The same notification object can be used for both the local and remote definition, or they can be different. The same notification object can be used in different pipes.

To use notifications, a client must be subscribed to the notification topic (which is defined in the notification object) to receive the messages when they are sent.

Connections

A connection contains information that tells the micro broker to connect to a broker, WebSphere MQ queue manager, or JNDI-enabled JMS provider. The micro broker supports three types of connections.

  • An MQTT connection specifies the information required to connect to a broker that supports MQTT (such as another micro broker).
  • An MQJMS connection specifies the information required to connect to a WebSphere MQ queue manager.
  • A JNDI connection specifies the information required to connect to a JMS provider in a generic way by using JNDI to retrieve further connection details from a JNDI repository.
.
More information about each of these connection types follows:
MQTT connections
The MQTT connection allows specific MQTT properties to be set, such as a keepalive value. This connection uses the MQTT version 3 protocol and is used to connect to other micro broker components and MQTT version 3 or later enabled brokers.

This connection can be used to connect to other micro broker components and MQTT version 3 or later enabled brokers.

MQJMS connection
The MQJMS connection is provided to enable connection to a WebSphere MQ queue manager. Properties such as broker version, queue manager name, and channel can be set. This connection supports both publish-and-subscribe and point-to-point messaging. To support publish-and-subscribe messaging, the MQ queue manager must be running a broker. Refer to the WebSphere MQ documentation for details on setting up a broker.

This type of connection also requires access to a synchronization queue to provide ensured message delivery and a dead-letter queue for unsupported message types. The default dead-letter queue is present on the queue manager as it is a system queue, but the default synchronization queue needs to be created the first time the queue manager is connected to the micro broker. If either queue cannot be accessed, the connection is not started.

JNDI connection
The JNDI connection provided for connection to any JMS client that can be administered using JNDI. This type of connection is generic and provides the most flexibility of all three available types. It can be used to create a connection to another micro broker or a WebSphere MQ queue manager instead of using one of the more specific types already discussed. It also allows connection to any other JMS providers that support JNDI.
This connection requires an Initial Context Factory and URL to be defined in order to connect to the JNDI repository. After it can access the repository, it also requires a connection factory lookup key. All provider-specific information is then retrieved from the JNDI repository. If the repository requires any other JNDI properties to be set, these properties can also be defined when creating the JNDI connection.

The JNDI connection can optionally define a synchronization queue and a dead-letter queue. Because these are not required parameters, there are no defaults. If a synchronization queue is not set, QoS 2 messages cannot be sent as message delivery cannot be ensured (QoS 2 messages can still be received as doing so does not require the use of the synchronization queue). If the dead-letter queue is not defined and an unsupported message type is placed onto a queue or topic to which the connection is listening or subscribing, the message is taken from the queue or topic and discarded.

There are a few well-defined JNDI security properties that can be set using the connection definition. They are not encrypted when the configuration data is saved. Another way to provide these properties is to use a JNDI security class. This class is a class that must be supplied by the application and must provide any security parameters required to use the JNDI repository.

Details about how to create and use the JNDI security class framework can be found in Adding JNDI security properties.

Transmission control

The transmission control component enables the bridge to operate more easily on mobile devices. Previous versions of micro broker expected a network connection to be available between itself and any other servers, such as MQ, with which it was communicating. In a mobile environment, this connection is typically not the case.

With the transmission control component, micro broker users can control when to attempt to establish a connection to another server. The administration interface enables the administrator to specify connection and disconnection policies based on combinations of the following events and parameters:
Time of day
  • The administrator configures the required connection times.
  • The administrator allows transmission at known times of the day.
Number of messages in the send buffer
  • The administrator configures the maximum number of messages that are held pending before a connection is attempted.
  • The administrator prevents the buildup of too many unsent messages.
Maximum priority of any message in the send buffer
  • The administrator configures the message priority level that initiates a connection attempt.
  • The administrator allows high-priority messages to be sent immediately.
Manual override
  • The user program and the administrator can force connection and disconnection.
  • The administrator allows for more complicated connection policies than provided by the preceding events.
Additionally, the following attributes can be configured:
Connection retry interval
If the micro broker is unable to establish a remote connection when wanted, the time interval before it reattempts to make the connection.
Idle timeout
While the micro broker is connected, if no messages are sent or received for the duration of the idle timeout, it disconnects.
The default policy is for the micro broker to attempt to be continually connected.
Transmission control terminology
This section lists the terminology associated with transmission control:
(Connection) Policy
Set of rules for determining whether to be in connected or disconnected mode. The first rule for which the trigger is true has its action performed.
(Connection) Rule
A list of rules is held in a (connection) policy. Each rule has a trigger that returns true or false and an action (connect or disconnect), plus associated attributes (for example, idle timeout and retry interval).
Connected
The bridge attempts to send or receive messages.
Note: Connected / Disconnected – This component does not actually connect or disconnect to any underlying network (that is outside the scope of this component and assumed to be undertaken by the application or other software running on the same platform as the micro broker).
Disconnected
The bridge does not attempt to send or receive messages.
Tariff
The cost to use a utility transmission system. Tariffs can be charged for each connection and for the amount of data transmitted.
(Message) Priority
Messages (in JMS) can be assigned an integer priority by their publisher. There are two broad categories: levels 0-4 are gradations of normal priority; levels 5-9 of expedited priority (4 is the default). A message server can choose to order the delivery of messages based on priority.
Idle timeout
The idle timeout is a timer that is started after the send buffer has been emptied and reset if there is network traffic. Idle timeout can be configured to check for a number of seconds of inactivity that, if exceeded, is used to signal the end of a period of connection.
Understanding the transmission control administration model and connection policies

The transmission control administration model presents several connection policies that automate connection, connection retries, and disconnection. Each connection policy is tailored to the behavior of a class of scenarios. As administrator, you choose one of them to be operational at a time; the choice depends on the device and network environment in which that micro broker is used.

The policies have various attributes; the attributes vary from one policy type to another. The attributes are preset to sensible default values, so that you need to select only the most appropriate policy.

If you require finer control, you can set one or more of those attributes. To simplify this control, some of the policies can have several attributes set at once using a set of predefined configuration methods, tailored to a particular subset of use.

The default connection policy, Always Connected, eliminates you from having to configure this feature and provides a micro broker bridge that performs the same as the previous version.

At the other extreme is the Manual Connection connection policy, which allows user run-time code to decide when to turn the connection on and off.

The other connection policies include the following:
Tariff-based
Suitable for use with expensive connection charges for data or connection time.
Message-based
Allows the arrival of messages to drive the connection policy. Connection can be based on high-priority messages, a buildup of messages, or both. Connection can also be set to occur at a designated time interval after the last disconnection.
Calendar
Suitable for a device that needs to connect periodically at set dates and times. Connection can also be triggered by a buildup of outgoing messages or their message priority.

The connection policies can be interrupted at run time by user code. This ability allows the user run-time code to decide when to connect, disconnect, or resume policy-based control. Additionally, if the idle timeout is set by the user code as a call parameter, a timeout causes the transmission control component to switch from connected state to resume policy-based control. (The Manual Connection policy is not able to resume policy-based control because its policy is to allow manual control only.)

The different connection policies and their predefined configurations are as follows:
Table 17. Connection policies and their predefined configurations
Connection policy Predefined configuration Default configuration
Always connected    
Manual connection    
Tariff-based Data X
  Connection time  
Message-based Priority and Volume X
  High priority  
Calendar Daytime  
  Nighttime X
  Hourly  
  Daily  
Always Connected connection policy
This connection policy is the default policy, and in its default configuration, it mimics the previous micro broker bridge behavior. That is, it tries to stay connected all the time, and if it detects a connection failure, it attempts to reconnect every 30 seconds. Configuration of the connection retry functionality is exposed through the Connection Retry Interval and Connection Retry Duration attributes:
Connection Retry Interval
If the micro broker bridge is unable to establish a remote connection when wanted, the time interval before it retries.
Connection Retry Duration
The time during which the micro broker bridge keeps retrying to establish a failed connection (after which it gives up).
Manual Connection connection policy
With this connection policy, the micro broker bridge does not connect automatically, but waits for user-written run-time code to decide when to turn on and off the transmission. Additionally, the user-called transmit-on method allows three parameters:
Idle Timeout
If this value is set, a timeout causes the transmission control component to switch from connected state to disconnected. The default value for the Idle Timeout is never.
Connection Retry Interval
If the micro broker bridge is unable to establish a remote connection when wanted, the time interval before it retries. The default value is immediately.
Connection Retry Duration
The time during which the micro broker bridge keeps retrying to establish a failed connection (after which it gives up). The default value is for ever.

There are no administrative attributes for the Manual Connection policy.

Tariff-based connection policy

This connection policy is intended for those situations where a device is connected to a network with expensive connection charges for data transmission or connection time, such as a mobile phone or PDA. The policy tries to connect often in short bursts.

The default configuration for this connection policy (Data) is as follows:
  • Attempt to connect every 5 minutes (from the end of the last connection). Disconnect after 30 seconds of inactivity (no messages have been sent or received 30 seconds after the send buffer has been emptied).
  • If failed to connect when attempting to, retry every minute (forever).
  • Otherwise, stay disconnected.
The other predefined configuration of this connection policy, for networks that are charged for connection time, has a shorter Idle Timeout (5 seconds). Both policies start initially disconnected so that the first connection is attempted after the connectionDelay has expired.
The predefined configurations for the Tariff-based connection policy are as follows:
Table 18. Tariff-based connection configurations
Name Connection Delay Maximum Connection Duration Idle Timeout Connection Retry Connection Retry Duration
Data (default) 5 minutes 30 seconds 30 seconds 1 minute forever
Connection Time 5 minutes 5 seconds 5 seconds 1 minute forever
The attributes for the Tariff-based connection policy are as follows:
Connection Delay
Time to connect measured from the end of the last connection.
Connection Duration
Disconnection based on a combination of:
Idle Timeout
No messages sent or received for this length of time.
Maximum Connection Duration
Disconnection occurs this many seconds after the connection is due, unless the Idle Timeout causes disconnection first.
Connection Retry Interval
If the micro broker bridge is unable to establish a remote connection when wanted, the time interval before it retries.
Connection Retry Duration
The time during which the micro broker bridge keeps retrying to establish a failed connection (after which it gives up).
Message-based connection policy

This connection policy is driven primarily by the arrival of messages. The default connection state is disconnected. Connection is activated when there is a sufficiently high volume of messages or messages of sufficient priority to send. Connection can also occur after a specific period from the last disconnection. This ability enables incoming messages to be processed when the message priority or volume are lower than typical. If the broker is stopped and restarted, the timer is reset (it does not remember across restarts).

The default configuration for this connection policy (Priority and Volume) is as follows:
  • Attempt to connect when any of the following are true:
    • When the highest priority of any messages in the send buffer is greater than or equal to 5. Disconnect when the buffer is empty.
    • When there are 10 or more messages in send buffer. Disconnect when the buffer is empty.
    • One hour after previous disconnection. Disconnect after idle time of 30 seconds.
  • If failed to connect when attempting to, retry every 10 minutes.
  • Otherwise, stay disconnected.
To enable you to more easily choose a configuration that suits the device and network conditions, there are predefined configurations of the Message-based connection policy, as described in the table Table 19. The message-based aspects of the configuration include low watermarks as well as high watermarks, like so:
  • Number of messages in send buffer:
    High Watermark
    Connection is attempted when the total number of messages has reached the high watermark.
    Low Watermark
    Connection continues until the total number of messages has been reduced to the low watermark.
  • Highest Priority of the messages in the send buffer:
    High Watermark
    Connection is attempted if there are any messages with this priority (or higher).
    Low Watermark
    Connection continues until the highest priority of any message is reduced to this low watermark. Message priorities run from 9 (high) down to 0 (low), then down to No Priority (for messages that do not have a priority set) and to No Messages (to empty the buffer).

One scenario is where the user wants to connect immediately whenever there are high-priority messages to be sent, but every now and again for the remaining low priority messages. The micro broker bridge can connect when there are any messages with a priority greater than or equal to the high watermark, send some messages, then disconnect when the highest priority message remaining is less than the low watermark.

Table 19. Message-based connection policy configurations
Name High Watermark Priority Low Watermark Priority High Watermark Number of Messages Low Watermark Number of Messages Connection Delay Idle Timeout Connection Retry Interval Connection Retry Duration
Priority and volume (default) 5 No messages 10 0 1 hour 30 seconds 1 minute 5 minutes
High Priority 9 4 0 0 1 week 30 seconds 30 seconds 1 hour
Note: Both default configurations have their Maximum Connection Duration equal to their Idle Timeout.
The attributes for the Message-based connection policy are as follows:
  • Number of messages in the send buffer:
    High Watermark
    Connection is attempted when the total number of messages reaches the high watermark.
    Low Watermark
    Connection continues until the total number of messages is reduced to the low watermark.
  • Highest priority of the messages in the send buffer:
    High Watermark
    Connection is attempted if there are any messages with this priority (or higher).
    Low Watermark
    Connection continues until the highest priority of any message is reduced to this low watermark. Message Priorities run from 9 (high) down to 0 (low), then down to No Priority (for messages that do not have a priority set) and to No Messages (to empty the buffer).
  • Connection Delay, after previous disconnection.
  • Connection Duration, disconnection based on a combination of:
    Idle Timeout
    No messages sent or received for this length of time.
    Maximum Connection Duration
    Disconnection occurs this many seconds after the connection is due, unless the Idle Timeout causes disconnection first.
  • Connection Retry Interval, if the micro broker bridge is unable to establish a remote connection when wanted, the time interval before it retries.
  • Connection Retry Duration, the time during which the micro broker bridge keeps retrying to establish a failed connection (after which it gives up).
Calendar connection policy

This connection policy is suitable for a device that primarily needs to connect periodically at set dates and times. It can also connect when there is a buildup of messages or when there are high-priority messages to be sent.

This connection policy can be used for those situations where a device is left unattended, with a network that is available only part of the time. The reasons might include:
  • A satellite, which appears only for a brief period every 24 hours.
  • A dial-up network, which might be costly and slow, so you want to limit connections to high-priority messages as they arrive in the micro broker bridge, with others being sent during an off-peak tariff period.
  • A heavily loaded network, where you want to limit the network activity of each device.
The default configuration for this connection policy (Night Time) is as follows:
  • Attempt to connect when any of the following are true:
    • Daily at 19:00 (local time).

      Disconnect 12 hours later (nominally at 06:00 the next morning, but may vary with daylight saving time).

    • When the highest priority of any messages in the send buffer is greater than or equal to 5.

      Disconnect when the highest priority of any message is reduced to 4.

    • When there are 50 (or more) messages in send buffer.

      Disconnect when the buffer is empty.

  • If failed to connect when attempting to, retry every hour.
  • Otherwise, stay disconnected.
See “Night Time” in Table 20.

You can alter the default values of the preceding attributes (or any of the others listed in the text that follows), but to enable to easily choose a configuration that suits your circumstances, there are several predefined configurations of the Calendar connection policy.

The following predefined configurations allow connection at a fixed time for a fixed duration (local time zone):
Table 20. Calendar configurations
Name Connect Time Maximum Connect Duration Idle Timeout High Watermark Priority Low Watermark Priority High Watermark Number of Messages Low Watermark Number of Messages Connection Retry Interval Connection Retry Duration
Day- time 07:00 12 hours Never 5 4 50 0 1 minute 1 hour
Night- time 19:00 12 hours Never 5 4 50 0 1 minute 1 hour
The following predefined configurations (Hourly and Daily) allow for connection at a fixed time every hour or day (local time zone). The connection ends after the maximum connection duration or an idle period, whichever is sooner. Connection can also be triggered by the highest message priority or message volume reaching their high watermark; in that case, connection ends when the low watermark is reached, as follows:
Table 21. Calendar hourly and daily connection configurations
Name Connect Time Maximum Connect Duration Idle Timeout High Watermark Priority Low Watermark Priority High Watermark Number of Messages Low Watermark Number of Messages Connection Retry Interval Connection Retry Duration
Hourly Every hour, on the hour 5 minutes 1 minute 5 4 10 0 1 minute 1 hour
Daily Daily at midnight 1 hour 1 minute 5 4 100 0 1 minute 1 hour
The attributes for the Calendar connection policy are as follows:
  • Time:
    • Connect Date/Time, combination of the following (either single value or array of values):
      • Day of week
      • Hour
      • Minute
    • Connection Duration, disconnection based on a combination of:
      • Idle Timeout: no messages sent or received for this length of time
      • Maximum Connection Duration: disconnection occurs this many seconds after the connection is due, unless the Idle Timeout causes disconnection first.
    • Number of messages in the send buffer:
      High Watermark
      Connection is attempted when the total number of messages reaches the high watermark.
      Low Watermark
      Connection continues until the total number of messages is reduced to the low watermark.
    • Highest priority of the messages in the send buffer:
      High Watermark
      Connection is attempted if there are any messages with this priority (or higher).
      Low Watermark
      Connection continues until the highest priority of any message is reduced to this low watermark. Message Priorities run from 9 (high) to 0 (low) to No Priority (for messages that do not have a priority set) and to No Messages (which effectively empties the buffer).
    • Connection Retry Interval: If the micro broker bridge is unable to establish a remote connection when desired, the time interval before it retries.
    • Connection Retry Duration: The time during which the micro broker bridge keeps retrying to establish a failed connection (after which it gives up).
Administrative API examples

This section details the additions to the Bridge administrative API.

The following code is an example of its use:
BrokerFactory f = com.ibm.micro.admin.BrokerFactory.INSTANCE; 
RemoteBroker b = f.getByAddress("tcp://localhost:1883"); 
b.logon("Admin", "Admin"); 
Bridge bridge = b.getBridge(); 
TransmissionControl tc; 
try { 	
        tc = bridge.createTransmissionControl(); 	
        MessageBasedConnectionPolicyDefinition cpd =  
               tc.createMessageBasedConnectionPolicyDefinition(); 	
        tc.setConnectionPolicy(cpd);
        // ... do something ... 	
        tc.transmitStart(); 	
        // ... do something ... 	
        tc.transmitStop(); 	
        // ... do something ... 	
        tc.transmitStart(); 	
        // ... do something ... 	
        tc.transmitAsPolicy(); 
} 
catch (AdminException e) {
       e.printStackTrace();
}

There are various policy definitions available, and the following sections show some examples of their use, which can be used in context with the example.

AlwaysConnectedConnectionPolicyDefinition
tc = bridge.createTransmissionControl(); 	
AlwaysConnectedConnectionPolicyDefinition cpd = tc.create AlwaysConnectedConnectionPolicyDefinition();
cpd.setConnectionRetryInterval(60); 	
tc.setConnectionPolicy(cpd);
ManualConnectionPolicyDefinition
tc = bridge.createTransmissionControl(); 	
ManualConnectionPolicyDefinition cpd = tc.createManualConnectionPolicyDefinition(); 
cpd.setIdleTimeout(60); 	
tc.setConnectionPolicy(cpd);
TariffBasedConnectionPolicyDefinition
tc = bridge.createTransmissionControl(); 	
TariffBasedConnectionPolicyDefinition cpd = tc.createTariffBasedConnectionPolicyDefinition(); 	
cpd.configureAsChargedOnConnectTime(); 	
cpd.setConnectionDelay(10); 	
tc.setConnectionPolicy(cpd);
MessageBasedConnectionPolicyDefinition
tc = bridge.createTransmissionControl(); 	
MessageBasedConnectionPolicyDefinition cpd = tc.createMessageBasedConnectionPolicyDefinition (); 	
cpd.configureAsPriorityAndVolume(); 	
tc.setConnectionPolicy(cpd);
CalendarConnectionPolicyDefinition
tc = bridge.createTransmissionControl(); 	
CalendarConnectionPolicyDefinition cpd = tc.createCalendarConnectionPolicyDefinition(); 	
cpd.configureAsDaily(); 	
/* 	 
 * Set the connection start time to 9:30, 11:30, 13:30, 15:30 and
 * 17:30 every Monday, Wednesday, and Friday. 	 
 */ 
int[] myDays = { 		
       Calendar.MONDAY,
       Calendar.WEDNESDAY, 		
       Calendar.FRIDAY 	
};
cpd.setConnectDaysOfWeek(myDays);
cpd.setConnectHours(new int[] {9,11,13,15,17});
cpd.setConnectMinute(30);
tc.setConnectionPolicy(cpd);

Message routing and transformations

The example in this section enables you to examine transformations in more detail. The diagram that follows illustrates a configuration with messages flowing in both directions between a micro broker and a WebSphere Event Broker.

Figure 1. Messages flowing in both directions between a micro broker and a WebSphere Event BrokerMessage flow diagram

Two flows have been configured, one inbound and one outbound flow, which means that the connection WBIEBConnection handles both incoming and outgoing (from the perspective of the micro broker) messages.

The outbound flow processes messages going from the micro broker out to event broker, and the inbound flow processes messages from event broker coming into the micro broker.

The outbound flow has specified that messages published to topic "devices" are published at the target end to the topic mb1/devices. In transit through the pipe, messages are passed through three user-written message transformations before being handed to the connection WBIEBConnection for delivery to Event Broker.

The inbound flow has specified that messages published to topic "mb1/control" are published at the target end to the topic "control". On the way, messages are passed through three user-written message transformations before being published by the micro broker.

Routing messages from micro broker to a queue owned by WebSphere MQ and back is similar. The diagram that follows shows an example:
Figure 2. Routing messages from micro broker to WebSphere MQ and backMessage routing diagram

As you can see, the topology is similar to the previous example, with the exception that the remote target is a queue (SYSTEM.DEFAULT.LOCAL.QUEUE) rather than a topic.

These examples have used topics as the source and target at the local micro broker, but you can use queues instead.

Although these examples show message transformations occurring in the bridge, enterprise message systems such as WebSphere Message Broker have rich function built in that makes it easy to transform messages. Unless there is a good reason to perform transformations in the micro broker's bridge, message transformation is typically better handled by the enterprise messaging system.

Bridging to a JMS provider using JNDI

With the use of the optional MicroBrokerBridgeJNDI bundle, a connection can be made to a JMS provider that supports JNDI. There are different requirements for using this additional functionality so make sure that you meet the prerequisites.

Configuring your JMS provider

To support sending messages to another JMS provider using QoS 2, a synchronization queue must be defined. This queue is used to temporarily store messages to ensure that they are delivered at the correct quality of service.

If your JMS provider does not support point-to-point messaging and a queue cannot be created, QoS 2 messages cannot be sent to your provider.

There is no default synchronization queue for a JNDI connection so you must create one if you wish to send QoS2 messages. A synchronization queue can be shared between different micro brokers and pipes within the same micro broker. To ensure that the queue is used correctly, two micro brokers with the same name must not use the same queue. If two micro brokers with different names are using the queue and their pipe names are the same, this approach is acceptable. Failure to use the queue correctly can lead to the loss of messages.

Setting up your environment
To bridge messages to a JMS server using JNDI, the JMS provider client bundles must be made available to the target OSGi runtime environment. To provide access to the required packages in the provider JMS client, the JAR files can be packaged as an OSGi bundle using the Lotus Expeditor Toolkit. The steps to do this are like those for packaging the WebSphere MQ 5.x and 6.0.0.0 JARs as shown in Bridging to WebSphere MQ. The differences for a third-party JMS provider are as follows:
  • Your Client Services project name must reflect that of your JMS provider rather than WebSphere MQ.
  • You need to determine exactly which JAR files are required for your provider for copying into the root of the new Client Services project. These files are provider-specific.
  • The META-INF / MANIFEST.MF file must display Bundle-Name and Bundle-SymbolicName attributes as appropriate for your provider. Similarly, the Bundle-ClassPath attribute must contain the list of JAR files for the JMS provider that were copied into the project previously.
  • The Export-Package attribute must contain the list of packages that your JMS provider provides for client applications. This list is provider-specific and exposes only those packages required by JMS applications to use the provider implementation of JMS.

The Lotus Expeditor platform contains bundles providing the javax.jms package, and some providers might include an implementation of this package within their JMS client code. If your Lotus Expeditor runtime already contains the Lotus Expeditor javax.jms packages, your Client Services project must not export them as well. If your Client Services project must export the javax.jms package, ensure that your Lotus Expeditor runtime does not also include the Lotus Expeditor implementation of the javax.jms package.

Bridging to WebSphere MQ

Micro broker prerequisites

The minimum level of WebSphere MQ required to run with the bridge is version 5.3 with CSD 9 installed.

The minimum level of Java required is J2SE 1.4.2 or the version specified for the WebSphere MQ Java Client if this is later.

Lotus Expeditor 6.2 provides the WebSphere MQ 7.0 Java Client in the feature com.ibm.mq.client.

Configuring the WebSphere MQ Queue Manager

To support sending messages to and receiving messages from a WebSphere MQ Queue Manager, a synchronization queue must be defined. This queue is used to temporarily store messages to ensure that they are delivered at the correct quality of service.

Each Queue Manager defined in the bridge must have a synchronization queue.

The naming convention for the synchronization queue for WebSphere MQ is fmb.sync.q. This synchronization queue can be shared between different micro brokers and pipes within the same micro broker. To ensure that the queue is used correctly, two micro brokers with the same name must not use the same queue. It is acceptable, however, for two micro brokers with different names to use the same synchronization queue even if their pipe names are the same . Failure to use the queue correctly can lead to the loss of messages.

Administering the micro broker bridge

This example shows how to obtain a reference to the bridge to define a pipe to a remote broker and add a flow in each direction to send messages between the two brokers.

Example:
Bridge bridge = broker.getBridge();
PipeDefinition pd = bridge.createPipeDefinition(“myPipe”);
		 
// Create a connection to a remote broker running on port 1884
MQTTConnectionDefinition cd = bridge.createMQTTConnectionDefinition("broker1884");
cd.setHost("127.0.0.1");
cd.setPort(1884);
cd.setKeepalive((short)45);
		 
// Set the connection on the pipe definition
pd.setConnection(cd);
		 
// Create 2 flows		 		 
FlowDefinition flow1 = bridge.createFlowDefinition("flow1");
flow1.setSources(new TopicDefinition[]{bridge.createTopicDefinition("out")});
flow1.setQos(0);
flow1.setTarget(bridge.createTopicDefinition("remote/out"));
 
FlowDefinition flow2 = bridge.createFlowDefinition("flow2");
flow2.setSources(new TopicDefinition[]{bridge.createTopicDefinition("in")});
flow2.setQos(0);
flow2.setTarget(bridge.createTopicDefinition("local/in"));
		 
// Add flow 1 such that messages coming from topic “out” on the local broker will be sent to topic “remote\out” on the remote broker
pd.addOutboundFlow(flow1);
 
// Add flow 2 such that messages coming from topic “out” on the remote broker will be sent to topic “local\in” on the local broker
pd.addInboundFlow(flow2);
 
// Add the pipe to the bridge
bridge.addPipe(pipeDef);

Adding Transformations

The bridge provides a framework for users to create and run their own transformations. These add-ons have to be defined and registered with the bridge.

Writing a new transformation

Transformations extend the com.ibm.micro.bridge.transformation.Transformation class and have a corresponding com.ibm.micro.bridge.transformation.TransformationFactory for creating instances of the transformation.

Here is an example of creating a transformation called MyTransformation. This transformation takes the input defined using the administration API to add to the payload. The destination topic also changes based on the message QoS.

Defining the transformation
  1. MyTransformation must extend the Transformation class. You must also define a local variable to hold the value to be added to the payload.
      public class MyTransformation extends Transformation
     {
        private String payloadSuffix = null;
  2. The initialise method obtains any parameters that were set using the administration interface. In this example, the user must use the setInput method on the TransformationDefinition to give the code “PAYLOAD_SUFFIX” the required value. If the parameter is not found, an exception can be thrown or a default used.
     
        public void initialise() throws BridgeException 
        {
           this.payloadSuffix = getProperties().getProperty("PAYLOAD_SUFFIX");
        }
  3. Implement the doTransformation() method specified on the Transformation class:
     
        public BridgeMessage doTransformation(BridgeMessage inputMessage)
        { 
           if (this.payloadSuffix != null)
           {
              // Append the suffix to the existing payload. This example
              // assumes the existing payload contains text
              String newPayload = new String(inputMessage.getBody()) + this.payloadSuffix;
              inputMessage.setBody(newPayload.getBytes());
           }
           try {
              // Append the qos value to the topic name.
              String qos = String.valueOf(inputMessage.getQoS());
              BridgeDestination newTopic = inputMessage.createTopic(inputMessage.getTarget()+qos);
              inputMessage.setTarget(newTopic);
           } catch(BridgeException ex) {
           }
           return inputMessage;
        }

In this method, we append the value of the payloadSuffix to the payload and append the QoS to the topic name. To find out what actions can be performed on the BridgeMessage refer to the API specification.

The doTranformation() method must return the transformed message or null. If null is returned, it indicates that the message is not to be sent. This type of logic can be used in a ReportByException transformation. If the message payload is equal to the value of the last message, then null is returned so messages with the same payload as the previous are not sent. This type of transformation can be useful when you want to be informed only of changes.

Defining the TransformationFactory
  1. MyTransformationFactory must extend the AbstractTransformationFactory class and implement the two methods:
    public class MyTransformationFactory extends AbstractTransformationFactory
     {
        public String getName()
        {
           return MyTransformation.class.getName();
        }
        public Transformation getTransformation()
        {
           return new MyTransformation();
        }
     }
    The getName() method must return a unique name for the transformation. This unique name can then refer to transformation within the TransformationDefinition API. The class name is usually a good value to use. The getTransformation() method has to return a new instance of the transformation.
For more information about writing a transformation, refer to the API specification for:
  • com.ibm.micro.bridge.transformation.Transformation
  • com.ibm.micro.bridge.transformation.TransformationFactory
  • com.ibm.micro.bridge.transformation.BridgeMessage

Enabling transformations

After a transformation has been written, you must register its factory so that the Bridge is aware of its presence and so that it can be used:
MyTransformationFactory mtf = new MyTransformationFactory();
 TransformationRegistry.INSTANCE.registerTransformationFactory(mtf);
When running within OSGi, the transformation needs to be provided by a bundle with the bundle activator performing this registration.
 import com.ibm.micro.bridge.transformation.TransformationRegistry;
 public class Activator implements BundleActivator
 {
    public static final String PLUGIN_ID = "MyTransformationBundle";
    private MyTransformationFactory factory;
    public Activator()
    {
       // Create a new instance of the factory
       factory = new MyTransformationFactory();
    }      
    public void start(BundleContext context) throws Exception
    {
       // Register the factory
       TransformationRegistry.INSTANCE.registerTransformationFactory(mtf);
    }
    public void stop(BundleContext context) throws Exception
    {
       // Unregister the factory
       TransformationRegistry.INSTANCE.unregisterTransformationFactory(mtf);
    }
 }
The MANIFEST.MF file for the bundle includes the following entry:
Import-Package: com.ibm.micro.bridge.transformation, com.ibm.micro.registry
Using transformations

Transformations can be defined for individual inbound or outbound flows or, if appropriate, default inbound or outbound transformations can be defined for a pipe. These default transformations are then applied to those inbound or outbound flows within the pipe that do not have their own defined transformations.

Multiple transformations can be “chained” in sequence and the combination attached to a flow or pipe. Thus, a message enters a flow and undergoes the first transformation. The output of the transformation is then passed to the next transformation in the chain, and so on, until all transformations have been applied and the message passes to the receiving end of the flow.

One or more transformations are attached to a flow or pipe by creating a TransformationDefinitionList. This list contains a TransformationDefinition entry for each transformation to be applied, and a list might consist of a single item if only one transformation is required for the particular flow or pipe it is intended for.

An example is shown here:
//Create a Transformation Definition
		TransformationDefinition transdef = bridge.createTransformationDefinition("myTransformationDefinition");;
		transdef.setClassName(MyTransformation.class.getName());

//Add the Transformation Definition to the Transformation Definition List
		TransformationDefinitionList transDefList = bridge.createTransformationDefinitionList();
		transDefList.addTransformation(transdef);
Next, add the transformation definition list to either flow or pipe. An example of adding the transformation definition list to the outbound Flow of the pipe:
pipe.setDefaultOutboundTransformations(transDefList);
An example of adding the transformation definition list to the inbound Flow of the pipe:
pipe.setDefaultInboundTransformations(transDefList);
An example of adding the transformation definition list to a flow:
flow.setTransformations(transDefList);

If required, parameters can be passed to a transformation using the TransformationDefinitino.setInput() method as illustrated in Using the built-in transformations.

Using the built-in transformations

Built-in transformations are supplied with the micro broker and enabled for use with pipes and flows in the bridge by default.

  • com.ibm.micro.bridge.transformation.AddPrefixToResourceName: A simple transformation that adds a topic prefix to the topic as a prefix. This transformation can be used only with topics. The prefix can be set by using the TransformationDefinition.setInput() method with key "input" and value being the prefix.
  • com.ibm.micro.bridge.transformation.AddSuffixToResourceName: A simple transformation that appends a topic suffix to the topic. This transformation can be used only with topics. The suffix can be set by using the TransformationDefinition.setInput() method with key "input" and value being the suffix.
  • com.ibm.micro.bridge.transformation.SetResourceName: Sets the target resource name. If the source is a topic, then the target is created as a topic. If the source is a queue, then the target is created as a queue.
Example usage of a built-in transformation
A code example of a built-in transformation:
AddPrefixToResourceNameFactory addPref = new 
AddPrefixToResourceNameFactory();
TransformationRegistry.INSTANCE.registerTransformationFactory(addPref);

Set the input for the transformation using the transformation definition instance: transdef.setInput("input", "sample_prefix");.

Advanced transformations

The following information shows how transformations can be based on payload types and can provide different results for each payload type.

To enable different transformations based on message type, the function getMessagePayloadType() in the BridgeMessage must be used to determine the type of message being processed.

int payloadType = inputMsg.getMessagePayloadType();
		switch (payloadType) {
		case MessagePayload.PAYLOAD_TYPE_BYTES:
			BytesPayload bytePayload = (BytesPayload)inputMsg.getMessagePayload();
			//Transform the byte message here 
			break;
		case MessagePayload.PAYLOAD_TYPE_TEXT:
			TextPayload textPayload = (TextPayload)inputMsg.getMessagePayload();
			//Transform the text message here
			break;
		case MessagePayload.PAYLOAD_TYPE_STREAM:
			StreamPayload streamPayload = (StreamPayload)inputMsg.getMessagePayload();
			//Transform the stream message here
			break;
		case MessagePayload.PAYLOAD_TYPE_MAP:
			MapPayload mapPayload = (MapPayload)inputMsg.getMessagePayload();
			//Transform the map message here
			break;
		case MessagePayload.PAYLOAD_TYPE_OBJECT:
			ObjectPayload objectPayload = (ObjectPayload)inputMsg.getMessagePayload();
			//Transform the object message here
			break;
		default:
			break;
		}
Changing the payload type in transformations
The PayloadFactory class can be used to change the payload type.
int payloadType = inputMsg.getMessagePayloadType();
		switch (payloadType) {
		case MessagePayload.PAYLOAD_TYPE_BYTES:
			BytesPayload bytePayload = (BytesPayload)inputMsg.getMessagePayload();
			TextPayload textPayload = PayloadFactory.createTextPayload(bytePayload);
			inputMsg.setMessagePayload(textPayload); 
			break;
		}

Using transformations in the bridge

After a transformation has been created and the bundle is loaded into the OSGi environment, the transformation can be used by a pipe or flow within a bridge. Refer to the Bridge Administration API Javadoc for details on how to use transformations.

Adding JNDI security properties

This section describes how to add JNDI security properties.

The bridge provides a framework for users to supply JNDI security credentials in a secure manner by defining a class that is used at run time from which to obtain the credentials. How this class obtains the credentials is entirely open. The class can display a graphical user interface to ask the user to enter the details at run time or can read the details from a secure file.

Writing a JNDI security bundle

You can access JNDI security classes that are available to the micro broker runtime in a bundle using a registry framework. This framework works in a similar way as the registration of bridge transformations described elsewhere. Factory classes for creating security class instances are stored in a registry with a unique name. The JNDIConnectionDefinition that is created when administering the bridge JNDI connection can then specify the name of the factory for creating a JNDI security class instance for that connection.

When creating a micro broker JNDI Security bundle, note that the bundle manifest needs to import both the com.ibm.micro.bridge.jndi and com.ibm.micro.registry packages to work properly.

The activator for the OSGI bundle is set up similarly to the following example, which registers a security factory implemented by a class called SampleJNDISecurityFactory. The bundle requires the JNDI Security Registry service to be running before a security factory can be registered and uses an OSGI Service Tracker to do this step in the start () method of the Activator:
JNDISecurityRegistry regService = null;
SampleJNDISecurityFactory jndiFactory = null;
ServiceTracker jndiST = null;
BundleContext context = null;

public void start(BundleContext ctx) throws Exception {
        context = ctx;
        jndiFactory = new SampleJNDISecurityFactory();
        jndiST = new ServiceTracker(context, JNDISecurityRegistry.class.getName(), 
                                    this);
        jndiST.open();
}
The Service Tracker has a callback mechanism such that a class can be notified when a given OSGI service is available. In the example, the code waits for this service to become available through the Service Tracker. For the Service Tracker callback to the bundle to work properly according to the previous example, the bundle needs to implement the ServiceTrackerCustomizer interface from the OSGI runtime. In the ServiceTrackerCustomizer addingService () method, the following code then registers the factory with the JNDI Security Registry:
public Object addingService(ServiceReference ref) {
        regService = (JNDISecurityRegistry)context.getService(ref);
        try {
                regService.registerJNDISecurityFactory(jndiFactory);
        } catch (RegistryException e) {
                e.printStackTrace();
        }
        return regService;
}
To complete the full life cycle of the security bundle, the following housekeeping is to be performed in the stop () method of the activator to remove the reference to the security factory and release any resources associated with the Service Tracker:
public void stop(BundleContext arg0) throws Exception {
        regService.unregisterJNDISecurityFactory(jndiFactory);
        jndiST.close();
}

In this way, the customer security factory has been registered with the JNDI Security Registry and is now available for use with a JNDI bridge connection.

Writing a new JNDI security class

JNDI Security classes need to implement the com.ibm.micro.bridge.jndi.JNDISecurity interface and have a corresponding com.ibm.micro.bridge.jndi.JNDISecurityFactory type, which is used to create instances of the JNDI Security class.

Here is an example in which a JNDI Security class called MyJNDISecurity is created. This class supplies some security parameters by storing them in the class.

SampleJNDISecurity must implement the JNDISecurity interface and implement the getSecurityProperties() method.
public class SampleJNDISecurity implements JNDISecurity{

public Properties getSecurityProperties() throws BridgeException {
Properties p = new Properties();
p.setProperty(JNDIConnectionDefinition.SECURITY_AUTHENTICATION, "simple");
p.setProperty(JNDIConnectionDefinition.SECURITY_CREDENTIALS, "secret");

return p;
}
}
In this example, the user is supplying two security properties, the authentication and credentials.
SampleJNDISecurityFactory must extend the AbstractJNDISecurityFactory class and implement the two methods:
public class SampleJNDISecurityFactory extends AbstractJNDISecurityFactory {

public JNDISecurity getJNDISecurity() {
return new SampleJNDISecurity(); 
}

public String getName() {
return SampleJNDISecurity.class.getName(); 
}
  
}
The getName () method has to return the name of the JNDISecurity class, and the getJNDISecurity method has to return a new instance of the JNDISecurity class.

The getName () method does not have to return the class name, as shown in the preceding example. It must, however, return a unique name for the class, so the class name is typically a good value to use as the unique name. Whatever value is used here, the same value must be used for the setSecurityClassName() method in the JNDIConnectionDefinition API. When the class is registered, it uses this name to identify itself so that when you want to use the class you must use the same identifier.

For more information about writing a JNDISecurity class, refer to the API specification for com.ibm.micro.bridge.jndi.JNDISecurity and com.ibm.micro.bridge.jndi.JNDISecurityFactory.

Using JNDI security classes with the bridge

Now that you have created new JNDI security classes and factories and registered them with the JNDI Security Registry, the final step is to configure the bridge connection to use them. Do this using the connection definition for the bridge JNDI connection as in the following example:
JNDIConnectionDefinition swtest = bridge.createJNDIConnectionDefinition("secConn");
swtest.setSecurityClassName(SampleJNDISecurity.class.getName()); 
The value specified in the setSecurityClassName matches the value that is returned by the getName () method of the JNDISecurityFactory implementation required. This link is the link between the factory registered through the bundle and the JNDI bridge connection itself. After you have set this value, when the bridge connects through the JNDI provider, it now finds the security factory in the registry and applies the required security logic.

Connecting to a broker

This section describes how to connect to a broker.

Obtaining a reference to a local broker in the same VM as the application

This example shows how to obtain a reference to a local broker started in bindings mode:
if (factory.exists(brokerName)) {
      broker = factory.getByName(brokerName);
}

Obtaining a reference to a remote broker

This example shows how to obtain a reference to a remote broker:
RemoteBroker broker = f.getByAddress("tcp://localhost:1883");

//The default username and password is admin / admin.
broker.logon("Admin", "Admin");

Administering listeners

A listener handles new incoming communications requests.

You can create two types of listeners:
MQTT TCP/IP listener
Allows connections from MQTT clients to be received over TCP/IP. One of the properties that you specify when the listener is created is the TCP/IP port on which the broker listens for connections. You can have multiple listeners on different TCP/IP ports, if required.
MQTT local listener
Allows connections to be received from clients running in the same Virtual Machine (VM) that implements the Java specifications as the broker without requiring TCP/IP. MQTT local listeners are recommended when clients are running in the same VM as the micro broker because a local listener consumes fewer resources than a TCP/IP listener. Only one local listener is allowed per broker.

The broker can have multiple TCP/IP listeners with different names, port numbers, being bound to different network interfaces and with different retry intervals. By default, the broker starts one unencrypted TCP/IP listener on the port set in broker preferences (1883 by default), and the local listener for applications running on the same Java Virtual Machine (JVM) as the broker. It is also possible to configure secure listeners (using the SSL/TLS protocols). The default port for a secure listener is 8883. There is no performance improvement gained by using multiple TCP/IP listeners. The recommended practice is to use one TCP/IP listener for all traffic to the broker.

The administration API provides methods to create and delete listeners. After you have created a listener, you can use the administration API to perform other actions, such as getting a list of all clients connected through the listener, getting the listener name, and starting and stopping the listener.

If you need to stop the listener, there are two options. You can immediately stop the listener, or you can quiesce it to stop. When the listener is stopped immediately, it stops accepting connections and it immediately disconnects all clients that are connected through the listener. A listener that is quiesced stops accepting new connections, but it leaves all clients that are connected through the listener connected to the broker. Quiesce is a cleaner way of stopping a listener, as it allows clients to disconnect in their own time without being abruptly stopped. If a client never disconnects, the listener never stops. In this case, you can issue another stop request to immediately stop the listener if necessary.

Example: creating a listener

Use the administration API to create a listener on TCP/IP port 1884.

Communications comms = broker.getCommunications();
MQTTTCPListenerDefinition tcpdef = 
     comms.createMQTTTCPListenerDefinition(1884);
// By default the listener will bind to all network interfaces.
// Restrict it to listen on the local interface only, thereby
// not allowing connections from remote machines.
tcpDef.setNetworkInterface("127.0.0.1");
comms.addTCPListener( tcpdef );

Example of stopping and deleting a listener

Use the administration API to stop and delete a listener on TCP/IP port 1884.

This action can be achieved in two ways:
  • If the listener name or definition is already known:
    // Assumming the listener name or definition is already known
    MQTTTCPListenerDefinition tcpdef = ...;
    Communications comms = broker.getCommunications();
    Listener listener = comms.getListener( tcpdef.getName() );
    listener.stop( false );
  • If the listener name or definition is not known:
    // If the listener name or definition is not known then iterate through
    // the known listeners looking for the one for TCP/IP port 1884
    Communications comms = broker.getCommunications();
    Listener[] listeners = comms.getListeners();
    for ( int i=0; i < listeners.length; i++ ) {
          if ( listeners[i] instanceof MQTTTCPListener ) {
                MQTTTCPListenerDefinition tcpdef = 
                      ((MQTTTCPListener)listeners[i]).getDefinition();
                if ( tcpdef.getPort() == 1884 ) {
                      listeners[i].stop( false );
                      listeners[i].remove();
                }
          }
    }

Administering queues

Application queues can be created on the Messaging Engine component for use with point-to-point messaging.

There are three types of queues:
  • Static queues, which are configured through the Administrative API.
  • Dynamic queues, which are created automatically on "first use" by an application. The dynamic queues feature is intended to dramatically reduce queue administration, and it means that a point-to-point JMS application can start sending or receiving messages from a queue. The micro broker creates the queue if it does not exist.
  • Temporary queues, which are created through JMS application code and survive for the lifetime of the JMS connection.

The key difference between the three types of queues is their life cycle. A statically created queue exists on the broker until it is administratively deleted. A dynamically created queue is expired (deleted) automatically if it is empty and not opened for a defined, configurable period. The default period is 28 days. Expiring queues helps make more efficient use of broker resources, and no messages are lost because the queue is expired only if it is empty. Any applications attempting to use the queue after expiry cause it to be re-created.

Using the MessagingEngine component from the Administrative API, you can retrieve information about all three types of queues and perform other operations, such as clearing messages off a queue and deleting a queue.

The following code is example code to create a static queue, changing the default queue depth to 2000 messages:
MessagingEngine messagingEngine = broker.getMessagingEngine(); 	
QueueDefinition queueDefinition = messagingEngine.createQueueDefinition("MyQueue"); 	
queueDefinition.setMaximumDepth(2000); 	
messagingEngine.createStaticQueue(queueDefinition);

Migration information

Bundles that use the micro broker administrative API, and that also use the "Require-Bundle" header in the manifest, need to be updated to use the "Import-Package" header instead. The administrative API is now in the bundle com.ibm.micro.admin. It is considered a best practice to manage imports at the package level, as it makes dependencies less sensitive to bundle changes.

Guidance on deployment environments

The micro broker is a flexible and powerful messaging platform that works in a wide variety of solution environments. The following section provides guidance for deploying the micro broker, which takes into account the design intent, and the environments in which it has been tested.

  • Reliable messaging does not work in environments that use network-level load balancing (such as IP sprayers). The quality of service offered by the broker that ensures delivery cannot be relied on in these environments.
  • The micro broker is not to be used on systems that are subject to large clock changes while the broker is running. The micro broker uses timers internally, and changing the system clock can cause strange and unexpected behavior. For example, this behavior can happen on systems that use the Network Time Protocol (NTP) for automatic clock updates, where the clock is updated by more than a second or two at a time.
  • The micro broker is not to be used with persistence set to "shutdown" or "full", when the underlying file system uses compression or encryption. This state is unsupported.
  • It is common practice for users to write tools that subscribe to topics on the micro broker, to observe messages flowing through the system. Be aware of the performance effect that such tools can have on a system in production. For example, subscribing to "#" (all messages) can effectively double the workload on the broker, as every message it receives needs to be sent out again at least once.

Assembling and deploying

This section describes how to assemble and deploy Lotus Expeditor Client.

Extending the platform

This section describes how to extend the platform.

Specifying platform branding and theme

The Lotus Expeditor Client Workbench uses Eclipse products and Eclipse themes for branding. Create your own branding plug-in with your product information instead of changing the one shipped with the Lotus Expeditor Client. The Lotus Expeditor Toolkit contains a Branding sample. You can refer to the sample when following these instructions for creating a product branding.

A developer follows these steps to change the Workbench branding:
  1. Create a branding plug-in, for example, com.ibm.rcp.samples.personality.branding.
  2. Create a plugin.xml file with Eclipse Products (org.eclipse.core.runtime.products) extension in the com.ibm.rcp.samples.personality.branding plug-in.
  3. Include the preferenceCustomization property in the Products extension to specify the preference customization file to use.
  4. Include an Eclipse Themes (org.eclipse.ui.themes) extension in the plugin.xml file in the com.ibm.rcp.samples.personality.branding plug-in.
  5. Include a preference customization file that is specified in the Eclipse Products extension. This file is the new_plugin_customization.ini file in the com.ibm.rcp.samples.personality.branding plug-in.
    Attention: It is recommended that you start with the plugin_customization.ini supplied with the Lotus Expeditor branding plug-in, or with the new_plugin_customization.ini file supplied with the sample, as these files contain necessary default preference settings.
  6. Include the splash screen to be used for the product in the plug-in.
  7. Create a feature for the preceding plug-in.
  8. Use the global install handler to specify the product attribute of the branding feature in the rcplauncher.properties file so that the correct product and application are used on launch.. See Using the global install handler for details.

    For example, in the feature provided with the sample, the handler.properties contains product=com.ibm.rcp.samples.personality.branding.SopwithLlamaProduct where this product identifier is the ID specified in the Products Extension in step 2.

  9. Use the global install handler to set the osgi.splashPath of the branding feature to change the splash screen in the rcplauncher.properties file. The syntax must be URL syntax. For example, osgi.splashPath=platform:/base/../shared/eclipse/plugins/com.ibm.rcp.samples.personality.branding.
  10. Deploy the branding feature as part of the initial install by updating the provisioning manifest.

Providing your own product branding

Product branding is specified in the Eclipse product extension point.

The following code is the code example for default branding used by the Lotus Expeditor Client:
<extension 
   id="DefaultProduct" 
   point="org.eclipse.core.runtime.products"> 
   <product 
   	name="%product.name"
   	application="com.ibm.rcp.personality.framework.RCPApplication"
   	description="%product.description">
   	   <property name="appName" value="DefaultPlatform" />
         <property name="aboutText" value="%productAboutText" />
         <property name="windowImages" value="icons/16.gif,images/32.gif" />
         <property name="aboutImage" value="icons/productAbout.bmp" />
         <property name="preferenceCustomization" value= "platform:/plugin/
      com.ibm.rcp.platform.personality.branding/plugin_customization.ini"/>
   </product>
 </extension>
To deploy your own branding, you must create a new branding plug-in and feature and deploy them as part of the initial installation by updating the provisioning manifest. The new branding feature must use the global install-handler to modify the product attribute in the rcplauncher.properties file.

Use the preceding snippet as an example for providing your branding. Replace com.ibm.rcp.platform.personality.branding in the snippet with the name of your branding plug-in.

Specifying the Window title

The title bar appears at the top of the client platform and typically contains the name of the workbench and a small graphic.

To modify the product title bar, you specify the name attribute of the product extension in the plugin.xml file of your branding plug-in.

Code example of the product extension in the plugin.xml file:

 <extension
         id="SopwithLlamaProduct"
         point="org.eclipse.core.runtime.products">
      <product
            application="com.ibm.rcp.personality.framework.RCPApplication"
            description="%product.description.0"
            name="%product.name.0">

Provide the actual value of the product name in the plugin.properties file of your branding plug-in.

Code example from plugin.properties:
product.description.0 = Sopwith Llama's Leading
Customer Service Application
product.name.0 = Sopwith Llama Smorgashboard

Provide a plugin_locale.properties file in the plug-in if you need to provide content for multiple languages. Repeat each of the keys from plugin.properties that need to be different for the locale.

Specifying the Window image

On Microsoft Windows systems, a small image is associated with the product and is displayed in the title bar, next to the product title. You can modify this image to be consistent with your branding.

Standard Widget Tools (SWT) allows a set of images to be associated with a shell with the expectation that all the images in the set have the same appearance but are rendered at different sizes. These images are provided to the SWT shell, which is then able to select the most appropriate one for each specific use. For example, the smaller image (16 X 16) is used for the title and task bars while the larger image (32 X 32) is used in the Alt-Tab application switcher.

Code example:
<property name="windowImages" value=
"platform:/plugin/com.ibm.rcp.samples.personality.branding.images/icons/16.gif,
platform:/plugin/com.ibm.rcp.samples.personality.branding.images/icons/32.gif"/>
While the sample provides its window images in the same plug-in, it is possible for the images to be provided in a separate plug-in. If so, use a URL, such as platform:/plugin/pluginidwithoutversion/dir/filename, for the image. For example, if there was a separate com.ibm.rcp.samples.personality.branding.images plug-in, then the windowImages property might appear like:

"platform:/plugin/com.ibm.rcp.samples.personality.branding.images/icons/16.gif,
platform:/plugin/com.ibm.rcp.samples.personality.branding.images/icons/32.gif"/>
Specifying the About dialog image

To specify branding of the About dialog, you must specify the image shown in the About dialog box.

The image shown in the About dialog must be a file with a .bmp extension. A full-sized product image (no larger than 500 x 330 pixels) is shown without the "aboutText" text. A half-sized product image (no larger than 250 x 330 pixels) is shown with the "aboutText" text beside it.

Code example:
<property name="aboutImage" value="icons/productAbout.bmp" />

You can have different About dialog images for each locale that the product supports. When a user opens the About dialog, the system detects the locale of the machine and then selects the About dialog image from the appropriate language directory.

A locale-specific image must reside in the nl/dir/localedirectory of either the plug-in supplying the images or a fragment associated with that plug-in. For example, in the com.ibm.rcp.samples.personality.branding plug-in, if there is a French-specific About image, then the productAbout.bmp file from the nl/icons/fr directory is used.

If the system does not find an About dialog image for your locale, then the system selects the default image from the com.myco.example_version_number\exampleimages directory.

Specifying the About dialog text

Specify the text that is displayed next to the image in the About dialog using the aboutText property.

Code example:
<property name="aboutText" value="About Sopwith Llama Smorgashboard" />
Specifying the splash screen

When a user launches the workbench, a splash screen image is displayed. You can replace the splash screen image with your own image. The splash screen must have the file extension .bmp. There are no constraints regarding the size of the image, but for reference, the standard Eclipse splash screen image is 500 x 300 pixels.

You can have a different splash screen for each locale that the product supports. When the application starts, the launcher determines the locale of the machine and then selects the splash screen image from the appropriate language directory in the plugins directory. For example, a splash screen for the French locale resides in the nl/fr directory.

To use your own splash screen, include the splash image in your branding plug-in. In your branding feature, use the global install handler to set the osgi.splashPath Java system property, osgi.splashPath=. The syntax must be URL syntax. For example: osgi.splashPath=platform:/base/../shared/eclipse/plugins/com.ibm.rcp.samples.personality.branding

Specifying your own help home page

Help Contents for the product can be accessed by clicking Help > Help Contents. To change the default help home page to one for your own product, provide the new help page as a fragment to org.eclipse.help.base. You must use a different name from what is currently used (for example, help_home.html and rcp_help_home.html are already used). The default help fragment provided by the Lotus Expeditor Client is com.ibm.rcp.platform.personality.branding.help. It is recommended that you use this fragment as an example to create your own help fragment. Changing the one provided by the Lotus Expeditor Client and using it is not recommended.

The product branding plug-in contains the help page preference in the product plugin_customization.ini, such as:
org.eclipse.help.base/help_home=/org.eclipse.help.base/doc/myproduct_help_home.html

(The branding sample does not supply a different help home page.)

Specifying the theme

The overall look and feel of the client is driven by a combination of Eclipse themes extensions and cascading style sheet (CSS) content.

Elements specific to product branding such as the color or visibility of the banner bar are driven by dedicated data key/value elements of an Eclipse theme extension. The look and feel for items such as the launch button, toolbars, and presentation factory is driven by the CSS content.

The banner area consists of an image on the right, an image on the left, and a tiled background image. Switching between applications changes the name and images displayed in the banner area. The system derives the application name to use from the applications contributed through extension points or through composite application definitions.

The banner area resides at the top of the workbench window, directly below the menu bar. You can customize all the visual elements of the banner to suit your needs:
  • Banner images
  • Banner background color
  • Banner application title (font, position, color, and text)
Specifying the banner image
You can specify the banner images in the plugin.xml file of your branding plug-in.
  <data
	 name="com.ibm.rcp.platform.BRANDING_BAR_VISIBLE"
	 value="true">
  </data>
	  
  <data
	 name="com.ibm.rcp.platform.BRANDING_BAR_IMAGE_LEFT"
	 value="platform:/plugin/com.ibm.rcp.samples.personality.branding_6.1.0/
icons/brand_bar_left.gif"> </data> <data name="com.ibm.rcp.platform.BRANDING_BAR_IMAGE_BACKGROUND" value="platform:/plugin/com.ibm.rcp.samples.personality.branding_6.1.0/
icons/stripe.gif"> </data> <data name="com.ibm.rcp.platform.BRANDING_BAR_IMAGE_RIGHT" value="platform:/plugin/com.ibm.rcp.samples.personality.branding_6.1.0/
icons/brand_bar_right.gif"> </data> <data name="com.ibm.rcp.platform.BRANDING_BAR_ICONS_ONLY" value="false"> </data>
Specifying the background image

The background image is the image that displays in the main data area of the workbench when no applications are opened. You can specify the background to display your own image.

A background image smaller than 500 x 330 pixels is tiled in the x and y directions. A background image 500 x 330 pixels or larger is centered.

Code example for the default background image used by the Lotus Expeditor Client:
 <data 
         name="WORKBENCH_BG_IMAGE"
         value="platform:/plugin/com.ibm.rcp.samples.personality.branding/icons/default_background.gif">
	  </data>

You can also change the image path and file name by specifying the defaultBackgroundImage property in the plugin_customization.ini file in the plugin.xml file of your branding plug-in.

To point to an image in the nl directory, you can set the value of defaultBackgroundImage to $nl$/new_default_background.gif.

Specifying the banner color
You can specify the banner color in the plugin.xml file of your branding plug-i. (The sample does not use these attributes, as it supplies images to be used.)
 <colorDefinition
         label="%BrandingBarForegroundColor"
         value="255,255,255"
         id="com.ibm.rcp.platform.BRANDING_BAR_FOREGROUND_COLOR">
         <description>
         </description>
      </colorDefinition>
      
      <colorDefinition
         label="%BrandingBarBackgroundColor"
         value="0,0,0"
         id="com.ibm.rcp.platform.BRANDING_BAR_BACKGROUND_COLOR">
         <description>
         </description>
      </colorDefinition>
      
      <colorDefinition
         label="%BrandingBarBackgroundColorBegin"
         value="56,56,56"
         id="com.ibm.rcp.platform.BRANDING_BAR_BACKGROUND_COLOR_BEGIN">
         <description>
         </description>
      </colorDefinition>
      
      <colorDefinition
         label="%BrandingBarBackgroundColorEnd"
         value="80,80,80"
         id="com.ibm.rcp.platform.BRANDING_BAR_BACKGROUND_COLOR_END">
         <description>
         </description>
      </colorDefinition>     
…
Specifying the banner application title font
You can specify the banner color in the plugin.xml file of your branding plug-in.
 <data
	 name="com.ibm.rcp.platform.BRANDING_BAR_FONT_POINT_SIZE"
	 value="14">
 </data>
Specifying the status line

You can specify if your product has a Status Line in the plugin.xml file of your branding plug-in.

<extension point="org.eclipse.ui.themes">
    <theme id="MyProductGreenTheme">
      <description>
         This is the My Product Green Theme
      </description>
      ...
	          <data
		              name="com.ibm.rcp.platform.STATUS_LINE_VISIBLE"
		        value="true">
	          </data>
Specifying a theme using CSS content
To contribute a theme using CSS content, first extend the com.ibm.rcp.ui.themes extension point. Themes extensions specify CSS content, a human-readable name for the theme, and an optional preview image for the theme. Following is an example of a theme extension. Refer to the Themes schema in Developing Applications for Lotus Expeditor.
<extension
  point="com.ibm.rcp.ui.themes">
    <theme
      id="com.ibm.rcp.ui.themes.mytheme"
      label="MYTEST Theme"
      css="themes/global.css"
      previewImage="themes/mytesttheme_preview.png">
    </theme>
</extension>
The current theme is specified using an Eclipse preference. The preference ID used to specify the theme is WED_THEME_PREFERENCE in the com.ibm.rcp.ui namespace. This preference is specified in plugin_customization.ini of your branding plugin. Following is an example of how to specify the value of this preference:
com.ibm.rcp.ui/WED_THEME_PREFERENCE= com.ibm.rcp.ui.themes.mytheme
Next, create a CSS file and add your new styles to it. You need to import the platform CSS file. The syntax for importing your CSS file is as follows:
@import url("platform:/plugin/com.ibm.rcp.ui.css/themes/wed61/global.css");
Note: The font chosen in the Fonts Preference page is applied only to controls that have an associated CSS content and have an absolute-size value defined in the theme .css file.

Distributing branding updates

To deploy your own branding, create a new branding plug-in and feature and deploy it as part of the initial installation by updating the provisioning manifest or using any of the provision capabilities.

The product property in the rcpinstall.properties file must be updated to refer to product ID defined by your new branding plugin. See Updating the rcpinstall properties file for more information.

Configuring the Portlet Container branding

You can modify the look and feel of portlets. Use the instructions in this section to modify the portlet user interface elements used by the Portlet Container.

The Portlet Container branding extension applies to all portlets deployed to the IBM Lotus Expeditor runtime.

These instructions include the creation and deployment of a branding Web application. This Web application includes the portlet user interface elements including the HTML style sheet, the icons, and the screen colors.

To modify the look and feel of portlets, follow these steps:
  1. Create a Client Services Web project. Refer to "Developing Web applications" in Developing Applications for Lotus Expeditor for instructions on how to create a Web application.
  2. Select Import > General > File System to add the branding resources (styleSheet and icons, for example) to the Web application.
  3. Open the plugin.xml descriptor and add a com.ibm.rcp.portletcontainer.branding.theme extension contribution.
    The following code is an example of a branding extension for Expeditor 6.2:
    <extension point="com.ibm.rcp.portletcontainer.branding.theme"> 
    	<theme styleSheet="/theme/Styles.css"
          	 maximizeIcon="/images/maximize.gif"
          	 minimizeIcon="/images/minimize.gif"
          	 restoreIcon="/images/back.gif"
          	 editIcon="/images/edit.gif"
          	 helpIcon="/images/help.gif"
          	 aboutIcon="/images/about.gif"
          	 configIcon="/images/config.gif"
          	 editDefaultsIcon="/images/edit_defaults.gif"
          	 previewIcon="/images/preview.gif"
          	 printIcon="/images/print.gif"
          	 titleBarColor="#5495D5"
          	 contentColor="#FFFFFF"/> 
       </extension>
    Note: Administrators modify the resource paths to match how the resources are packaged in the Web application.
  4. Click the Save button to save all changes made to the plugin.xml descriptor. The branding Web application is now ready to be distributed to the IBM Lotus Expeditor runtime.
  5. See Packaging applications for deployment for instructions on how to distribute the branding Web application.

Configuring enterprise definitions (JNDI)

This section describes how to deploy an application that is configured with an initial set of enterprise definitions.

Lotus Expeditor Client JNDI overview

The Lotus Expeditor Client runtime provides a simple Java object JNDI registry to support the enterprise object definition needs of Web applications, EJB applications, and messaging applications.

The Lotus Expeditor Client JNDI provider enables a local naming directory for objects running in the client platform to communicate through standard Java naming APIs. The runtime client JNDI implementation is lightweight and does not support federation of other name spaces; rather, it provides a simple hierarchical name space for client applications. In most cases, applications using JNDI do not need to interact directly with JNDI Name objects and simply use String representations of the names to be bound or located. If your application needs to directly interact with JNDI CompoundName objects, note that due to the lightweight implementation, only a restricted set of JNDI syntax properties is supported for use when creating a CompoundName object. In order to ensure that the correct JNDI syntax properties are used, use the provided NameParser implementation from the Lotus Expeditor Client JNDI provider when a CompoundName object is needed.

The Lotus Expeditor Client JNDI provider can be directly accessed through the provider's InitialContextFactory class as shown here:
try {
	Hashtable env = new Hashtable();
	env.put(Context.INITIAL_CONTEXT_FACTORY,
     "com.ibm.pvc.jndi.provider.java.InitialContextFactory");
	InitialContext context = new InitialContext(env);
			
} catch (NamingException e) {
	e.printStackTrace();
}

This JNDI provider is also registered as the default JNDI provider for the Lotus Expeditor Client platform so that even if no provider is specified it still uses the InitialContextFactory to generate the InitialContext object.

The Lotus Expeditor Client JNDI provider does not persist objects or their state information across platform restarts, so the platform administrator is responsible for binding the objects each time the platform starts and configuring those objects as needed before binding them into the JNDI registry. While the application itself could programmatically register the objects that it needs each time the platform starts, the Lotus Expeditor Client provides another declarative model for JNDI bindings.

Objects that need to be bound into JNDI can be declared using Eclipse extension points, to be described in detail shortly, so that when a lookup request is made for a specific object using its JNDI name the JNDI provider locates the declarative definition, creates the object, and returns it to the client application on-demand. This “lazy” creation of objects provides for faster platform startup and memory allocation based on actual need, rather than expected need.

This capability is based on two characteristics of the bundles and plug-ins:
  1. A plugin.xml must exist and must provide an entry for the com.ibm.pvc.jndi.provider.java.binding extension point
  2. If the bundle/plug-in has a Manifest.mf file, it must contain the Eclipse-LazyStart: true entry.

The Lotus Expeditor Toolkit leverages this declarative JNDI capability to automatically generate the required plugin.xml, and Manifest.mf entries for EJB so that the Lotus Expeditor Client JNDI provider can locate their declarative information upon a lookup of their JNDI name.

Using declarative JNDI

The declarative JNDI component is based on an Eclipse extension point.

The use of the Eclipse extension point registry provides the ability for objects to dynamically be added and removed from the JNDI registry by providing extension points as a part of the plugin.xml files of installation artifacts.

This JNDI binding extension point is called com.ibm.pvc.jndi.provider.java.binding.

An example of the usage of this extension point is like the following code:
<extension 
    point = "com.ibm.pvc.jndi.provider.java.binding”>
    <binding 
   	jndi-name=”java:comp/env/jdbc/dsname”
	objectFactory-id=”com.ibm.pvc.jndi.provider.java.GenericObjectFactory”>
    </binding>
  </extension>
A required component of the com.ibm.pvc.jndi.provider.java.binding extension point is the objectFactory-id. The Lotus Expeditor Client provides the following ObjectFactory implementations:
  • GenericObjectFactory
  • WSObjectFactory
  • ManagedDSObjectFactory
  • JMSConnectionFactory
  • JMSTopicFactory
  • JMSQueueFactory
The GenericObjectFactory allows for an XML description of any Java object, including primitive constructor parameters, and the ability to call methods on the object after it has been created, but before it is bound into the JNDI registry and returned to a client application. The WSObjectFactory allows the Web Services stub creator to provide information about the stub so that it can be identified on a JNDI lookup call. The ManagedDSObjectFactory provides support for managed JDBC DataSources, while the JMSConnectionFactory, JMSTopicFactory, and JMSQueueFactory provide JMS support for the micro broker platform messaging components.
Note: No matter what specific object factory is used, all JNDI objects declaratively described are required to provide the com.ibm.pvc.jndi.provider.java.binding in their plugin.xml files. Some object factories might also provide another extension point that needs to be implemented, such as the GenericObjectFactory.

The ManagedDSObjectFactory provides an Eclipse extension point (described using a schema definition file) that allows for the description of managed Java JDBC DataSource objects to bound into JNDI on a client JNDI lookup. The ManagedDSObjectFactory is responsible for processing declarative definitions of the com.ibm.rcp.database.core.datasource extension point and creating the JDBC DataSource object to be managed. For more information on the usage of this objectFactory, see Defining managed data sources, the schema definition for the com.ibm.rcp.database.core.datasource extension point, and the Database Lifecycle Management section in Developing Applications for Lotus Expeditor.

The JMSConnectionFactory, JMSTopicFactory, and JMSQueueFactory object factories provide Eclipse extension points (described using a schema definition file) that allow for the description of Java JMS objects to bound into JNDI upon a client JNDI lookup. These objectFactories are responsible for processing declarative definitions of the com.ibm.msg.client.jmsconnectionfactory, com.ibm.msg.client.jmstopic and com.ibm.msg.client.jmsqueue extension points and creating the JMS objects to support enterprise messaging in IBM Lotus Expeditor.

GenericObjectFactory

This factory provides an Eclipse extension point (described using a schema definition file) that allows for the description of Java objects to bound into JNDI upon a client JNDI lookup.

An example of the use of the new extension point to instantiate a DB2 Everyplace DataSource object is as follows:
<extension	point="com.ibm.pvc.jndi.provider.java.genericobject">
		<object 
		  jndi-name="java:comp/env/jdbc/dsname"
	        class="com.ibm.db2e.jdbc.DB2eDataSource"
	       <method name="setUrl">
		  <method-parameter
	            type="String"
		    value="jdbc:db2e:oedb">
		  </method-parameter>
	       </method>
	    </object>
   </extension>
The com.ibm.pvc.jndi.provider.java.genericobject extension point definition allows for:
  • The jndi-name of the object
  • One class name to be specified per object entry
  • A list of parameters including type (supported types listed in the text that follows) and value to be used to create the constructor call to be executed to create this object
  • A list of methods to be called against this object including parameters with type (supported types listed in the text that follows) and value to be used in the method calls
Note: The parameter values can include Java system properties that are resolved when the object is instantiated. Specify a Java system property using the syntax ${propertyname}. If the property does not exist, the property is replaced by an empty string. Special properties _workspace and _configuration have been defined and refer to the current workspace or configuration areas, based on the method calls to org.eclipse.core.runtime.Platform.getInstanceLocation() and getConfigurationLocation(). The following is an example of the use of this property replacement:
<method-parameter 
      type=String 
      value="jdbc:db2e:${_workspace}/oedb">
</method-parameter>

The jndi-name and class attributes are the only required attributes.

The list of valid types for the parameters is as follows:
  • Objects: Boolean, String, Integer, Short, Long, Float, Double
  • Primitives: boolean, int, short, long, float, double
WSObjectFactory

The WSObjectFactory is responsible for providing a pre-initialized instance of Web services client stub for Apache Axis in the IBM Lotus Expeditor runtime.

Upon a client lookup of the client stub using JNDI, the JNDI provider uses the WSObjectFactory to locate the Web service stub based on the extension definition, which in turn causes the stub to initialize and be bound into JNDI.

The IBM Lotus Expeditor Toolkit automatically generates the appropriate plugin.xml entries for the stub as a part of the development process. The stub developer or the deployer is required to enter appropriate values.

The following example shows how to register the service interface with the WSObjectFactory:
<extension point="com.ibm.pvc.jndi.provider.java.binding">
   <binding jndi-name="com.ibm.test.EchoService"
       objectFactory-id= "com.ibm.rcp.ws.objectfactory.WSObjectFactory">
   </binding>
</extension>

<extension point="com.ibm.rcp.ws.objectfactory.WSfactoryobject">
   <WSobject
       account-key="username.us.ibm.com"
       class="com.ibm.test.EchoService"
       jndi-name="com.ibm.test.EchoService">
   </WSobject>
</extension>
Where: account-key is the name of the account, class is the class name of the service interface, and jndi-name is the name client uses to look up the stub instance.

Extending declarative JNDI

The declarative JNDI solution uses the Eclipse extension point registry to provide a means to declare a list of objects that is bound in JNDI if and when a client application attempts to locate them.

Providing an extensible mechanism for this list, the declarative JNDI component uses the JNDI ObjectFactory interface as a way of abstracting the JNDI provider from the specific implementation code needed to instantiate different objects to be bound in JNDI. The javax.naming.spi.ObjectFactory interface is simple and contains only one method, getObjectInstance().

getObjectInstance() is called by the lookup() method of our JNDI provider implementation if it is unable to locate the object requested in its current registry of JNDI objects. The JNDI provider first reads the list of object factories from an Eclipse extension point. It then reads the list of descriptions of objects to be bound into JNDI. With this information, the JNDI provider determines if the name that is attempting to be located is in the list of names to be lazily bound. If it is, it instantiates the ObjectFactory based on the id provided in the extension point registry for that name and calls getObjectInstance() with a null object, the current name, and context. The returned object from this method invocation is then bound into the JNDI object registry and returned from the lookup method of the JNDI provider.

In the Lotus Expeditor runtime, Object factories are registered using the Eclipse extension point registry, which allows for any number of ObjectFactory implementations to be registered and available to the JNDI Provider.

This extension point is com.ibm.pvc.jndi.provider.java.objectfactory, and an example of the usage of this extension point would be like the following code:
<extension 
point="com.ibm.pvc.jndi.provider.java.objectfactory">
 </extension>
Life cycle management of JNDI registry

It is required that JNDI be notified when a lazily bound object is removed from the environment so that it can be sure to unbind the object from the JNDI registry. This requirement is met by registering a listener with the extension registry, which notifies JNDI when new objects are registered and also when currently registered objects are unregistered. When this notification occurs, the JNDI provider adds the new object or removes the existing object from its registry.

It is the responsibility of the JNDI provider to manage the life cycle of the binding, not of the instantiated object. The ObjectFactory implementation is responsible for managing the life cycle of the created object by registering any appropriate listeners and managing the cleanup of any associated resources if the contributing bundle artifact is de-activated. It can do so by registering its own Extension Registry listener (org.eclipse.core.runtime.IRegistryChangeListener) for the exposed extension point.

Defining managed data sources

You can declare, migrate, and populate databases that the Lotus Expeditor Client applications used by your organization access using the Database Life Cycle Management component.

The Database Life Cycle Management component allows Lotus Expeditor Client applications to interoperate with a relational database. As administrator, you can specify the required database structure (schema) and then populate the database before client access. You can also migrate the database. Database interaction is broken down into three types of tasks: create, migrate, and populate. Create tasks run first and typically contain instructions that are responsible for creating tables in a database. Migrate tasks run after the create tasks and are responsible for migrating any data that currently exists in the database. Populate tasks run last and typically contain instructions that are responsible for populating the database with new data. If one of these tasks fails, an error message is logged and the data source is not accessible.

An advantage of using the schemas is that they have multiple versions. If multiple schema versions are deployed on the system, the schemas are applied sequentially based on the version. For example, if you deploy both a 1.0 version and 2.0 version of the schema, the 1.0 schema tasks run first, followed by the 2.0 schema tasks. Because the schemas are applied sequentially, successive versions of schemas contain only the changes from the previous versions. For example, if schema version 1.0 creates table TABLE1 in the database, then schema version 2.0 does not need to create table TABLE1 because it was already created by schema version 1.0. Prior schema versions are not removed from the platform because they might need to be applied by new users on the platform.

Consider the following scenario. An application is initially deployed and uses schema version 1.0. Because this application is a new application and a new database definition, users using this application apply schema 1.0 to the database. Later, an application update is required and schema version 2.0 is deployed. Existing users apply only schema version 2.0 to the database because they have already applied version 1.0. Because version 1.0 is already deployed, the instructions in schema version 2.0 do not need to repeat version 1.0 instructions. A new user, however, applies version 1.0 first (because the database has not been created) and then version 2.0.

With the Lotus Expeditor Client, a database can be a specific instance of any type of SQL database, tabular data source, spreadsheet, or flat file that can provide access to its content using a JDBC-compliant driver.

The steps involved in defining data sources involve using the Lotus Expeditor Client Toolkit with extension point schemas. Extensions are the key mechanism that a plug-in uses to add new features to the platform. Extensions cannot be arbitrarily created. They are declared using a clear specification defined by an extension point. Each extension must conform to the specification of the extension point that it is extending Each extension point defines attributes and expected values that must be declared by an extension. This information is maintained in the platform plug-in registry. Extension point providers query these values from the registry, so it's important to ensure that your plug-in has provided the expected information.

Table 22. Database Life Cycle Management Extension points
Extension point Description
com.ibm.rcp.database.core.provider This extension point allows for the definition of new database providers. If you want to use another database besides the default Derby database of the platform, you must implement this extension. After the extension is implemented, users of the platform can access the provided database using the database provider ID.
com.ibm.rcp.database.core.schema This extension point allows for the definition of schemas. A schema is a set associated create, populate, and migrate tasks. Schema definitions do not necessarily correspond to the schema of a specific database vendor, but form the logical unit of a database that undergoes life cycle events. Each schema is versioned independently, and can contain its own set of tasks to maintain its life cycle.
com.ibm.rcp.database.core.datasource This extension point is used to declare a managed data source to the database infrastructure. A managed data source allows your company custom applications to connect a database provider with associated schemas to manage the life cycle of the data source. If declared, the data source is created and associated with a ManagedDatasourceObjectFactory. From this data source, an instantiated version of the Datasource object can be retrieved from JNDI using a context.lookup().
com.ibm.rcp.database.core.listener This extension point allows your custom applications to define listeners to hook into data sources. Listeners are useful when you want to know the status of operations being applied to their data source. For example, you might want to inform the user of some progress if extensive schema processing on a data source is about to occur.
For information about declaring extension points, refer to the Platform Plug-in Developer Guide and to Eclipse (http://help.eclipse.org/help32/index.jsp).

Choosing between datasource types

The Managed Datasource components provide a default managed datasource definition (JNDI name jdbc/DerbyDS) that can be used by all applications. If you want to use the Managed Data Source schema extensions with the default datasource, then you need to define a virtual datasource whose parentDatasource is the default datasource.

Even if you choose not to use schemas with the default datasource, you might still want to define a virtual datasource so that your application has a consistent, unique name to use to access the managed datasource. If you later choose to use a different database than the default, you can still use the same data source name to access the database, but have the virtual datasource refer to a different parent data source.

The default managed datasource provides for an encrypted database stored within the workspace directory. Multiple applications could share the single instance of the database, by defining schemas within the database to provide unique table references. If the configuration of the default datasource is not suitable, then you need to define a new datasource using the extension. Virtual datasources do not allow you to change the database configuration, such as encryption or location.

One of the main values of using the Managed Datasource is the definitions of the schemas that can be associated with the virtual or actual datasource definitions. If you choose not to use the schema capability, you can still use the Managed Datasource and create your own code to perform definition, migration, and population tasks.

Iterative development

If you are using managed data sources with schemas, to iteratively update the database, it is recommended that you provide updates in the form of incremented schema versions. The database management life cycle framework updates and migrates your schema after the managed data source is accessed. As an administrator, you are expected to work with the developer that is using the managed data source to make sure that all the data required by the developer is in the managed data source. An example workflow would be this sequence:
  1. Administrator deploys a managed data source jdbc/MyDataSource with schema version 1.0.
  2. Developer uses the jdbc/MyDataSource but finds later that the managed data source needs another table and contacts the administrator.
  3. The administrator updates the schema to version 2.0 and adds a task to create a table as the developer requested.
  4. Developer uses the jdbc/MyDataSource again and finds that the managed data source contains the table.
Proper interactions between an administrator and developer ensure that the managed data sources are at a state in which developers want them.

In terms of testing, it is recommended that administrators deploy their updates to a new managed data source for testing before deploying to the original data source. This deployment ensures that when the old managed data source is updated, developers do not see any problems. It is important to interact with a developer during this testing period to ensure that the developer understands what managed data sources are used in testing and production.

Security considerations for managed data sources

Depending on the managed data source definition, the data source can use the platform keystore to store password or encryption key information. By associating a particular platform keystore alias with a data source connection attribute, such as a bootPassword for the Derby managed data source provider, the information can be securely stored within a keystore. Only after the appropriate password is used to unlock the platform keystore can the database password or encryption key information be obtained.

If the keystore alias is allowed to be created on first access with a random value, it is important to retain both the keystore and the password to the keystore to continue access to the database. If the keystore is no longer accessible, then the database might be inaccessible because the necessary keys are available only in the keystore.

The value associated with the alias needs to remain constant from the initial creation, as the managed data source component does not currently provide a mechanism to change the password or encryption key associated with a database.

If the database needs to be accessed external to the managed data source component, or outside the Lotus Expeditor runtime, and aliases to the platform keystore are used to contain the password, then applications must first access the keystore to obtain the appropriate values to supply when accessing the database.

Refer to Managing secure keystore for more information about accessing the Secure KeyStore.

Testing notes

When testing managed data sources and working with new managed data sources, you might find yourself in situations where there were errors due to a bad script or database task. Sometimes it is necessary to clear out managed data sources that you have been working with and to start from a clean slate. IBM Lotus Expeditor stores all databases in the workspace directory (mostly under the db directory unless specified otherwise). To start fresh, it is necessary to delete the directory in which the databases you are interested in reside. This deletion effectively clears the cache that the managed data source uses for its databases and schemas. After this step is completed, you effectively start with a fresh system that acts as if no managed data sources have been accessed yet. This series of steps can be useful when testing new managed data sources before deploying them. If troubles arise from testing managed data source, look at the logs for important error information.

Defining a managed data source

You can define a managed data source using the Eclipse extension points and the Lotus Expeditor Toolkit.

Follow these steps to define a managed data source:
  1. Using the Lotus Expeditor Toolkit, define a managed data source by specifying the com.ibm.rcp.database.core.datasource extension point.
    • To define a normal managed data source, use the data source element.
    • To define a managed virtual data source, use the virtualDatasource element. Virtual data sources are powerful as they let you reuse other data sources (like the default data source) but give you the ability to provide your own schemas and tasks.
  2. Define a valid JNDI binding to match the JNDI name of the data source using the com.ibm.pvc.jndi.provider.java.binding extension point.
After these steps are performed, the managed data source is defined.

Defining an encrypted managed data source

You can define an encrypted managed data source using the Eclipse extension points and the Lotus Expeditor Toolkit.

Follow these steps to define a managed data source:
  1. Using the Lotus Expeditor Toolkit, define a managed data source by specifying the com.ibm.rcp.database.core.datasource extension point.
  2. Use the existing Apache Derby database provider and specify the following connection encryption attributes:
    Table 23. Apache Derby Encryption attributes
    Encryption attribute Description
    encryptionProvider Specifies the provider for data encryption. If none is specified, the provider of the JRE is used.
    encryptionAlgorithm Specifies the algorithm for data encryption. If none is specified, the default value is DES/CBC/NoPadding.
    encryptionKeyLength Specifies the key length used to encrypt the Derby database. The Derby database implementation uses a default key length based on the selected encryption algorithm. The default key lengths used by Derby are 56 bit for DES, 168 bit for TripleDES and Desede, and 128 bit for other algorithms. Key lengths longer than the default can require the installation of unrestricted policy files for the Java runtime that permit longer keys to be generated.
    dataEncryption Specifies data encryption on disk for a new database.
    Refer to the Apache Derby documentation for more information about specifying encryption attributes.
  3. Define a valid JNDI binding to match the JNDI name of the data source using the com.ibm.pvc.jndi.provider.java.binding extension point.
The encrypted managed data source is defined.

Defining an encrypted managed data source with authentication

You can define an encrypted managed data source that uses the platform credential store for authentication.

Follow these steps to define a managed data source:
  1. Using the Lotus Expeditor Toolkit, define a managed data source by specifying the com.ibm.rcp.database.core.datasource extension point.
  2. Use the existing Apache Derby database provider and provide the following connection encryption and credential alias attributes:
    Table 24.
    Encryption attribute Description
    encryptionProvider Specifies the provider for data encryption. If none is specified, the provider of the JRE is used.
    encryptionAlgorithm Specifies the algorithm for data encryption. If none is specified, the default value is DES/CBC/NoPadding.
    dataEncryption Specifies data encryption on disk for a new database.
    credential Specifies the credential alias used by the managed data source to boot the database.
    Refer to the Apache Derby documentation for more information about specifying encryption attributes.
  3. Define a valid JNDI binding to match the JNDI name of the data source using the com.ibm.pvc.jndi.provider.java.binding extension point.
The encrypted managed data source is defined.

Defining a database

The value in using the Managed Datasource capability is that the defined scripts and tasks are run automatically during the initial datasource access. This step eliminates the requirement for application code to handle tasks such as database definition, population, and migration tasks.

To use this capability of the Managed Datasource, you must define a schema and associate it with a managed datasource.

  1. Create the SQL script files, or create the classes (that implement the com.ibm.rcp.database.core.DatabaseTask) that operate on the database.
  2. Define the com.ibm.rcp.database.core.schema extension with a valid schema name and version.
  3. Add create, migrate, and populate definitions to the extension, referring to the scripts or classes created in step 1.
  4. Include a schemaReference in the target managed datasource (com.ibm.rcp.database.core.datasource) extension. If you are defining a new managed datasource, you can directly include the schema reference. If you are using the default managed datasource, you need to first define a virtual datasource on the default datasource and include the schema reference in the virtual datasource definition.

When the application code uses JNDI to look up the managed datasource, the steps associated with the schema are performed prior to the datasource being returned to the calling code.

Defining a database schema for initial population using a database task

You can define a schema for data population using a script.

To define a schema for data population using a database task:
  1. Implement the com.ibm.rcp.database.core.schema extension point using the Lotus Expeditor Toolkit with a valid schema version and database task that uses the populate action.
  2. Locate the data source you want to populate and add the proper schemaReferences.

The managed data source is then populated.

Defining a database provider

You can define a database provider.

To define a database provider, implement the com.ibm.rcp.database.core.provider extension point with a valid database provider ID and a class that implements the DatabaseProvider interface.

Migrating a managed data source to a new schema

You can migrate a managed data source to a new schema.

To migrate a managed data source to a new schema:
  1. Implement the com.ibm.rcp.database.core.schema extension point with the same schema name as the previously installed schema. The only difference is that the version number must be greater than the version number of the previously installed schema. This difference allows the database catalog to recognize that an updated schema exists and it can be applied to the data source.
  2. Implement the DatabaseTask interface to provide code that migrates the database.

Using the Network layer

The network layer is a base network management layer in Lotus Expeditor that provides a framework to applications and platform components for network invocations and network error handling.

It provides users with the capability to determine the status of the client platform as well as their connectivity to remote servers and HTTP resources including Web services. The application can choose to be notified of client status changes or to check the client platform status by using the public APIs for offline manager. The application can handle the network error by using the public APIs for Net Faults. The application can also check the real network status by using the public APIs for network status. This layer also includes the Rich Client Platform (RCP) version of HTTP URL Handler which integrates with account API and offline manager.

Adding and configuring customized handlers

As administrator, you can add handlers and configure the platform to use its customized handlers.

You must create the handler and add the handler to the platform.

See "Adding and configuring customized handlers" in Developing Applications for Lotus Expeditor for more information about creating a handler and adding the extension to a plugin.xml.

Extending the platform for client management properties management

The Client Management server working with the Enterprise Management Agent on the client can update individual properties present in Java properties style files.

This ability allows for individual property updates to be distributed to multiple clients, without having to do a wholesale file replacement, which can result in incorrect settings being propagated to clients.

Files to be managed must be able to be processed as if they are ordinary Java properties files and be read and handled by the Java java.util.Properties class. Keys that contain characters that are not typically replaced in HTTP URI handling, such as the back slash (\) or plus sign (+), are escaped using typical escape notation of using %xx where xx is the hex value of the character. When they are displayed on the client management server, the escaped formatting characters are displayed.

The platform enables four files for management by default. These files are the rcpinstall.properties and config.ini in the configuration directory and the rcplauncher.properties and plugin_customization.ini in the <installdir>/rcp directory.

To enable additional properties files to be updated, you must first register them with the platform. To register a new properties file, add a new extension to the com.ibm.rcp.props.dm.managedFile extension point. To do so, follow these steps:
  1. If you have an existing project to which you want to add this extension point, go to step 3.
  2. Create a project to contain the extension:
    1. Create a client services (or plug-in) project.
    2. If you intend to add code to this project, leave the default settings. If you do not intend to add code to this project, clear the Create Java Project option on the dialog page.
  3. Go to the Extensions page in the Plug-in Manifest Editor for this project.
  4. Click Add.
  5. Clear the option Show only extension points from the required plug-ins.
  6. Enter com.ibm.rcp.props.dm.managedFile as the Extension Point filter. Select this extension point and click Finish.
  7. Optionally, add com.ibm.rcp.props.dm as a required bundle for the project.
  8. Optionally, fill in the ID and Name fields in the Extension Point details.
  9. Select the extension that you have added, right-click, then select New > managedFile.
  10. In the extension details, complete the following details:
    1. In the file field, enter the location of the file. You can use variables in the location that are replaced during runtime execution. Refer to the extension point documentation for more information. From the extension point, you can right-click, then select Show Description to display the description.
    2. In the name field, enter a name to identify this file. This name can be the same as the file name, or you can use an alias to represent the file. This name is used during operations performed at the Client Management server.
  11. Save the file contents.
You can continue to add code to this plug-in as with any other plug-in. Deployment of this plug-in follows the standard patterns. See Packaging applications for deployment for more information.

After the feature containing this plug-in has been deployed to the client, you can then initiate job requests from a Client Management server. See Managing properties files for more information.

Adding a managed settings provider

A managed settings provider is an Eclipse plug-in that knows how to pull settings from an associated back-end management system and pass them to the managed settings framework in the appropriate format.

IBM Lotus Expeditor provides providers for settings specified by the Portal Policy Manager, for settings that are specified in XML files and for policies specified in IBM Lotus Domino (shipped with Lotus Notes 8.0). If you would like to control preference or policy settings from a different back-end system you can have a developer create a custom provider for you.

Custom providers must do the following:
  1. Extend the ManagedSettingsProvider extension point provided by the plug-in com.ibm.rcp.managedsettings. Additional information is provided in the schema of the com.ibm.rcp.managedsettings plug-in.
    For example:
    <extension point="com.ibm.rcp.managedsettings.ManagedSettingsProvider">
           <provider
                 class="com.isv.Provider"
                 weight="10"/>
        <extension>
    The class attribute points to a class that implements the interface com.ibm.rcp.managedsettings.Provider, defined in the com.ibm.rcp.managedsettings plug in.
    The weight attribute is intended to resolve conflicts between multiple providers providing the same data. This value can be overridden by the administrator. The values provided by the provider with the lower weight get priority. Two providers can unintentionally be managing the same setting group if, for example, you initially set up mail policies in an XML file but decided to move them to Portal and forgot to delete them from the XML file. The weights for known providers have the following default values, which the administrator can change:
    • com.ibm.rcp.managedsettings.provider.file = 300
    • com.ibm.rcp.managedsettings.provider.portal = 200
    • com.ibm.notes.managedsettings.provider = 100
  2. Implement the com.ibm.rcp.managedsettings.provider.Provider interface.

At the beginning of a managed settings update, the framework calls getProvidedSettingGroups() to determine which setting groups the providers currently provide data for. This step is used to identify which setting groups have been deleted since the last update.

To implement this method, you need to determine how the concept of a setting group relates to the back-end system that you are writing the provider for. A setting group is a group of related settings. It is usually the level of granularity at which settings modifications are tracked, if modifications are not tracked at the individual setting level. If the back-end system does not have the concept of a setting group, you can hard-code a single value and put all your settings in this setting group.

For example: Retrieves the names of the Setting Groups that this provider knows about.
Returns:
Collection of Strings containing the names of the Setting Groups that this provider can provide.
Throws:
ProviderException if the call failed for any reason.
public Collection getProvidedSettingGroups() throws ProviderException {

    ArrayList settingGroups = new ArrayList();

    String[]providedSettingGroups = BackEndSystem.getPolicyNames();

    ArrayList ret = new ArrayList();

    for (int i = 0; i < providedSettingGroups.length; i++){
        ret.add(providedSettingGroups[i]);

    }

    return settingGroups; 	
}
Setting groups are represented by the SettingGroup class, which is a data structure that enables applications to easily pass settings data to the Managed Settings Framework. The SettingGroup class is used to associate a set of name-value pairs, indicate their locked or unlocked state, and note the time that any of the values were last changed by the administrator. After calling getProvidedSettingGroups(), the framework calls getUpdates() and passes it a Map that specifies the setting groups and the last known modified dates of those setting groups. The method returns a list of SettingGroup objects for any of the setting groups that have changed since the last modification date. The Managed Settings Framework then stores the returned SettingGroup objects in the local store on the client. For example, if one of the entries in the map is setting group A, with a last modification date of January 1, 2006, the provider returns a SettingGroup object in the List if any of the values of the settings in setting group A have changed since January 1, 2006.

To be stored in the correct place in the Eclipse Preference store, the settings and setting groups must use the naming conventions described in Specifying settings. If you are unable to specify the settings that way due to limitations in the back-end system, this setting must be encoded in the provider instead.

If any updated setting group is missing any settings that were provided in the previous update, those settings are treated as newly unmanaged and are unlocked. For example:
public List getUpdates(Map updateMap) throws ProviderException {
    ArrayList ret = new ArrayList();
    Iterator groups = updateMap.keySet().iterator();
    while (groups.hasNext()){
        String policySet = (String)groups.next();
        Date requestChangesSince = updateMap.get(policySet);
        Map settingsChanges = BackEndSystem.getPolicyChanges (policySet, requestChangesSince);
        SettingGroup settingGroup =
            new SettingGroup(policySet, BackEndSystem.getLastChangeDate(policySet);
        Iterator settingsList = settingsChanges.entrySet().iterator();
        while (settingsList.hasNext()){
            Map.Entry setting = (Map.Entry) settingsList.next();
            settingGroup.add(setting.getKey(), setting.getValue(), true);
        }
        ret.add(settingGroup);
      }
      
      return ret;
} 

You might want to combine your implementations of getProvidedSettingGroups() and getUpdates() to require just one call to the server by fetching the information required by both in the getProvidedSettingGroups() call and then caching the update information so that it can be later returned by the getUpdates() method. The only issue with doing this is that at the time getProvidedSettingGroups() is called, you do not have access to the last modification dates provided as an argument to the getUpdates() method. You can get access to the last modification dates any time you want by calling ProviderHelper.getSettingGroupLastModDates(String providerId).

You can use the Accounts API to narrow down the list of settings and Setting Groups to ones that apply to the logged in user.

Optional: If the provider knows when it has updates, it can request that the Managed Settings Framework run an update immediately instead of waiting for the update interval to expire. The Managed Settings Framework calls Provider.addProviderUpdateListener on the provider to register for these notifications. Implement this method in order to track the listeners. When the provider knows it has updates, it calls the onRequestUpdate() method on the registered listeners and an update is run immediately.

Defining accounts for Apache Axis WebServices clients

You can programmatically create accounts for Apache Axis WebServices clients.

Refer to "Programmatically creating accounts for Apache Axis Web Services clients" in Developing Applications for Lotus Expeditor.

Defining locations

You can define new locations, using the Eclipse extension points and the Lotus Expeditor Toolkit. If there are no location contributions, Lotus Expeditor will provide two default locations called Online and Offline.

To define a new location, implement the com.ibm.rcp.locationmanager.locationActionSets extension. Make sure that you provide the preferred Online or Offline state associated with your new location by specifying the offline attribute. The user will be able to switch between locations via UI controls. In addition, you can use com.ibm.rcp.locationmanager.LocationManager public API to switch between locations programmatically.

The following is an example of a location action set. In this example, a location called Office is contributed to the platform. The preferred platform state for this location is online (note the sub-elements and the way attributes are used):
<extension
      point="com.ibm.rcp.locationmanager.locationActionSets">
      <actionSet
            automaticStartup="false"
            id="com.ibm.rcp.locationmanager.test.locations" 
            label="com.ibm.rcp.locationmanager.test.locations"
          <action
                class="com.ibm.rcp.locationmanager.test.actions.TestAction"
                id="com.ibm.rcp.locationmanager.test.office"
                label="Office"
                offline="false"
                tooltip="Switch location"/>
      </actionSet>
</extension>

Defining component wiring

Refer to the Portal information center for information about component wiring.

The Portal information center is located at http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp.

Extending the Text Analyzer

You can extend the Text Analyzer framework to provide Spell Checker, which is used to check misspelled words in a document.

Spell Checker supports 26 languages and can be used by many editors, by implementing the document interfaces. You can contribute new engines and dictionaries to the Text Analyzer framework so that applications can use customized engines and dictionaries through the framework.
Table 25. Supported dictionaries
Languages Supported dictionaries
English English (Australian)

English (Great Britain)

English(United States)

Chinese (simplified) Chinese (Simplified)
Chinese (traditional) Chinese (Traditional)
French French (French)

French (Canadian)

German German (Swiss)

German (Germany reform)

Italian Italian
Spanish Spain
Portuguese (Brazilian) Portuguese (Brazilian)
Arabic Arabic (Arabic)
Czech Czech (Czech Republic)
Danish Danish (Denmark)
Dutch Dutch (Holland)
Finnish Finnish (Finland)
Greek Greek (Greece)
Hebrew Hebrew (Israel)
Hungarian Hungarian
Norwegian Norwegian (Bokmal)

Norwegian (Nynorsk)

Polish Polish
Portuguese Portuguese (Portuguese)
Russian Russian (Russia)
Swedish Swedish (Sweden)
Turkish Turkish (Turkey)
Catalan Catalan (Catalan)

Contributing a custom dictionary

Use the com.ibm.rcp.textanalyzer.Dictionaries extension point for applications to contribute new dictionaries.

A plug-in that needs to contribute a dictionary into the framework could define the extension, similar to the following:
<plugin>
 <extension
   point="com.ibm.rcp.textanalyzer.Dictionaries">
   <dictionary
    description="English medical dictionary"
    dict_name="en_US_medical.dic"
    engine="jFrost"
    filePath="./dictionaries/en_US_medical.dic"
    language="en-US"
    locale="en-US"
    provider="IBM"
    version_info="1.0.0"
    type="spell"/>
  </extension>
</plugin>
In this example, the plug-in contributes a medical dictionary in English to the existing IBM jFrost engine, and the dictionary file position is in the dictionaries folder of that plug-in. For more information, refer to "Contributing custom dictionaries" in Developing Applications for Lotus Expeditor.

Contributing a new engine

Use the com.ibm.rcp.textanalyzer.Engines extension point for applications to contribute new engines.

A plug-in that needs to contribute a spell checking engine to the framework can define the extension and implement the interface com.ibm.rcp.textanalyzer.spellchecker.SpellCheckerEngine. For more information, refer to "User dictionary manager" in Developing Applications for Lotus Expeditor.

Deploying the IBM Lotus Expeditor micro broker

There is only a single micro broker instance per platform. The micro broker instance is created programmatically by using the administration APIs.

The micro broker instance once created will be started automatically by the com.ibm.micro bundle. Since the com.ibm.micro bundle will be lazy started as a result of calling the administrative APIs on the micro broker, the only bundle that needs to be added to the platform or application lifecycle is your application bundle that checks for existence of or creates a micro broker instance. See Managing life cycle for more information.

To begin initial prototyping using the micro broker, a IBM Lotus Expeditor micro broker Getting Started feature is provided on the updates\platform update site. This feature is not installed by default and must be installed using one of the provisioning mechanisms. To use this feature, either add the com.ibm.micro.gettingstarted plug-in to the platform life cycle to perform the initial configuration of the micro broker instance, or use the platform console to manually start this plug-in. The micro broker instance is named FirstBroker. This plug-in is for evaluation and initial prototyping use and provides a very basic configuration. You may need to create your own broker instance specific to your application requirements, configuring capabilities such as connections and connection types, persistence, connection factories and more.

For more information, refer to "Configuring and administering micro broker components" in the micro broker documentation for more details.

Configuring widgets and creating the catalog

Administrators plan for, install, and configure the Widgets feature for their end users.

Lotus Expeditor administrators can use an IBM Lotus Notes application as a widget catalog. In this case, the administrator is also responsible for creating the catalog application and assigning widgets access using Lotus Domino server catalog applications ACLs. Administrators configure users based on preference as well as widget catalog categories. They also control which users are designated as power users and end users. A typical power user is able to create widgets in the catalog while end user typically are not allowed to do such an action.

Hiding and showing all widgets in the My Widgets sidebar panel

A user can right click on one or more widgets and select the Hide action to hide the widgets in the My Widgets sidebar panel. The widget actions are still available to use.

A user can right click on one or more widgets and select the Hide action to hide the widgets in the My Widgets sidebar panel. The widget actions are still available to use. The user can then go to the Show drop-down menu on the My Widgets sidebar panel and select Show All to display all the hidden widgets.

Configuring a Features and Plug-ins provisioning widget

You can create a widget that will provisioning features and plug-ins.

You can create a widget that will provisioning features and plug-ins.

You can also get started by clicking 'Configure a Component from' from the My Widgets options menu.

Configuring a Features and Plugins deployment widget

You can use the Features and Plugins option on the Getting Started with Widgets wizard to create a new widget for deploying new and updated client plug-ins to users.

You can use the Features and Plugins option on the Getting Started with Widgets wizard to create a new widget for deploying new and updated client plug-ins to users.

This option guides you through the process of creating a feature and plug-in deployment widget. The wizard guides you through the widget definition process, prompting for the updatesite in which the target plug-in resides. After specifying the plug-in, entering the name, image URL, and description for the widget, the wizard creates the widget's install manifest content, saves the new widget, and installs the specified plug-in. You can then export and publish the widget.

This procedure is designed for application developers, power users, and administrators.

Note: This process assumes that you already have created and signed the feature's updatesite contents and that you have a properly configured site.xml file.
Note: You cannot create a provisioning widget using the "Configure a widget from the current context" wizard.
  1. Click the Getting Started with Widgets toolbar button to start the wizard.
  2. Click Features and Plugins and then click Next.
  3. In the Enter the URL ... field, specify the existing updatesite URL, specifically the path to the site.xml file in the target updatesite, and click Load. The URL can be of the http:// or https://, or file:// format as follows:
    http:// or https:// – Use http or secure https protocol to specify the path to the updatesite in which the feature's updatesite resides. 
    http://server_name/directory_path/updatesite/site.xml 
    
    jar:http://server_name/directory_path/updatesite.zip!/ 
    
    file:// – Use a simple file path protocol if, for example, the updatesite is resident on disk. 
    file:///C:\directory_path\updatesite\site.xml 
    
    jar:file:///c:\directory_path\updatesite.zip!/ 

    All the available features and plug-ins in the updatesite are displayed and available for selection. To simplify deployment for users, be sure that you have signed the features and plug-ins using a trusted certificate authority; this signing prevents users from being prompted to respond to trust screens during provisioning.

  4. Select one or more features for the widget to deploy and click Next or Finish.

    Click Finish to complete the widget by accepting all defaults.

    If you select only one feature and click Next, the feature name appears in the Widget Name field and the feature description appears in the Description field. Features do not require a description, so this field can be blank.

    If you select more than one feature, "Provisioning Widget" appears in the Widget name field and "This widget will provision the following features: feature_ids" appears in the Description field.

  5. Confirm or modify the Widget name field entry. This field is required.
  6. Optionally, specify an Image URL to use as the widget's thumbnail in the My Widgets sidebar panel.
  7. Confirm or modify the Description field entry to appear in the widget's catalog document (if published) and click Next.
  8. Preview and optionally edit the install manifest snippet (code block) and click Next.
  9. Click Finish and, as prompted, be sure to test the widget before sharing it with others.

After creating the widget, a thumbnail is added to the My Widgets sidebar panel representing the provisioning widget you just created. The features are then installed and you are prompted to restart your client.

Configuring a new composite application widget

You can create a widget from an open composite application.

You can create a widget from n open composite application. When you open the widget, it opens the application.

  1. Open the desired composite application.
  2. Click the Configure a Widget from Current Context toolbar button.
  3. Enter in a name for the widget.
  4. Click Finish.

Opening a widget

You can open a widget, for example, a local weather display, using one of several options.

You can open a widget, for example, a local weather display, using one of several options.

Right-click the widget in the My Widgets sidebar panel.

Click Open in and choose one of the following options:

  • Tab -- opens a tab
  • Sidebar panel -- opens a new sidebar panel
  • New window -- opens a new, moveable, sidebar-sized window
  • Floating window -- opens a new, smaller, moveable window

You can also double-click a widget in the My Widgets sidebar panel to open the widget in a new window.

To use the keyboard to open a widget and execute its default behavior, select the widget and press the space bar or Enter key.

Installing the Widgets feature

To install the Widgets feature, users need to choose a specific set of features from the update site in the Lotus Expeditor kit.

Expeditor Widgets Feature
com.ibm.rcp.toolbox.xpd.feature (main widgets feature)
Threading Violation Monitor
com.ibm.rcp.threading.monitor.feature (a widgets dependency)
Feed Reader core feature
com.ibm.rcp.feedreader.feature (a widgets dependency)
com.ibm.rcp.feeds.parser.feature
com.ibm.rcp.feeds.parser.feature (a widgets dependency)
Embedded Browser Component
com.ibm.rcp.ui.browser.feature (a widgets dependency)
Widgets Composite Applications Provider Feature
com.ibm.rcp.toolbox.ca.provider.feature (additional widget provider)

If users choose to install CAE in the install wizard, the widgets features and its dependencies are also installed.

Creating the widget catalog

Administrators can create a widgets catalog on a Lotus Domino server, using a catalog template (an IBM Lotus Notes application) supplied on the server.

  1. Obtain the Widget Catalog template (TOOLBOX.NTF). The template is installed with the IBM Lotus Domino server.
  2. Create the catalog, for example named TOOLBOX.NSF, using the supplied TOOLBOX.NTF template.
  3. Assign ACLs to control access rights to the catalog application for administrators, power users, and end users.

    Administrators and power users need read and write access to the catalog.

    Administrators must be granted the [Admins] role in the catalog Access Control List (ACL). Administrators also need one of the following access rights to the catalog:

    • Manager
    • Designer
    • Editor

    End users may not be set up to browse and access the catalog directly but rather to obtain widget actions automatically by way of their membership in specific widget categories. End users, if they are not allowed to create and configure widgets, need Reader access to the catalog; otherwise it is recommended that end users be granted Author access to the catalog.

  4. Once you have created the catalog, optionally create an initial set of categories for the catalog. here are two types of predefined categories in the catalog: administrator categories and categories. Both of these categories are defined in the Administration/Keyword view. Administrator categories are named "ADMIN-Categories", while the other categories keyword is named "Categories".
    Note: You can assign preferences to designate user access to the catalog.
  5. Enable the "Toolbox Sweeper" agent, which is a scheduled agent set to run against new and modified documents. This agent ensures that Widget documents are properly created and populated; if a problem is found the offending document is removed from the user views, is placed in the Administration/Document Queue, and an e-mail is sent to the document author informing him of the problem. Enable the Sweeper agent by selecting View/Agents, highlighting the Toolbox Sweeper agent, and then clicking "Enable". You will be prompted to choose which server to run the agent on; choose the server where you have deployed the catalog.

Catalog options and access

The widgets catalog is an IBM Lotus Domino server-based application that contains all centrally managed widgets and their underlying XML extension definitions. The catalog is based on the Lotus Notes server-supplied Widget Catalog template (TOOLBOX.NTF) and its access is controlled by PLUGIN_CUSTOMIZATION.INI preferences.

Power users can configure new widgets and publish them in the catalog for user access. Users obtain the latest widgets from the catalog on a scheduled basis. Depending on how users are configured they can browse the catalog for new widgets and update the widgets in their local catalog replica on demand.

Catalog documents

Each widget is represented in the catalog as a Notes document containing the following elements.

Widget graphic for display in the catalog document
Note: You can use the default graphic or specify another for display in the catalog document. However the graphic you specify for the catalog document has no effect on the widget thumbnail used in the My Widgets sidebar panel. The widget thumbnail is specified in the .XML file attachment using the "imageUrl" variable.
Title, Description, and Detail
Use the default widget name or specify a different catalog document title. Use the Description and Details fields to describe the widget.
Category
Control user access to the widget based on widget category grouping such as team name or job. This is how you specify which users have access to which widgets. Users whose "category" preference allows them access to widgets of a specific category name will be provisioned with those widgets automatically.
Type
Optionally specify the widget type(s) -- for example component or feature or plug-in.
XML extension attachment
This contains the widget XML itself, which informs the client what to do when the widget is provisioned to the user, for example deploy a plug-in from a named update site or install a gadget.
Catalog views
The catalog is supplied with the following views
  • All Widgets
  • By Author
  • By Category
Catalog access rights
The administrator can control a variety of Widgets catalog access settings using settings in the PLUGIN_CUSTOMIZATION.INI file. For example, an administrator can control widget deployment based on categories. Categories are created in the catalog, but are administered by way of preference settings. Specific widgets can be deployed to specific users based on the category in which a given widget resides and the categories for which a given user is assigned.
Catalog action buttons
The catalog contains the following action buttons:
Open
This allows you to open and view the selected catalog document for the purposes of viewing and optionally adding it to the My Widgets sidebar panel. Provided you have edit rights to that document, you can also open it for edit.
Add Widget to Catalog
Use this to add a widget to the catalog. This action opens a dialog in which you can attach your .XML file and add a title, category name (optional), type designation, short description, and detailed description.

Eclipse preferences for Widgets access control

Access to Widgets functionality and the widgets catalog is controlled by settings in the PLUGIN_CUSTOMIZATION.INI file.

Note that if a setting is changed using the Widgets preferences panel, that setting takes precedence for the duration of the active session.

Note: The default PLUGIN_CUSTOMIZATION.INI file is provided in the Expeditor install media kit in the deploy subdirectory. The file path of the installed PLUGIN_CUSTOMIZATION.INI file is <install_dir>\rcp\ plugin_customization.ini.
Catalog server URL
This setting specifies the catalog server from which to provision widgets.
com.ibm.rcp.toolbox.admin/webCatalogUrl
Example:
com.ibm.rcp.toolbox.admin/webCatalogUrl=http://myserver.mycompany.com/toolbox.nsf
Note: Using this setting does not prevent the user from changing the catalog server name in the Widgets preferences panel. This corresponds to the "Catalog server" preference on the Widgets preferences panel.
The preference default is blank.
Update interval
This setting specifies the amount of time, in hours, that the client waits to get widget updates from the catalog.

The preference default is 24 hours.

Example:

com.ibm.rcp.toolbox.admin/webCatalogUpdateIterval=24
Widget categories to install
This setting enables you to list the widget categories from which to provision widgets.
com.ibm.rcp.toolbox.admin/catalogCategoriesToInstall
Example:
com.ibm.rcp.toolbox.admin/catalogCategoriesToInstall=<ABXID>,<Team1>
Note: Using this setting does not prevent the user from adding or removing categories in the Widgets preferences panel. This corresponds to the "Categories to install" preference on the Widgets preferences panel.
The preference default is blank, meaning no categories are selected in the Widgets preferences panel.
Show Widget Toolbar and the My Widgets Sidebar panel
This setting specifies whether the "Show Widget Toolbar and the My Widgets Sidebar Panel" preference is enabled (checked) by default. The preference default is true, such that the option is not checked on the Widgets preferences panel. If the user enables "Show Widget Toolbar and the My Widgets Sidebar panel" on the Widgets preferences panel, she can see the three Widgets toolbar buttons, the Tools - Widgets menu options, and the My Widgets sidebar panel.
com.ibm.rcp.toolbox.admin/toolboxvisibleChild
Options are =true and =false. The preference default is true.
com.ibm.rcp.toolbox.admin/toolboxvisibleChild=true
Restrict widget creation and edit to specific types (provider IDs)
Restrict creation and edit of widgets to certain types (referred to as provider IDs).

The Widgets feature includes an extension point for widget providers. The supplied providers are Feeds, Web page or service, Google Gadget, Composite Application, and Feature and Plug-in Provisioning.

If the preferences are set to restrict installation of a certain widget type, then the preferences should also restrict creation of the same widget type.

If this setting is disabled, the user can create or edit widgets with no restriction on type.

If this setting is enabled, the user can only create or edit widgets of a certain type. The administrator can then specify which widget types (provider IDs) are available using the setting below.

com.ibm.rcp.toolbox.admin/createTool

Options are =true and =false. The preference default is false.

If enabled you can then specify which widget types (provider IDs) are available for creation or edit using the setting below.

com.ibm.rcp.toolbox.admin/createToolProviderIDs

Specify the widget types available for creation and edit. Use a comma to separate types in the list. The available widget type/Provider ID entries are as below and correlate to the Web page or service, Feeds, Google Gadget, Composite Applicaiton, and Feature and Plug-in Provisioning widget types.

com.ibm.rcp.toolbox.web.provider.WebServicesPalleteProvider 
com.ibm.rcp.toolbox.feeds.FeedPalleteProvider 
com.ibm.rcp.toolbox.google.provider.internal.GooglePalleteProvider 
om.ibm.rcp.toolbox.ca.provider.internal.CAActionPalleteProvider  
com.ibm.rcp.toolbox.prov.provider.ToolboxProvisioning c 

The default is as below:

com.ibm.rcp.toolbox.google.provider.internal.GooglePalleteProvider,  com.ibm.rcp.toolbox.web.provider.WebServicesPalleteProvider,  com.ibm.rcp.toolbox.feeds.FeedPalleteProvider, 
com.ibm.rcp.toolbox.ca.provider.internal.CAActionPalleteProvider  com.ibm.rcp.toolbox.prov.provider.ToolboxProvisioning  com.ibm.rcp.toolbox.ca.provider.internal.CAActionPalleteProvider
com.ibm.rcp.toolbox.prov.provider.ToolboxProvisioning

For example, if the setting is as below, the user could only create Google Gadget widget types:

com.ibm.rcp.toolbox.google.provider.internal.GooglePalleteProvider
Restrict the installation of widgets to specific widget types (provider IDs)
Restrict installation and update of widgets to specific types (referred to as provider IDs):
com.ibm.rcp.toolbox.admin/toolboxrestrictProviderIDs
Options are =true and =false. The preference default is false.
If the preferences are set to restrict installation of a certain widget type, then the preferences should also restrict creation of the same widget type.
If a certain widget type was created and the preferences are changed to restrict the installation that certain widget type, that widget is removed.
If enabled, the administrator can then specify the widget types (provider IDs) available for install and update using the setting below, which corresponds to the Enable provider IDs for installation/execution policy. Use a comma to separate types in the list.
com.ibm.rcp.toolbox.admin/toolboxinstallProviderIDs
The available widget type/Provider ID entries are as below and correlate to the Web page or service, Feeds, Google Gadget, Composite Appication, and Feature and Plug-in Provisioning widget types.

A fourth type, prov.provider.ToolboxProvisioning, which allows a widget to be used to deploy a client plug-in, is also available.

com.ibm.rcp.toolbox.web.provider.WebServicesPalleteProvider
com.ibm.rcp.toolbox.feeds.FeedPalleteProvider
Com.ibm.rcp.toolbox.google.provider.internal.GooglePalleteProvider
com.ibm.rcp.toolbox.prov.provider.ToolboxProvisioning
The default is as below:
com.ibm.rcp.toolbox.google.provider.internal.GooglePalleteProvider,
com.ibm.rcp.toolbox.web.provider.WebServicesPalleteProvider,
com.ibm.rcp.toolbox.feeds.FeedPalleteProvider,
com.ibm.rcp.toolbox.prov.provider.ToolboxProvisioning
For example, if the setting is as below, the user could only install or provision Google Gadget widget types:
com.ibm.rcp.toolbox.google.provider.internal.GooglePalleteProvider
Enable the ability to install widgets from non-catalog means
Specify whether a user can install widgets using an XML extension file obtained from the user's file system. If enabled, the user can use drag and drop to install widgets from the user's file system or an import action from the user's file system.
com.ibm.rcp.toolbox.admin/toolboxinstallFromOther
Options are =true and =false. The preference default is true.
Enable the ability to install widgets from the catalog and to browse the catalog from the My Widgets sidebar panel
Specify whether a user can browse the configured catalog and select widgets to install to the My Widgets sidebar panel or sidebar.

If enabled, the user can select a widget from the catalog and drag and drop the widget's XML extension attachment to their My Widgets sidebar panel. They can also select additional categories to be provisioned with using their Widgets preferences panel.

com.ibm.rcp.toolbox.admin/toolboxinstallFromCatalog
Options are =true and =false. The preference default is true.
Restrict installation to specific extension point types
Restrict installation of widgets that contain certain extension points.
com.ibm.rcp.toolbox.admin/toolboxspecifyExtPtIDs
Options are =true and =false. The preference default is false.
Note: Extension points are an Eclipse feature. They define new function points for the platform that other plug-ins can plug into. Eclipse provides many extension points with the core platform. The Widgets feature also provides some extension points. For example:
  • The Eclipse platform provides the following identifiers, and many others:
    org.eclipse.ui.popupMenus, org.eclipse.ui.viewActions, org.eclipse.ui.views identifiers
  • Expeditor provide the following identifiers, and many others:
    com.ibm.rcp.search.engines.searchEngines, 
    com.ibm.rcp.search.ui.searchBarSets, com.ibm.rcp.content.contentTypes, 
    com.ibm.rcp.annotation.regex.regexTypes
If "toolboxspecifyExtPtIDs" is set to true, the administrator can then specify which extension point IDs are allowed using an additional entry in the INI file.
com.ibm.rcp.toolbox.admin/toolboxdynamicExtPtIDs
By default, this setting is disabled. The default is as below:
com.ibm.rcp.toolbox.admin/toolboxdynamicExtPtIDs= 
org.eclipse.ui.popupMenus,
com.ibm.rcp.content.contentTypes,
com.ibm.rcp.annotation.regex.regexTypes,
com.ibm.rcp.ui.shelfViews,
org.eclipse.ui.views,
org.eclipse.ui.viewActions,
com.ibm.rcp.search.engines.searchEngines,
com.ibm.rcp.search.ui.searchBarSets
For example, the following settings specify that widgets will not be able to contribute to the sidebar.
com.ibm.rcp.toolbox.admin/specifyExtPtIDs=com.ibm.rcp.ui.shelfViews
Controlling the default double-click behavior of widgets in the My Widgets sidebar panel

This preference enables the control of what action is taken when you double click on a widget (which does not already define a custom double click action) in the My Widgets sidebar panel.

This preference enables the control of what action is taken when you double click on a widget (which does not already define a custom double click action) in the My Widgets sidebar panel.

com.ibm.rcp.toolbox/doubleClickAction

Options are:

  • sideBar (opens the widget in a sidebar panel)
  • newWindow (opend the widget in a new window)
  • float (opend the widget in a floating window)
  • tab (opend the widget in a tab)

The preference default is sideBar.

For example, the following settings specify that widgets will not be able to contribute to the sidebar.
com.ibm.rcp.toolbox.admin/specifyExtPtIDs=com.ibm.rcp.ui.shelfViews 
Hiding widgets in the My Widgets sidebar panel

You can specify whether a user can hide widgets in the My Widgets sidebar panel.

Specify whether a user can hide widgets in the My Widgets sidebar panel. If enabled, the user can right click on a widget in the My Widgets sidebar panel and choose 'Hide'. After hiding a widget, the 'Show All' view action will become enabled.

com.ibm.rcp.toolbox/allowUserShowHideWidgets

Options are =true and =false. The preference default is true.

Creating and publishing widgets

Widgets enables you to create and edit Web-based XML extensions (widgets) and make those widgets available to users from a central widget catalog.

Wizards are available to assist you in configuring new widgets.

Setting Widgets preferences

Use the Widgets preferences panel to specify the name of the catalog server, update interval, and widget catalog categories to install. Also use the Widgets preferences panel to toggle display of the Widgets toolbar buttons, the Tools - Widgets menu options, and the My Widgets sidebar panel. The catalog is a central repository for widgets that you can add to, update, and retrieve from or be provisioned with. These settings can be initially set using Eclipse preferences (PLUGIN_CUSTOMIZATION.INI file).

  1. Click File (on Mac, Lotus Expeditor -) > Preferences > Widgets. Alternatively, you can click Catalog > Preferences from the My Widgets options menu.
  2. Use the Show Widget Toolbar and the My Widgets Sidebar Panel option to show or hide the Widgets toolbar buttons, the Tools > Widgets menu options, and the My Widgets sidebar panel.
  3. Specify an HTTP or HTTPS URL to the catalog server on which the widget catalog resides. The Edit account button opens the Accounts preference page, so you can set up an account for the URL.
  4. In the Update interval field, specify how often you want to update widgets installed from the catalog.
  5. Select the widget categories to install from the list of available categories. Categories typically equate to a user grouping such as a project team, job type, or function. When you click OK, widgets in the selected categories are updated in your local widget catalog and My Widgets sidebar panel.
Browsing the catalog

You can browse the catalog to optionally add widgets to your My Widgets sidebar panel.

  1. Click Catalog > Browse in the My Widgets options menu, or you can click the Browse button on the My Widgets sidebar panel's toolbar. These actions open the widget catalog. You can browse this catalog by preset views.
  2. Locate a widget that you want to add to your My Widgets sidebar panel.
  3. To add an individual widget from the catalog, open the widget document and drag the link in the Attachments section to your My Widgets sidebar panel.
    • To add a category of widgets to your My Widgets sidebar panel, click Catalog > Preferences from your My Widgets options menu, check the categories that you want to install, click Apply and then click OK.
To immediately update the widgets in your My Widgets sidebar panel, click Catalog > Update Widgets from the My Widgets options menu. Otherwise, they will be updated automatically on a scheduled basis.
Creating a new widget category

You can create category names to group widgets relative to a user distinction, such as a project team or job type, when you publish the widget to the catalog.

You can add one or more category names to a widget when you publish to the catalog. You can also open an existing widget in the catalog and add or remove category names, as below.
  1. Use a Lotus Notes or Lotus Domino Administrator client to open the widget catalog.
  2. Double-click to open one of the widgets.
  3. Double-click the Category field to open it for edit.
  4. Type the new category name in the New keyword field and click OK. For widgets that belong to multiple categories, use a comma to separate the category names.
The new category name is added to the widget and is also now available for new or existing widgets.
Updating widgets from the catalog

You can update widgets from the catalog so that any new, updated, or deleted widgets in the catalog are reflected in your local client.

Update is based on the Catalog server URL and Categories to install settings specified on the Widgets preferences panel. Widgets are installed or updated if you are assigned the widget's specified category in the PLUGIN_CUSTOMIZATION.INI file preference or have specified that category on your Widgets preference panel. Widgets are also updated if you installed them using drag and drop from the configured catalog.
To force an update, click Catalog > Update Widgets from the My Widgets options menu. While you can manually check for updates using this menu option, the update interval is used to automatically check for updates and refresh your widgets with updates from the catalog. If a category that a user is subscribed to is removed from the catalog, your widgets from that category are removed the next time catalog update occurs.
Configuring widgets using the wizards

Wizards are available to power users for all widget creation tasks. Click the Getting Started with Widgets toolbar button to begin.

When you first open the My Widgets sidebar panel, and if there are no widgets in the panel, introductory text appears in the My Widgets sidebar panel to guide you through the process of creating your first widget. Otherwise, you can begin creating widgets by clicking either the Getting Started with Widgetsor Configure a Widget from Current Context toolbar buttons.
You can configure a widget from any of the following contexts
  • Feed
  • Web page
  • Google Gadgets
  • Composite applications
  • Features and plug-ins on an Update site

The general process for configuring a new widget is as follows:

  1. Start the widget configuration wizard. Click Getting Started with Widgets and choose one of the available widget contexts to start the correct wizard. Once you have obtained the context, the widget configuration wizard steps you through the process.
  2. Test the new widget, as prompted by the wizard, to ensure that it is correct and that you are ready to share it with others.
  3. Share the widget with others. You can make widgets available to others in several ways. As a reminder, end users may not have the authority to create or edit widgets but they can use the widget actions that you make available to them. Based on preference, they may also be restricted as to which types of widgets they can use.

    To share the widget with others you can export the widget by selecting the widget and choosing Export... in the My Widgets' options menu. After exporting the widget, you can add it to the catalog using your Notes or Administrator client.

Configuring a new Web page widget

You can configure a new widget that performs an action using a single form on a specific Web page, or you can create a widget that can perform one or more actions based on an overall Web page. You can optionally require that the user authenticate before using the Web page action.

  1. Open the target Web page on which you want to base the new widget and with which you want the action to take place. For example, to search the IBM Lotus Notes and IBM Lotus Domino Forum, go to the Notes/Domino forum page using the http://www.ibm.com/developerworks/lotus/community link.
  2. Choose one of the following options and click Next to open the Configure a Component dialog.
    This web page
    You can build a widget from the target Web page. Choose this option if you are displaying a Web page that contains the results of a form submission;, for example "http://www.lotus.com/ldd/nd8forum.nsf/Search?SearchView&Query=widget".
    From a form on this web page
    You can build a widget that will submit data to a single form on the target Web page. For example, you can choose the search form on the http://www.lotus.com/ldd/nd8forum.nsf Notes/Domino forum page. If there are feeds available from the current Web page, the wizard will provide you with additional options for creating a Feeds-based widget.
  3. Optionally specify that authentication is required and click Next. For information about the Authentication Required option, see Requiring authentication when creating a Web-based widget in this guide.
  4. For this example, click From a form on this web page" and click Next.
  5. Select a form on the page as prompted in the wizard. For example, click Form 1 on the Select a form on this page wizard panel and the corresponding form; in this case the Search this Forum field highlights in green to indicate it is the corresponding form field. As you give focus to different forms on the page, the form with focus is highlighted in green and the corresponding form number is also highlighted.
  6. Click Next to open the Configure a Component dialog.
  7. Specify a short, descriptive widget name or accept the default.
  8. In the Widget settings area, specify an ID and display name fields and if a default value is required. Depending on your source, there can be several widget setting IDs. For example, search_by, url, where, and field-keywords are common Ids.
    ID
    This is the field ID name obtained from the source Web site form. When you check items in the ID column, default values may appear in some or all of the remaining widget fields in that row.
    Display name
    Use an optional name to describe the ID.
    Required
    Specify whether this field must be used. For example, a search string should be required, but the number of results returned by the search may not be.
    Default value
    Optionally specify a default value to use with this component. This can equate to an ENUM value from a list of enumerated values allowed for this field in the given web form. For example, this allows you to preset default values such as your home airport if you are booking a flight.
    Edit
    Click edit to add additional default values.
  9. Specify what you want to do with the component now; the options are as below.
    Display as a sidebar panel
    This adds the component as its own sidebar panel, not as a widget in the My Widgets sidebar panel. If you choose this option, the Test and Publish panel appears describing what you should do next. Read and then click Finish to exit the wizard and add the widget to your sidebar.
    Just configure a component for now
    This adds the component to the My Widgets sidebar panel. If you choose this option, the Test and Publish panel appears describing what you should do next. Read and then click Finish to exit the wizard and add the widget to your sidebar.
  10. Click Next and Finish to add the widget and close the wizard.
Requiring authentication when creating a Web-based widget

When you create a Web-based widget, you can optionally specify that users authenticate in order to access the Web site that will be used by that widget. To require authentication, you must specify an existing account name, or create a new account, as you create the widget. This account will be used, or created if it does not already exist, on the user's client. Anyone who uses the widget must use their own existing or new account information.

When users act on the widget for the first time they will either be prompted for a user name and password or be asked to give the widget permission to use the user name and password in an existing account. This step will create a new account if it does not already exist. If you enable the Authentication Required option on the Create a Widget from this Web Site dialog, wizard instructions guide you through the authentication process as below.
  1. Check Authentication Required on the Create a Widget from this Web Site dialog and click Next.
  2. Navigate to the Web page that contains the authentication form, for example, a Google sign-in form prompting for a user name and password.
  3. Select the correct form from the Web page's form list and click Next to open the Account Management dialog. Colored highlighting helps you to determine which form on the Web page has focus.

    The Next button is only enabled if you select a form containing a password field.

    The wizard will attempt to place the "Lotus" in the user name field and "IBM" in the password field. You may need to enter the name and password field values manually if the wizard does not choose the correct fields.

  4. The Account Management dialog allows you to either choose an existing account to use when authenticating to this site or to create a new account. Choose the account name carefully as all users who use this widget will have an account with this name created on their system, if it does not already exist. Consider using the same account name for all widgets that require the same user name and password, since multiple widgets can use the same account.
    Choose an existing account
    If you already have an account with the correct user name and password, choose the account by name. The current user name and obscured password will be displayed. If these are the correct credentials press Next. If the user name and password are out of date, or nonexistent, you can change them by canceling the wizard, clicking Preferences > Accounts and selecting Edit Account.
    Create a new account
    If you do not have an account with the correct credentials, create a new account name, user name and password now and click Next. The new account name must be unique; an error message appears if it is not.
  5. If authentication is successful, click Next to continue to the next page in the widget creation process. See the wizard-based widget creation topics for details.

    The account will be created at the end of the widget creation process when you click Finish on the final wizard screen. If authentication fails, it is likely for one of the following reasons:

    • The user name and password are incorrect. Press the Back button and enter the correct credentials.
    • JavaScript or other active code on the Web page is preventing the widget from authenticating. Consider building the widget without authentication. Many sites, such as Google, only require the user to log in once per session, giving access to all of their applications, so many non-authenticated widgets will function once the user has logged in manually.
      • You can view the accounts created for a widget by clicking File > Preferences > Accounts and double-clicking the account name. This allows you to see which widgets have permission to access a certain account. In the Advanced Properties section, there is a field called Tool IDs. Clearing this field of all text revokes the permission granted for existing widgets to use this account. If you do that, the next time a user engages any widget that uses this account, they will be asked for permission to use the account associated with the widget. Also note that editing an account allows you to modify the user name and password for that account.
Configuring a new Google Gadget widget

You can easily browse a gadget directory and find the a gadget from which to create a widget.

  1. Click the Getting Started with Widgets toolbar button to start the wizard.
  2. Click Google Gadgets and then click Next.
  3. Click Browse the Google Gadget directory, read the explanatory text, and then click Finish to open and browse the site. This opens the Google Gadget directory, which you can search to find a variety of gadgets.
  4. Navigate to the page for the gadget you want, and then click the Configure a Widget from Current Context toolbar button, click Google Gadget, and click Next.
  5. Click Google Gadget from the Configure a Component from this Web site dialog.
  6. Read the terms of service panel text and then click Next.
  7. Specify a short, descriptive component name or accept the default.
  8. In the component settings area, specify an ID and display name, if a default value is required, and optionally a default name. Depending on your source, there can be several widget setting IDs.
    ID
    This is the field ID name obtained from the source Web site form; for example, zip. When you check items in the ID column, default values may appear in some or all of the remaining widget fields in that row.
    Display name
    Use an optional name to describe the ID, such as Zip Code.
    Required
    Specify whether this field must be used. For example, a zip code might be required, but the exact address might be optional.
    Default value
    Optionally specify a default value to use with this component. This can equate to an ENUM value from a list of enumerated values allowed for this field in the given web form. For example, to display your local weather whenever you open a weather gadget, enter your zip code in this field.
    Edit
    Click edit to add additional default values.
  9. Specify what you want to do with the component now; the options are as below.
    Display as a sidebar panel
    This adds the component as its own sidebar panel, not as a widget in the My Widgets sidebar panel. If you choose this option, the Test and Publish panel appears describing what you should do next. Read and then click Finish to exit the wizard and add the widget to your sidebar.
    Just configure a component for now
    This adds the component to the My Widgets sidebar panel. If you choose this option, the Test and Publish panel appears describing what you should do next. Read and then click Finish to exit the wizard and add the widget to your sidebar.
  10. Read the Test and Publish panel and then click Finish to add the widget and close the wizard.
Google Gadget widget fields and language internationalization

When you configure a Google Gadget widget using Widgets, the default component name and property display names are localized properly such that when you run Expeditor, for example, in another locale, those names appear in the language of the active locale.

However, if you change the component name from its Google Gadget default, or if you add or change any property display names from their Google Gadget preference defaults, those names will not be localized properly when using that widget in another locale, but rather will remain in the language in which you modified them. This consideration applies specifically to the Component name and Display name fields on the Configure a Component wizard panel. If the component name or property display names are modified, those modified names will not appear localized when using the widget in a different locale.

For example, if you create a Google Gadget widget while active in the US English locale and change a default display name, when you later use that widget while active in a different locale, such as German, the changed name appears in US English, not that of the active German locale. For background information, see Google Gadgets and Internationalization.

Configuring a new Feed widget

You can configure a new widget that will search for a given feed and return the results of that search in a specified display window such as the sidebar.

  1. Click Getting Started with Widgets and choose Feeds from the list of available widget types to start the appropriate wizard. Or click Create a Widget From - A Feed in the My Widgets options menu to start the wizard.
  2. When prompted, enter the feed URL and click OK to open the Configure a Component dialog. For example, to subscribe to the Notes and Domino developerWorks® forum, enter the following value:
    http://www.lotus.com/ldd/nd8forum.nsf/forumfeedmain.rss
  3. Enter a new component name or use the default name provided.
  4. If component settings are available, specify an ID, default value, and whether the default is required.
  5. Specify what you want to do with the component now; the options are as below.
    Display as a sidebar panel
    This adds the component as its own sidebar panel, not as a widget in the My Widgets sidebar panel. If you choose this option, the Test and Publish panel appears describing what you should do next. Read and then click Finish to exit the wizard and add the widget to your sidebar.
    Just configure a component for now
    This adds the component to the My Widgets sidebar panel. If you choose this option, the Test and Publish panel appears describing what you should do next. Read and then click Finish to exit the wizard and add the widget to your sidebar.
  6. Click Next and Finish to add the widget and close the wizard.
Importing and exporting widgets

You can add a new widget to the My Widgets sidebar panel by importing its properly formatted XML extension file. You can also export the XML extension for selected widgets in the My Widgets sidebar panel to a single XML file.

Import from an XML extension file

You can add a widget to the My Widgets sidebar panel by importing an XML extension.

  1. Click Import... from the My Widgets options menu.
  2. Specify the XML extension filename and click Open.
The widget is added to the My Widgets sidebar panel.
Export widgets to an XML extension file

You can export selected widgets as a single XML extension file.

  1. From the My Widgets sidebar panel, select the widgets that you want to export.
  2. Click Export ... from the My Widgets options menu.
  3. Enter a file name and location at which to create the XML extension file containing the selected widgets and then click Open.
This action exports all selected widgets and actions created for the widgets as a single XML extension file.
Opening a widget in a dashboard

You can select two or more widgets in the My Widgets sidebar panel and open them in a dashboard. This enables you to display and link between multiple services in a single pane. For example, you may want to create a widget that displays both a map and a weather forecast.

In the My Widgets sidebar panel, select the widgets you want to use, right-click, and select Open in a dashboard.
Changing a published widget and updating the catalog

You can change a widget in your My Widgets sidebar panel that you had previously published to the catalog. However, once you change the widget locally, for example by changing a default property value, you must update the catalog master.

  1. From the My Widgets sidebar panel, open the widget that you want to change.
  2. Make the change. For example, for a location-type widget change the default zip code value.
  3. Select the changed widget and click Export from the My Widgets options menu.
  4. As prompted, specify a widget name, keep the .XML widget file extension, and note the directory in which you place the widget XML.
  5. Open the widgets catalog using your Lotus Notes or Domino Administrator client
  6. Locate the widget document in the catalog.
  7. Open the widget document in the catalog and enter Edit mode, for example by clicking the Edit button on the document.
  8. Delete the XML file that is currently attached to the widget document and replace it with the widget XML file that you created in steps 3 and 4.
Removing a component

You might be able to remove a widget from the My Widgets sidebar panel using the Remove option. You cannot remove a widget in this manner if it was installed as part of a widget category.

  1. Right-click the widget in the My Widgets sidebar panel.
  2. Click Remove or select the Widget and click the Delete key.
The widget is removed from the My Widgets sidebar panel
Setting or changing component properties

You can set or change default component properties. For example, properties available for a local weather component could include a zip code.

  1. Right-click a widget and select Properties.
  2. Optionally check Contribute to sidebar on startup option if the component should be added to the sidebar panel. If you enable this option, the widget will open in a separate sidebar panel. If you later click Close on this widget's sidebar panel, you will negate this property value and the widget sidebar panel will be removed.
  3. Make any property changes in the resultant dialog and click OK.
Each widget has unique component properties; some might have no properties at all. Depending on how the widget was created, you might not have edit rights to its component properties.

Packaging applications for deployment

This section describes how to deploy applications.

The term application is used in this section to refer to a group of one or more features that must be deployed together to provide some useful capabilities.

The deployment artifacts are plug-ins, fragments, features, and update sites.

Plug-ins contain the code and resources that provide specific functions. Fragments can contain code to extend other plug-ins, but are typically used to provide locale specific information or operating system specific implementations. Plug-ins and fragments are not individually installed into the client runtime, but must be packaged within a feature. A feature is the minimal install artifact. Features include plug-ins and fragments. Features may also include other features. Features can also require other plug-ins and features to be installed.

An update site is a repository of features. Features on an update site may or may not have any relationship one to another. Depending on the methods used for deployment, update sites are optional. To deploy features without adding them to an update site, you can use the following deployment choices:
  • Feature distribution using the Client Management server
  • Feature distribution using the Portal managed Client
To deploy features that are contained within an update site, you can use the following deployment choices:
  • Local update site
  • Remote update site
  • Local archived update site
  • Update site distribution using the Client Management server
To create features and update sites, use the following tasks:
  • Creating a feature
  • Creating an update site
  • Exporting a feature and its plug-ins

Once the feature or update site is created, see Managing the client runtime for information on deploying the feature or update site.

Understanding feature life cycle

This section describes the life cycle of features for the IBM Lotus Expeditor platform. It is important to understand the feature life cycle when distributing features to client systems.

Just like the plug-ins that exist within the platform, the features that define the plug-ins have a similar life cycle that affects the ability to use what they provide.

A feature exists in one of three states:
Uninstalled
This refers to a feature that is not installed on the platform sites. This is either a feature that has never been installed or one that was previously installed and then had an uninstall operation performed on it. During the uninstall operation, the uninstall methods of the InstallHandler are invoked.
Installed
The installed state is entered either by performing an install action on an uninstalled feature, or disabling an enabled feature.
For an uninstalled feature that is installed, the install related methods of any InstallHandler associated with the feature are called.
For a previously enabled feature that is being disabled, the unconfigure related methods of any InstallHandler are called. For a feature to successfully install, the feature descriptor as well as any required plug-ins must be accessible and valid to be copied to the platform site. In addition, any requirements expressed by the feature must also be met before it can be installed. A validation phase occurs prior to attempting an install to verify that the feature deployment descriptors are accessible, and that the requirements are satisfied. Plug-in existence and validity (that is, the valid signed certificate) are checked during the actual task of installing the feature.
A feature that is only installed does not provide any function to the platform, and its contained plug-ins are not installed into the runtime.
Configured (or Enabled)
The configured (or enabled) state occurs by performing a configure (or enable) operation on a feature in the installed state. During the configure operation, the configure related methods of the InstallHandler are called to perform tasks.
Once configured, the feature and its contained plug-ins are then able to provide function to the platform.
A feature that is currently enabled can be disabled, but only if by doing so it would not invalidate other features dependencies upon the feature or its contained plug-ins.
The enable and disable operations require a platform restart before the results are effective.

Now that the life cycle of features has been explained, we can now discuss the role of the InstallHandler, which was referenced above.

InstallHandlers may be specific to either a single feature, or global to the entire platform. Regardless of the type, the behavior and call sequence is equivalent.

The InstallHandler class will be instantiated prior to any operation. The first call (after the constructor) will always be the initialize method. This method sets up the install handler and provides information that can be used throughout the call sequence.

During an install operation, the following sequence of calls would be made:
  1. initialize()
  2. installInitiated()
  3. pluginsDownloaded()
  4. nonPluginDataDownloaded()
  5. completeInstall()
  6. installCompleted()
Refer to the Javadoc for specific signature information. Once initialize method has been called, the installCompleted call will always be performed. The installCompleted call is passed a Boolean indicating success or failure of the install operation.

Tasks that need to be performed to install the feature should be performed during the range of calls from installInitiated to completeInstall. A CoreException thrown during these methods will result in the feature failing to install. At the point when the installCompleted() method is called, the feature is either installed or not installed. While the signature allows a CoreException to be thrown at this point, it is strongly recommended that features do not throw a CoreException from the installCompleted (true) call, as it will result in error messages being logged, but will still result in the feature being installed.

During the configure (or enable) operation, the following sequence of calls would be made:
  1. initialize()
  2. configureInitiated()
  3. completeConfigure()
  4. configureCompleted()
As in the install case, once the install handler has been initialized, the configureCompleted() method will always be called. As in the install case, the configureCompleted() does allow a CoreException to be thrown, but work should preferably be done in either the configureInitiated or completeConfigure methods. A failure in any of the methods will result in the feature not being configured.
The install handler is also called during the disable operation in the following sequence:
  1. initialize()
  2. unconfigureInitiated()
  3. completeUnconfigure()
  4. unconfigureCompleted()

A CoreException thrown in the unconfigureInitiated method will abandon install handler processing for the feature, and the completeUnconfigure and unconfigureCompleted methods will not be called. Unless exceptions otherwise inhibit the call, unconfigureCompleted() will be called following an initialize. It is suggested that the main install handler work be performed in the unconfigureInitiated() and completeUnconfigure() methods.

Finally, the install handler is called during the uninstallation of a feature.
  1. initialize()
  2. uninstallInitiated()
  3. completeUninstall()
  4. uninstallCompleted()
A CoreException thrown in the uninstallInitiated method will abandon install handler processing for the feature, and the completeUninstall and uninstallCompleted methods will not be called. Unless exceptions otherwise inhibit the call, uninstallCompleted() will be called following an initialize. It is suggested that the main install handler work be performed in the uninstallInitiated() and completeUninstall() methods.

When the multiuser platform configuration is used, features installed by the administrator and available to the users will only be installed a single time. This means that the install methods of the install handlers will be run at most once. For this reason, and in anticipation of a change in a direction of install processing, it is not recommended that install handlers perform work related to feature configuration during the install related methods of the install handler. Features will be configured (or enabled) multiple times, at least once in each workspace, so the preferable location for feature related changes would be the configure related methods.

Creating a feature

To create a feature, use the Plug-in Development Environment within Eclipse or the Rational Software Development platform.

Prior to creating a feature, you should have the plug-ins and fragments that will be contained within the feature:
  1. From your workspace, select File > New > Project > Plug-in Development > Feature Project
  2. Enter the project name. This is typically the same name as the feature ID.
  3. Enter the Feature ID, Feature Name, and Feature Version. The Feature Provider and Install Handler Library are optional.
  4. Select Next.
  5. Select the plug-ins and fragments that you want to add to the feature. If you do not want to enter them at this time, you can select Finish now, and add plug-ins and fragments later using the editor.
  6. The editor opens. Use the editor tabs to specify additional information:
    Overview
    Enter feature descriptive information and supported environments.
    Information
    Enter description, license, copyright, and other update sites to visit.
    Plug-ins
    Enter the plug-ins and fragments that should be packaged, as well as supported environment information if needed.
    Include Features
    Enter the additional features to include, as well as supported environment information if needed.
    Dependencies
    Enter any dependency information that must be met before the feature will install.
    Installation
    Enter information such as install handler and other data files.
    Build
    Select the files that will be packaged into the feature.
  7. Save the contents of the editor.
Refer to the Platform Plug-in Developers Guide and to Eclipse (http://help.eclipse.org/help32/index.jsp) for more information on using the feature editor.

Specifying optional child features

The feature manifest (feature.xml) enables the definition of included features. Included features define a parent-child relationship for features, such that actions on the parent apply also to the child. For example, if the parent is installed, the child is also installed. An included feature may be marked as optional. This would enable a parent to be installed without some of the optional child features.

When the Lotus Expeditor platform installs a new feature, all optional children of the feature, if they are available on the update sites specified during the install operation, will be installed.

Controlling the feature install location

This section explains the available methods for controlling and specifying the target install site for a feature.

The platform provisioning system defines by default the following target sites into which features are installed:
rcp
Contains the features and plug-ins that are part of the Eclipse and client platform.
shared
Contains additional features and plug-ins intended for use by all users of the client platform.
“user”
Located in the workspace, this target site contains additional features and plug-ins intended for use only by a single user of the client platform.

The target install site for a particular feature is determined by evaluating several conditions, including whether the feature is currently installed, colocation-affinity, ability to write a specific directory, and requested target site.

Colocation-affinity is an attribute that can be specified by each feature in the feature.xml descriptor. The colocation-affinity attribute specifies the ID of another feature. It directs the provisioning system to attempt to install the new feature into the same target site that the other feature (the feature whose ID is specified in the feature.xml). Using the Feature Manifest Editor from the Plug-in Development Environment, the colocation-affinity can be specified on the Installation page of the editor.

For example, suppose that feature with an ID of com.ibm.sample has been installed into the shared site. A new feature with an ID of com.ibm.extendedsample can then specify a colocation-affinity of "com.ibm.sample” to request that the feature is installed into the same location as com.ibm.sample:
<feature
      id="com.ibm.extendedsample"
      label="Extendedsample Feature"
      version="1.0.0"
      provider-name="IBM"
      colocation-affinity="com.ibm.sample">
The platform provisioning system uses these decisions to determine the target site for a feature.
  1. If a provisioning system detects a version of the feature that is already installed, the same install site will be used for any additional versions. This only applies when the feature has been installed into the Eclipse, RCP, or shared target sites.

    If a deployer installs a feature X version 1.0.0 into the shared site, and later attempts to install feature X version 1.0.1, then version 1.0.1 will be installed into the shared site.

    If a user A installs a feature Y into their user site in their workspace A, and later another user B attempts to install feature Y, feature Y will be installed a second time into the workspace B, since workspace A is not visible to user B.

  2. If feature.xml specifies the colocation-affinity attribute, then the following decisions are made:
    1. If the feature that was specified in the colocation-affinity attribute is installed, then attempt to install into that site. If that site is not accessible to the user installing the feature, the feature installation will fail.
    2. If the feature that was specified in the colocation-affinity attribute is not installed, then continue with step 3 in the decision process.
  3. If a specific target site is requested for the feature, then attempt to install the feature into this site. If that site is not accessible, then continue with step 5. A target site can be specified only for features distributed through the Eclipse feature distribution job using the Device Management server.
  4. If the provisioning manifest or a ProvisioningRequest (provided through an API request) specifies shared = true, then the shared site is the desired target site for installing the feature. If that site is not accessible, then continue with step 5. (Refer to Provisioning manifest DTD for more information on the attributes available through the provisioning manifest.
  5. If the provisioning manifest or a ProvisioningRequest object specifies shared = false, or if because of accessibility issues, the desired target sites for step 3 and step 4 are not available, then attempt to install the feature into the “user” site.
Since the colocation-affinity takes precedence over target site or shared attribute specification, specifying a colocation-affinity is the preferred model for controlling feature install locations. The client platform has defined the following features that can be used as targets for the colocation-affinity attribute:
com.ibm.rcp.site.anchor.shared.feature
This feature is always installed into the shared site.
com.ibm.rcp.site.anchor.user.feature
This feature is always installed into the user site.
If the platform is only ever used by a single user with a single workspace, then the target site for a feature is less important, since all features will always be available. In the multiuser configuration, the target install site becomes much more important, since some applications should be shared among all users of the platform, while other applications should be private to specific users.

As an example, assume a multiuser configuration in which deployers have admin rights to the shared directory, while ordinary users are limited to read-only rights. Feature W does not contain a colocation-affinity attribute. If a deployer attempts to install this feature, it will be installed into the shared directory, since this is the default option with no colocation-affinity and no target site specified. However, if a user attempted to install this feature, it would be installed into the user target site, and could not be shared by all users on the platform. The user site would be selected since the shared site is not accessible.

To limit the ability of a specific user to install feature W into their user site, the deployer could specify a colocation-affinity attribute with the ID “com.ibm.rcp.site.anchor.shared.feature”. The resultant site for a deployer would still be the shared site, chosen now not because it is the default, but because the colocation-affinity selects that site. A user attempting to install the feature would have the feature installation fail, since the site specified by the colocation affinity is not accessible.

Enabling features for update

This section provides information about how feature updates are handled. Updating an application is similar to the initial installation.

The Lotus Expeditor uses the rcp/eclipse directory within the Lotus Expeditor root for its own features and plug-ins. The shared directory is provided as an Eclipse extension, and the default installation location for new features.

When new versions of features are provided, they are installed into the same directory as the previous version. The installation directory for a feature update cannot be changed. Some features have a colocation-affinity attribute specified. In this case, the feature and its plug-ins are installed to the same location as the feature specified by the colocation-affinity attribute.

Versions for features are specified using major.minor.service qualifier. For example, a version of 4.0.1 has a major version of 4, a minor version of 0, and a service version of 1. An equivalent version is a version that differs first at the service level. A compatible version is a version that differs first at the minor level. For example, using our version 4.0.1 in the previous example, a version of 4.0.2 would be an equivalent version, because the service value is the first value that changed. A version of 4.1.2 would be a compatible version, because the minor value is the first value that changed. A major version is a version that differs first at the major level. For example, using our version of 4.0.1, a version of 5.0.0 would be considered a major version upgrade.

The Automatic Updates capability provided as part of the Application Manager dialog enables updates of only major, equivalent or compatible versions, according to the preferences selected in the Install/Update dialog, which you access as follows: Manage > Preferences > Install/Update. The default value is for equivalent updates. Updates can only be performed here for features that have the URL and update attributes specified in their feature.xml file. For example:

<url>
     <update_label="Your Update Site"
     url=http://updatesite/com.your.plugin.site/site.xml>
</url>

For additional information on versioning, refer to the Feature manifest section of the Platform Plug-in Developer's Guide and to Eclipse (http://help.eclipse.org/help32/index.jsp).

Eclipse feature update on devices

You can search for updates to one or all existing applications that are installed on the Lotus Expeditor on the device. When new versions of features are available, they are installed into the same directory as the previous version. The installation directory for a feature update cannot be changed.

The default update type on the Lotus Expeditor for Devices is equivalent. This means that the update process will search for all equivalent versions on the update site and update to the highest of all versions. The update type can not be changed by the user. However, the administrator can change it using a properties configuration job. To change the update type, modify the following property:
./Configuration/Properties/config.ini/Eclipse.update.core.updateVersions
where config.ini is the file name, and Eclipse.update.core.updateVersions is the property key. There are three supported property values: equivalent, compatible, and major. The equivalent value means the update process only searches equivalent versions on the update site. The compatible value means the update process searches all equivalent and compatible versions, and the major value means the update process will search all versions greater than the existing one.

Exporting a feature and its contents

Once the feature is defined, to deploy the feature, you will need to export the feature and its plug-ins.

If you will be creating an update site, skip to Creating an update site.

If you will be just deploying the feature, then you will need to build and export the feature and its contents. Select File > Export > Plug-in Development > Deployable Features.

Select the features to export, enter a directory or archive file, then select Finish. The feature contents, as well as the included plug-ins, fragments, and features will be exported to the desired directory or archive file.

Refer to the Platform Plug-in Developers Guide and to Eclipse (http://help.eclipse.org/help32/index.jsp) for more information on using the feature editor.

Creating an update site

An update site project can be created either inside your current workspace, or you can create it anyplace on the local file system.

Follow these steps to create an update site
  1. Select File > New > Project > Plug-in Development > Update Site Project.
  2. Enter the project name, then select Finish.
  3. The Site Manifest Editor opens, enabling you to add features to the site. Select Add Feature to add features to the site.

    You only need to add the features that you specifically want to make available for installation. Features included in other features do not need to be added here unless you want to make them separately installable.

  4. Once you have added all the features, select Build or Build All to build the features and the feature content.
Refer to the Platform Plug-in Developers Guide and to Eclipse (http://help.eclipse.org/help32/index.jsp) for more information on using the update site editor.

Using the global install handler

Install handlers are Java classes that are run by the Update Manager during the install, configuration, and uninstall processing of a feature.

Update manager can handle standard installation of features, plug-ins, and fragments without writing any Java code. However, if additional tasks are required to be performed during install, configuration, and uninstall processing, an install handler can be used to perform these tasks. An example of tasks that might be performed by install handlers include configuration file updates.

The client platform provides an install handler that can be used to perform updates to files present on the client system. The install handler provides additional capabilities beyond that offered by the default install handler provided by Eclipse. Capabilities provided by the install handler include the following:
  • Ability to modify rcpinstall.properties settings for:
    • bootclasspath
    • PATH / LD_LIBRARY_PATH
    • class path
    • VM System properties
    • VM
    • Other properties
  • Ability to set locations of Virtual Machine (VM) that implements the Java specifications, RCP base location, RCP launcher location, provisioning manifest location and version
  • Ability to launch a native script or executable

Creating the install handler instructions file

The install handler processes instructions from a file named handler.properties that is present within the feature.

The handler.properties files should not contain absolute path references, as the actual file location may change depending upon either the launch directory or the workspace directory. The available substitution parameters should be used instead, as these will correctly handle the changes to ensure correct operation of the platform when either the launch location or workspace directory location changes.

All normal commands ("exec.command"-related commands) get executed during the completeConfigure() phase of installation. It is also important to note that most commands ("exec.command"-related commands) should properly remove their actions during the completeUnconfigure() phase of installation.
Xbootclasspath.prepend=<path>
Xbootclasspath.append=<path>
Adds all listed entries to the Xbootclasspath.prepend or Xbootclasspath.append properties in rcpinstall.properties.

Used by the native launcher to set the vm option -Xbootclasspath.

library.path.prepend=<path>
library.path.append=<path>
Adds all listed entries to the library.path.prepend or library.path.append properties in rcpinstall.properties

Modifies PATH on Windows or LD_LIBRARY_PATH on Linux.

-D<value>=<pair>
Adds value-pair settings to add VM system properties definitions to rcpinstall.properties.

Used by the native launcher to add settings to the VM.

vm
Adds vm setting to rcpinstall.properties.

Used by the native launcher to add entries to the system path variable.

vmarg.<key>=<value>
Used to pass VM arguments. The entry is written to the rcpinstall.properties file and is processed by the rcplauncher.
jvm.location=<value>
Modifies the VM location in rcplauncher.properties.
rcp.base.location=<value>
Modifies the rcp base location in rcplauncher.properties.
rcp.launcher.location=<value>
Modifies the rcp launcher location in rcplauncher.properties.
exec.command.<os><arch>.<#>=<command>
u.exec.command.<os><arch>.<#>=<command>
Executes a command using the Runtime.exec() from the feature directory. exec.command is processed during the feature enable processing. u.exec.command is processed during the feature disable processing. If an argument in the <command> contains spaces, then include the argument in quotation marks (""). The exec and u.exec commands that match the current platform OS and architecture are executed in numerical order. Use either all numbered commands or all unnumbered commands. Using a mixture of numbered and unnumbered commands results in a syntax warning. The exec.command/u.exec.command can be useful for running scripts or registering Windows services. For example:
exec.command.win32x86.1=regsvr32 /s my.dll
exec.command.linuxx86.1=sh –c myscript.sh
exec.command.win32x86.2="C:\Program Files\SomeProgram\Program.exe"
"C:\Documents and Settings\user\Application Data
"
mergemanifest=<value>
Merges the file specified by <value> into the current provisioning manifest identified by rcplauncher.properties. <value> is expected to be a file system location for a new provisioning manifest file. Examples of the mergemanifest command are as follows:
mergemanifest=${plugin.dir}/com.ibm.rcp.newmanifest_1.0.0/upgrade.xml

mergemanifest=${features.dir}/com.ibm.rcp.newmanifest.feature_1.1.0/install.xml
See Understanding the merge processing for the provisioning manifest for more information on the merge processing.
product=<value>
Specifies the product ID that will be used as the default by the platform. This results in the addition of the product property to the rcplauncher.properties file. This command is typically used by a branding feature that has provided a new product definition. The product attribute is removed during a feature disable operation.
config.<configuration>.<id>=<value>
Adds a config line to the rcplauncher.properties file. See Updating the rcplauncher.properties file for more information on the how the config attribute is used in the rcplauncher.properties file.
file.copy.<id>=<target><tab><source>
Performs a file copy operation during the feature enablement operation.
<id>
Unique identifier differentiating multiple file copy commands
<target>
Target file. If the target file location has directory locations that do not exist, they will be created by the copy command.
<tab>
Tab character that is used to separate source and target
<source>
Target file
When disabling the feature, the <target> file is removed.
product.name
Specifies the registry key (Windows) or filename (Linux) that contains the path to the launcher program. See Locating the Lotus Expeditor Client launcher program for more information on how the product.name command is used. The product.name command would typically be used as part of a branding operation. On feature disable, the registry key or file will be removed.
osgi.splashPath=<value>
Adds the osgi.splashPath property to the rcplauncher.properties file. The value is a URL referring to the location of the splash image. As an example, the branding feature for IBM Lotus Expeditor specifies the following:
osgi.splashPath=platform\:/base/rcp/eclipse/plugins/...
   com.ibm.rcp.platform.personality.branding
This command is typically used by a branding feature that needs to specify the splash image. On feature disable, the property will be removed from the rcplauncher.properties file.
env.set.<id>=<value>
Adds the env.set.<id>=<value> property to the rcpinstall.properties file. See Updating the rcpinstall properties file for more information on how the env.set property is used in the rcpinstall.properties file.
logger.<logger command>=<level>
This action adds the logger command = level entry to the rcpinstall.properties file. For examples of logging levels, refer to Updating the rcpinstall properties file.
plugincustomization.<preference name>=<preference value>
This action adds the preference name=value entry to the plugin_customization.ini file.
Note: Updates to this file require administrative privileges on the client system.
registry.<action>.<entry>.<#>
u.registry.<action>.<entry>.<#>
registry is processed during the enable phase. You can prefix any entry with u. in order to process during the disable phase. The table below describes the actions that you can use with the registry and u.registry commands.
Table 26. Registry action command syntax
Action Description
registry.create_key Creates a registry key
registry.create_key.key.<#>=<key> Specifies the location of the key containing the subkey to create (relative to HKCU)
registry.create_key.subkey.<#>=<subkey> Specifies the registry subkey to create
 
registry.delete_key Deletes a registry key
registry.delete_key.key.<#>=<key> Specifies the location of the key containing the subkey to delete (relative to HKCU)
registry.delete_key.subkey.<#>=<subkey> Specifies the registry subkey to delete
 
registry.delete_value Deletes a registry value
registry.delete_value.key.<#>=<key> Specifies the location of the key containing the value to delete (relative to HKCU)
registry.delete_value.valuename.<#>=<valuename> Specifies the name of the registry value to delete
   
registry.set_value Sets a registry value
registry.set_value.key.<#>=<key> Specifies the location of the key containing the value to set (relative to HKCU)
registry.set_value.valuename.<#>=<valuename> Specifies the name of the registry value to set
registry.set_value.value.<#>=<value> Specifies the registry value to set
registry.set_value.type.<#>=<type> Type of value to set (Bytes, Int, or String). For values of type bytes, no codepage conversion is done.
registry.set_value.overwrite.<#> = <boolean> (Optional) Action to take if value already exists (true or false). The default value is true. This option is only used if a value exists where the write is attempted.
The following tokens are supported for paths in the handler.properties file:
${product.install.dir}
${rcp.home}
The install directory for the platform.
${features.dir}
The features directory of the site to which the current feature is being installed.
${old.feature.dir}
The previous install directory of the feature if it exists.
${plugin.dir}
The plug-ins directory of the site to which the current feature is being installed.
${plugin.dir.<id>}
The install directory name for the given plug-in <id>.
${old.plugin.dir.<id>}
The previous install directory name for the given plug-in<id>.
${rcp.os}
The platform operating system (for example, win32).
${rcp.arch}
The platform Architecture (for example, x86).

Creating instructions for desktop updates

The global install handler supports the creation of desktop-related objects.

Use the global install handler to:
  • Create/delete a desktop link (Windows only)
  • Create a program group (Windows and Linux only)
  • Add/remove a link to the program group (Windows and Linux only)
To enable these functions, include a /links directory in your feature with properties files that fill in the following properties. It is also possible to include a directory (named for your operating system and architecture) that will read property files only when the proper operating system and architecture uses the feature. For example, if you create a directory named /win32x86 in your feature, the property files inside this directory would only be applied if your operating system is win32 and your architecture is x86.
The format of the properties files for creating links and program groups is as follows:
Table 27. Properties files format
Link key name String constants Required Description
link.context
CONTEXT_DESKTOP 
CONTEXT_PROGRAMS
yes Value can be one of the constants. Sets operation context to be either desktop or program group.
link.foldername N/A no This value is only used when the context of a link is CONTEXT_PROGRAMS. This is the program group folder name. If omitted, the link will be created in the root program group.
link.displayname N/A yes This is the display name of the link. In windows the link filename would be <display name>.lnk.
link.iconpath Can start with one of the following path constants:
$FEATURE_DIR 
$RCP_DIR 
$ECLIPSE_DIR 
$WORKSPACE_DIR
INSTALL_DIR
no Only required if the target exec does not have a built-in icon resource. Used to specify an icon for a program link. Example values:
c:\\winnt\\icon.ico
$FEATURE_DIR\icons\
myicon.ico
link.target Can start with one of the following path constants:
$FEATURE_DIR 
$RCP_DIR 
$ECLIPSE_DIR 
$WORKSPACE_DIR
$INSTALL_DIR
yes This is the path and filename of the target exec to launch. Example values:
c:\\winnt\\notepad.exe
$RCP_DIR\\
rcplauncher.exe
link.args N/A no This is the command line arguments for the target
link.workingdir Can start with one of the following path constants:
$FEATURE_DIR 
$RCP_DIR 
$ECLIPSE_DIR 
$WORKSPACE_DIR
$INSTALL_DIR
no This is the path and filename of the target exec to launch. Example values:
c:\\myworkingdir 
$ECLIPSE_DIR
link.windowstate Can be one of the following window state constants:
WINDOW_STATE_NORMAL 
WINDOW_STATE_MIN 
WINDOW_STATE_MAX
no This is the initial window state of the target exec.
link.categories N/A no Only supported on Linux. This specifies where the main icon should be created. Example value: Application;Office;
Table 28. String constants - Link context constants
String constant Description
CONTEXT_DESKTOP Indicates that this is a desktop link
CONTEXT_PROGRAMS Indicates that this link is a program group.
Table 29. String constants - Path substitution constants
String constant Description
$FEATURE_DIR Used where allowed for path substitution. Resolves to the installed path to this feature's root directory. Example:
C:\Documents and Settings\testuser\Application Data\Lotus\XPD\
applications\eclipse\features\com.ibm.rcp.installhandler.test.feature
$RCP_DIR Used where allowed for path substitution. Resolves to the root of the installed RCP client RCP directory. Example:
c:\ibm\rich client\rcp 
$ECLIPSE_DIR Used where allowed for path substitution. Resolves to the root of the installed RCP client Eclipse directory Example:
c:\ibm\rich client\rcp\eclipse
$WORKSPACE_DIR Used where allowed for path substitution. Resolves to the active user's workspace root. Example:
C:\Documents and Settings\someuser\Application Data\Lotus\XPD
$INSTALL_DIR Used where allowed for path substitution. Resolves to the root of the platform directory. Example:
C:\ibm\expeditor
Table 30. Link window state constants
String constant Description
WINDOW_STATE_NORMAL Used by links to set the initial launch state of the target to normal.
WINDOW_STATE_MIN Used by links to set the initial launch state of the target to minimized.
WINDOW_STATE_MAX Used by links to set the initial launch state of the target to maximized.
Use the following tables to locate icons, depending on the type of user and features and the installation configuration.
  • Windows desktop shortcut and menu locations:
    Table 31. Windows desktop shortcut and menu locations
    Scenario Desktop shortcut location Menu location
    Admin user and feature are shared Shortcut goes to all users/desktop Menu goes to All Users/Start Menu
    Admin user and feature are not shared Shortcut goes to admin/desktop Menu goes to admin/Start Menu
    Non-admin user and feature is shared Shortcut goes to user/desktop Menu goes to user/Start Menu
    Non-admin user and feature is not shared Shortcut goes to user/desktop Menu goes to user/Start Menu
  • Linux desktop shortcut and menu locations:
    Table 32. Linux menu and shortcut locations
    Scenario Menu or shortcut location
    Admin user and feature are shared Menu goes to /usr/share/applications
    Admin user and feature are not shared Menu goes to admin_home/.local/share/applications
    Non-admin user and feature is shared Shortcut goes to user_home/.local/share/applications
    Non-admin user and feature is not shared Shortcut goes to user_home/.local/share/applications

Adding the global install handler to a feature

You can add the global install handler to a feature.

To add the global install handler to the feature.xml, use the Feature Manifest Editor.
  1. Open the feature.xml file using the Feature Manifest Editor.
  2. Select the Installation tab
  3. Enter com.ibm.rcp.installhandler.RCPInstallHandler as the Handler class. No entry is required in the Library attribute.
  4. Select the Build tab in the Feature Manifest Editor.
  5. Verify that the file handler.properties is checked in the binary build section.
  6. Verify that the links directory, if used, is checked in the binary build section.
  7. Save the feature.xml file.

Deploying features to the platform

This section describes the information and tasks necessary to deploy application and infrastructure features to the client platform.

Note: If you are using Windows Vista, be sure to review Administering the platform on Windows Vista prior to changing the platform configuration.
There are four mechanisms for deploying features to the client platform:
Portal managed provisioning
A provisioning manifest is distributed from the Portal server to the client containing the instructions on what features to install, and where to install them from. For more information, see to Managing Rich Clients using the Portal server.
Client management server-based provisioning
Specific Eclipse feature installation and management jobs are created at the server, distributed to the client, and processed by the Enterprise Management Agent. For more information, see Managing with a Client Management server.
Using the provisioning application and provisioning manifest
The Provisioning Manifest is an XML file containing a set of instructions pertaining to the features to install, enable, disable, or remove. This can be used by any user or as a mechanism initiated from another management system. For more information, see Managing using another management system.

Changes initiated using the provisioning application are specific to only a single runtime, but the steps to request the changes can be easily replicated to many systems.

Using the application install and application management dialogs
The individual user specifically installs and manages the installed features using the available dialogs. Changes are specific to only a single configuration, and the steps must be performed by all users. This mode of operation is typically used by deployers in a test mode, by application developers, or in scenarios where there might only be a few locally installed platforms.
Changes to the platform restart in Lotus Expeditor 6.2.0
Deploying features to the platform requires the user to restart the platform to activate newly installed or updates to the existing features. When the restart dialog appears, the user will have two choices, restart now or wait a predetermined number of minutes. When the user chooses to wait, the platform will remind the user after the predetermined number of minutes by presenting the restart dialog again. When a composite application is deployed, the platform requires the user to restart the platform to activate the application. When the application is deployed, the user is presented with a restart dialog with two choices, restart now or cancel. When the user chooses cancel, the activation of the application is deferred until the platform is restart and a status indicator is activated on the task bar. When the status indicator is selected, the user can view the pending applications. The user will be reminded that the platform is waiting to be restarted after the predetermined number of minutes.

Using any of the above methods, you can perform the following tasks.

Installing features in a multiple user environment

As administrator, you are responsible for performing the initial installation, and should restrict directory access for other users to the original install to read/execute access only.

When another user launches Lotus Expeditor Client for the first time, a new workspace will be created based upon the installed platform using the provisioning manifest specified in the rcplauncher.properties file.

On subsequent launches by the same user, the value of the provisioning.manifest.version in the user's rcpinstall.properties file is compared to the value specified in the platforms rcplauncher.properties file. If the values are different, then the launcher will start the provisioning application to reprocess the provisioning manifest defined in the rcplauncher.properties file.

To install applications for multiple users (non-Restricted Workbench), there are some thing to consider. As administrator, if you intend to install and enable features for every user on the system, then follow these steps. Otherwise, see Adding a new feature to the shared install site and Adding a new feature to the user install site.
  1. If using Linux, modify owner permissions of the <users workspace> directory by specifying chown -R root <users workspace> where <users workspace> is the fully qualified directory containing logs, applications, and .config directories. Example: /home/myuser/Lotus/XPD
  2. Launch the Lotus Expeditor Client with the -data <users workspace> command line parameters, where <users workspace> is the fully qualified directory containing logs, applications, and .config directories. Windows Example: C:\Documents and Settings\myuser\Application Data\Lotus\XPD Linux Example: /home/myuser/Lotus/XPD
  3. Click File > Application > Application Management, then locate the applications to enable for this user.

    For each feature that needs to be enabled, select the feature, then select the Enable action. If multiple features need to be enabled, you must enable them one at a time. Despite being prompted to restart after every action, you can enable multiple features before restarting.

  4. Allow the Lotus Expeditor Client to restart when you are prompted and ensure the new applications are available
  5. Exit the Lotus Expeditor Client.
  6. If using Linux, restore owner permissions of the <users workspace> directory by specifying chown -R <username><users workspace> where <username> is the Linux login identity for the user.
    Note: These steps must be completed for each user you want enabled for the newly installed application.
    Additionally, it is possible for each user to enable the applications as needed by performing steps 2 and 3 above after launching the Lotus Expeditor Client normally.
When installing applications for Linux Restricted Workbench users, you should know that the Restricted Workbench prevents normal users from installing applications; requiring you, as the administrator, to perform all installations. To install applications for Restricted Workbench users, perform the following steps:
  1. Log in to the operating system as the administrative user that installed the Lotus Expeditor Client.
  2. Launch Lotus Expeditor Client.
  3. Click File > Application > Install and use the installation wizard to install the desired applications.
  4. Allow the Lotus Expeditor Client to restart when you are prompted.
  5. Exit the Lotus Expeditor Client.
  6. Modify owner permissions of the <users workspace> directory by specifying chown -R root <users workspace> where <users workspace> is the fully qualified directory containing logs, applications, and .config directories. Example: /home/myuser/Lotus/XPD
  7. Launch the Lotus Expeditor Client with the -data <users workspace> command line parameters, where <users workspace> is the fully qualified directory containing logs, applications, and .config directories. Example: /home/myuser/Lotus/XPD
  8. Click File > Application > Application Management, then locate the applications to enable for this Restricted Workbench user.

    For each of the features that need to be enabled, select the feature, then select the Enable action. If multiple features need to be enabled, you must enable them one at a time. Despite being prompted to restart after every action, you can enable multiple features before restarting.

  9. Allow the Lotus Expeditor Client to restart when you are prompted and ensure the new applications are available.
  10. Exit the Lotus Expeditor Client.
  11. Restore owner permissions of the <users workspace> directory by specifying chown -R <username><users workspace> where <username> is the Linux login identity for the user.
  12. Log out of the operating system administrative user.
  13. Log in to the operating system as the Restricted Workbench user. This will automatically start the Lotus Expeditor Client and the applications will now be available.
Note: These steps must be completed for each Restricted Workbench user.

Adding a new feature to the shared install site

The preferred model for an administrator is to add a new feature to the platform in the shared site (shared directory) using the Device Manager server, Portal Managed provisioning, or other means.

Since the provisioning.manifest.version will not match the values in the users' workspaces, as they individually start their platform, they will automatically receive the new feature enabled in their configuration.

The administrator can also manually add a new feature onto the platform in the shared install site (shared directory). The feature will be installed following the install site selection rules defined in Controlling the feature install location. Once the feature has been added to the platform, it will be automatically enabled in the user's configuration as he starts his platform.

Adding a new feature to the user install site

Users are permitted to install features into an install site present in their workspace. These features are available only to the user that has installed the feature.

Additionally, if the deployer wants applications to be individually deployed to users' workspaces, the deployer can also follow similar steps as Adding a new feature to the shared install site. By updating the provisioning manifest to include the feature, but specify an attribute shared with a value false, the feature is directed to install into the user site.

Deleting features from the shared install site

If the administrator deletes a feature from the platform prior to being removed from the user workspaces, then the user's platform configuration will be missing the feature. When the individual users launch their platform, each user's platform configuration is modified to automatically remove the missing feature.

Deleting features from the user install sites

Users can delete features from their own configuration, but cannot affect the features installed in the shared site or in other user sites.

If the deployer had configured the provisioning manifest to install the feature into the user install site, then the action for the feature can be changed to “uninstall” to remove it from each of the users configurations when they restart their platform.

Using the provisioning manifest

The Expeditor Client installation process consists of two steps: installation of core platform files and provisioning of additional components. Depending on the desired install configuration (user or multiuser), differing sets of components are provisioned to the product from update sites.

The set of components to be provisioned is defined within a provisioning manifest, which is processed by the installer and platform provisioning system. The file must be named install.xml and be located in a deploy/ directory located in the same location as the installer executable

The Expeditor Client CD includes a provisioning manifest for each of these install configurations. You cannot modify these files because they reside on the CD. However, if the contents of the install directory were copied to a read-write file system (as in the case of a Web download scenario), then the files can be modified to have each of these install configurations include a customized set of components.
Note: Modifying these provisioning manifests from their shipped states could result in an invalid platform installation.

During the installation process, the provisioning manifest is processed (replacing any supported variables) and copied to <product destination>/rcp/deploy/install.xml.

The location of this file is then passed to the platform provisioning component to begin the provisioning process.

The Expeditor platform defines a default set of features that will be provisioned during the initial installation. The list of features can be updated prior to installation to either remove features that are not desired, or to add custom or application specific features.

In all configurations, the launcher (rcplauncher.exe) reads the rcplauncher.properties to determine the provisioning.manifest.version property, and compares to the version currently specified in the rcpinstall.properties. If the version in rcplauncher.properties is greater than the version in the rcpinstall.properties file, then launcher will start the platform provisioning application to update the platform based upon the provisioning manifest (specified in the rcplauncher.properties).

In the multiuser platform configuration, the provisioning manifest is therefore used as the basis for creating the new workspace for every user.

By updating the provisioning manifest contents, and the provisioning.manifest.version, the launcher will start the provisioning application to process the provisioning manifest.

While the provisioning manifest can be directly updated on the system, the preferred model for distributing a new manifest is to use the mergemanifest command provided by the Global Install Handler. The install handler provides a mechanism to deploy a new provisioning manifest and to merge it with the existing manifest present on the system. This enables the deployment of a subset of new changes that will be merged into the existing manifest without requiring the specification of an entire file.

The mergemanifest command is also used to deliver a new version of the provisioning manifest, such as occurs during an upgrade of the existing platform.

Understanding the merge processing for the provisioning manifest

The provisioning manifest generally serves two purposes. During the initial installation, the provisioning manifest provides instructions for the install program to specify the options available for installation, and also specifies the features that need to be installed during the initial provisioning. Subsequent to the install, the provisioning manifest is used during the construction of new workspaces to provide the initial configuration for those workspaces.

The provisioning manifest is also used during subsequent provisioning operations to make modifications to the installed platform. During upgrades initiated through the install program, or upgrades initiated via an install update site, a new provisioning manifest may be provided to the platform to provide instructions for the new workspace configuration. Since the original provisioning manifest may have been modified by a deployer to customize the platform, the new provisioning manifest is merged with the current provisioning manifest.

When a new provisioning manifest is merged with an existing provisioning manifest, the new provisioning manifest can contain mergeaction attributes on the features and installfeatures present in the provisioning manifest. The mergeaction attributes provide the rules on how to merge the content of the two provisioning manifest files.

The general principle is that what was previously installed will stay installed. Generally only upgrades to existing components will be performed, and new components will not be installed, unless required as a dependency.

More specifically, the following rules control the merge process:
Table 33. Merge process control rules
Current manifest New manifest Result if mergeaction="Add" Result if mergeaction="Remove" Result if mergeaction not specified
Feature specified Feature specified Feature retained with new feature attributes Feature removed from the provisioning manifest Feature retained with new feature attributes
Feature specified Feature not specified n/a n/a Feature retained with old feature attributes
Feature not specified Feature specified Feature retained with new feature attributes Feature removed from the provisioning manifest Feature removed from the provisioning manifest
The merge action specified here is defined in the provisioning manifest definition. The merge action only applies to the provisioning manifest and does not apply to the features already present on the file system. During the merge process, the merge action attribute is removed.

In the provisioning manifest, features are elements of the installfeature element. The table above defines the results on a feature by feature basis within an install feature with the same ID.

Install features also define merge actions that are processed according to this table:
Table 34. Additional merge actions
Current manifest New manifest Result with mergeaction=”Add” Result with mergeaction=”Remove” Result with no mergeaction attribute
Install feature specified Install feature specified New install feature retained in manifest, overwriting old contents Entire install feature is removed from manifest Features within the install feature are individually merged
Install feature specified Install feature not specified n/a n/a Old install feature definition retained
Install feature not specified Install feature specified New install feature retained in manifest Install feature removed from manifest Install feature removed from manifest
The following scenarios will help illustrate the processing during the merge operation.
Scenario I

The product's original manifest was used during install, and the product installer is used with the upgrade product's new manifest.

The original manifest contained these definitions:
<feature id="A" version="1.0"/>
<feature id="B" version="1.0"/>
<feature id="C" version="1.0"/>
The new manifest contained these definitions:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
The features already installed on the system will be upgraded as part of the new installation. New optional components provided as part of the product will not be added to the manifest since they were not previously present. New required components will be specified in the manifest with merge=”add” attributes. The resulting manifest will be the following:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
Scenario II

The product's original manifest was modified by the deployer prior to initial install to remove some of the product features. The product installer is used with the upgrade product's new manifest (without modifications).

The original manifest contained these definitions:
<feature id="A" version="1.0"/>
<feature id="C" version="1.0"/>
The new manifest contained these definitions:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
Only the features already present in the original manifest will be in the resultant manifest. Original product features removed by the deployer will be removed from the resultant manifest, and therefore will not be installed or upgraded. New optional components provided as part of the product will not be added to the manifest since they were not previously present. New required components will be retained in the manifest since they were specified with the merge="add" attributes.
The resulting manifest will be the following:
<feature id="A" version="1.0.1"/>
<feature id="C" version="2.0"/>
Scenario III

The products original manifest was modified by the deployer prior to initial install to add additional custom features. The product installer is used with the upgrade product's new manifest.

The original manifest contained these definitions:
<feature id="A" version="1.0"/>
<feature id="B" version="1.0"/>
<feature id="C" version="1.0"/>
<feature id="D" version="4.0"/>
The new manifest contained these definitions:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
All of the features present in the original manifest will be retained, including the custom features. Upgrades to the product components will be retained since they are present in the existing manifest. New optional components will not be added to the manifest. New required components will be added to the manifest since they contain the merge="add" attribute.
The resulting manifest will contain the following:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
<feature id="D" version="4.0"/>
Scenario IV

The deployer needs to remove a feature from the resulting manifest. The feature must be specified in the upgrade manifest with a mergeaction="remove".

The original manifest contained these definitions:
<feature id="A" version="1.0"/>
<feature id="B" version="1.0"/>
<feature id="C" version="1.0"/>
The new manifest contained these definitions:
<feature id="A" version="1.0"/>
<feature id="B" version="1.2" mergeaction="remove"/>
<feature id="C" version="2.0"/>
The resulting manifest will contain the following definitions:
<feature id="A" version="1.0.1"/>
<feature id="C" version="2.0"/>
Scenario V

The deployer needs to add a new feature to the system via the merge process. The feature must be specified in the upgrade manifest with a mergeaction = add.

The original manifest contained these definitions:
<feature id="A" version="1.0"/>
<feature id="B" version="1.0"/>
<feature id="C" version="1.0"/>
The new manifest contained these definitions:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
<feature id="E" version="1.2" mergeaction="add"/>
The resulting manifest will contain the following definitions:
<feature id="A" version="1.0.1"/>
<feature id="B" version="1.2"/>
<feature id="C" version="2.0"/>
<feature id="E" version="1.2"/>
Scenario VI
A new installfeature is available containing optional features, and needs to be added to the provisioning manifest The original provisioning manifest contains the following:
<installfeature id=”A” name=”Required Feature A” required=”true”>
...
</installfeature>
<installfeature id=”B” name=”Optional Feature B” required=”false”>
...
</installfeature>
The upgrade provisioning manifest contains the following:
<installfeature id=”A” name=”Required Feature A” required=”true”>
...
</installfeature>
<installfeature id=”B” name=”Optional Feature B” required=”false”>
...
</installfeature>
<installfeature id=”C” name=”Optional Feature C” required=”false” mergeaction="add">
...
</installfeature>
Following the rules defined above, since neither installfeature A nor B includes a mergeaction, the features present in each of these installfeatures will be merged together. Since installfeature C contains a mergeaction specified as add, then installfeature C will be retained in the resulting manifest.
<installfeature id=”A” name=”Required Feature A” required=”true”>
...
</installfeature>
<installfeature id=”B” name=”Required Feature B” required=”false”>
...
</installfeature>
<installfeature id=”C” name=”Optional Feature C” required=”false”>
...
</installfeature>
Scenario VII
One of the features has been enhanced, but has now become an optional installation component. The original provisioning manifest contains the following:
<installfeature id=”A” name=”Required Feature A” required=”true”>
  <feature id=”A.1” version=”1.0”/>
...
</installfeature>
<installfeature id=”B” name=”Optional Feature B” required=”false”>
...
</installfeature>
The upgrade provisioning manifest contains the following:
<installfeature id=”A” name=”Required Feature A” required=”true”>
   <feature id=”A.1” version=”1.0” mergeaction=”remove”/>
...
</installfeature>
<installfeature id=”B” name=”Optional Feature B” required=”false”>
...
</installfeature>
<installfeature id=”C” name=”Optional Feature C” required=”false” mergeaction=”add”>
   <feature id=”A.1” version=”2.0”/>
...
</installfeature>
Following the rules defined above, since neither installfeature A nor B includes a mergeaction, the features present in each of these installfeatures will be merged together. Since feature A.1 has a mergeaction of remove from installfeature A, it will be removed from installfeature A in the result. Since installfeature C contains a mergeaction specified as add, then installfeature C will be retained in the resulting manifest. All features present in installfeature C will be added, so feature A.1, previously removed from installfeature A, is now contained in installfeature C.
<installfeature id=”A” name=”Required Feature A” required=”true”>
...
</installfeature>

<installfeature id=”B” name=”Optional Feature B” required=”false”>
...
</installfeature>

<installfeature id=”C” name=”Optional Feature C” required=”false”>
   <feature id=”A.1” version=”2.0”/>
...
</installfeature>  

Provisioning manifest DTD

The provisioning manifest is an XML file that lists the features to be installed during the provisioning portion of the install process.

The structure of the provisioning manifest is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!-- The root tag of the CA XML formatted file. -->
<!ELEMENT ibm-portal-composite (domain-object)+>

<!-- When specified with a name attribute of "com.ibm.rcp.installmanifest",
     this denotes that this is an install manifest object. -->
<!ELEMENT domain-object (object-data)+>
<!ATTLIST domain-object name CDATA #FIXED "com.ibm.rcp.installmanifest">

<!-- Wrapper tag for the generic object data. -->
<!ELEMENT object-data (install)>

<!-- This tag is required in the hierarchy
     version if optionally used by Notes -->
<!ELEMENT install (installfeature)+>
<!ATTLIST install version CDATA #IMPLIED>

<!-- This tag will have the following attributes:
        id     
               The id of the install feature.
               
        name (optional) 
              The name of the install feature.  The value of this attribute can be contributed 
              to an offering installer's UI when the show attribute is set to true and the 
              offering installer has ShowCustomFeatures property set to true.
               
        description (optional)
              The description of the install feature.  The value of this attribute can be contributed 
              to an offering installer's UI when the show attribute is set to true and the 
              offering installer has ShowCustomFeatures property set to true.
              
        show (optional)
              Used to indicate whether the installfeature should be shown in the offering installer
              feature panel.  Default value of this attribute is false.
               
        restartPersonality (optional) (DEPRECATED)
              Used to indicate the personality with which the platform should be restarted once 
              the provisioning of all the features has succeeded.
               
        required (optional) 
              Denotes whether this is a required installfeature or can be optionally installed.  
              Default value is false.
              
        version 
              Indicates the version of the installfeature to be provisioned.  
              Example format of the version string is 6.2.1.20090519-0748.  Default value is 1.0.0
               
        action 
              Used to indicate whether to install or uninstall an installfeature.  Default value is install.
              

        mergeaction (optional) 
	            Selected values are "add" and "remove"
	            
              During upgrade scenarios, a pre-existing install manifest will be merged with a new manifest, 
              according to the following rules.  
			   
              The mergeaction attribute is processed only from the new install manifest, 
              and is ignored in the old manifest.

                  add
                        forces an installfeature specified in the new install manifest file 
                        to be retained in the merged result.  
                         
                  remove
                        forces an installfeature specified in the new install manifest file 
                        to be removed from the merged result.
			
              If the mergeaction attribute is not present, then the features within the installfeature are processed 
              against the install feature of the identical id
-->

<!ELEMENT installfeature (requirements)>
<!ATTLIST installfeature 
	id CDATA #REQUIRED
	name CDATA #IMPLIED
	description CDATA #IMPLIED
  	show CDATA #IMPLIED
	restartPersonality CDATA #IMPLIED (DEPRECATED)
	required CDATA #IMPLIED
  	default CDATA #IMPLIED (DEPRECATED)
  	version CDATA #REQUIRED
  	action CDATA (install|uninstall) "install"
	mergeaction (add|remove) #IMPLIED>
	

<!-- The requirements tag denotes a requirements block which will 
     contribute a list of required features to be used by the 
     provisioning system. -->
<!ELEMENT requirements (feature)*>

<!-- This tag denotes a feature that is required by the platform for 
     a given deployment.
     
     This tag will have the following attributes:

        id
              The id of the feature to be provisioned
	
        version
              The version of the feature to be provisioned
	
        match(optional) 
              Used to indicate the desired match rule. 
               
              According to the manifest definition in the Eclipse help, the match rules are as follows: 

                  perfect 
                        Dependent plug-in version must match exactly the specified version. 
                        If "patch" is "true", "perfect" is assumed and other values cannot be set. 
                         
                  equivalent 
                        Dependent plug-in version must be at least at the version specified, or at a higher 
                        service level (major and minor version levels must equal the specified version). 
                         
                  compatible 
                        Dependent plug-in version must be at least at the version specified, or at a higher 
                        service level or minor level (major version level must equal the specified version). 
                          
                  greaterOrEqual 
                        Dependent plug-in version must be at least at the version specified, or at a higher 
                        service, minor or major level. 

              Match attributes are specified in the install manifest and in the feature itself.  

              The match attributes specified inside the feature apply to the feature requirements and plugin 
              requirements for the feature.  These are processed by the update manager to determine whether 
              all requirements for the feature have been satisfied.

              The match attributes specified in the install manifest are used as a predetermination for 
              installing and uninstalling the feature. If not specified, the default is perfect. When uninstalling 
              provisioning will process all the versions of the specified feature id. All the versions that fall 
              within the match attribute range will be uninstalled.

        url
              The URL to the update site where the feature can be found.  An update site is any valid file URL 
              which contains a site manifest file, a features folder, and a plugins folder.
                  
                  Example: url=http://www.myupdatehost.com/updateSite
                  Example: url=file://C:/Program Files/application/updateSite

              "${installer.root}" is an optional token that is replaced by the EXPEDITOR assembly when the manifest is 
              processed prior to initial provisioning.  The parameter is replaced with the directory from which the 
              installer has launched, and can therefore only be used in conjunction with a relative update site path.
                  
                  Example: "${installer.root}" = "file://D:/ProductCD/install/"
                  url="${installer.root}/../updates" translates to file://D:/ProductCD/../updates/
		
        size(optional)
              The installed size (in kilobytes) of the feature.  It is used by the install application to calculate 
              the total size of the installed product.  The size attribute is currently used only by the install 
              application.
               
        download-size(optional)
               The download size (in kilobytes) of the feature.  It is used by the install application to calculate 
               the amount of temporary space required during the install processing. The download-size attribute is 
               currently used only by the install application.
               
        shared(optional)
               If set to true, the feature will be installed into the shared site (if no other feature version or 
               affinity is satisfied).  If false, the feature will be installed into the user site 
               (if no other feature version or affinity is satisfied).  Default value is true.
               
        config(optional) (DEPRECATED)
               Denotes the configuration(s) into which this feature will be installed. Available values are user 
               (the feature will install into the user's configuration) or multiuser (the feature will be installed 
               into the multiuser service configuration). If a feature is to be installed into multiple configurations, 
               configurations should be separated by commas (for example, user,multiuser). Default value is user. 
	
        remove(optional) (DEPRECATED)
               Remove this feature.  This is deprecated and is equivalent to specifying action="uninstall".  
               This attribute is ignored if the action attribute is specified.
	
    	  action(optional)
  	            Selected values are as follows.
  	           
                  install 
                         Install and configure the feature (default)
                         
                  installonly 
                         Install, but do not configure the feature
				         
                  deferredenable 
                         Install, but defer the enablement (configuration) of the feature until a platform restart 
                         occurs and a user interface is available.
                         
                  enable
                         Enable a feature that is currently installed
                         
                  disable
                         Disable a feature that is currently installed
                         
                  uninstall 
                         Disable, then uninstall a feature
                         
                  ignore 
                         Perform no actions on this feature
				
        mergeaction(optional)
              Selected values are "add" and "remove"
	
              During upgrade scenarios, a pre-existing install manifest will be merged with a new manifest, 
              according to the following rules.  
               
              The mergeaction attribute is processed only from the new install manifest, 
              and is ignored in the old manifest.

                  add
                         forces a feature specified in the new install manifest file to be retained in the 
                         merged result.  
                         
                  remove
                         forces a feature specified in the new install manifest file to be removed from the 
                         merged result.

              If the feature is present in the old manifest, and the feature is present in the new manifest
               
                  mergeaction attribute not specified
                         The feature is retained with the attributes defined in the new manifest
                         
                  mergeaction = "add"
                         new feature is retained completely
                         
                  mergeaction = "remove"
                         feature is removed
				
              If the installfeature is present in the old manifest, and does not exist in the new manifest, 
              it will be retained completely
			
              If the installfeature is not present in the old manifest, it will only exist in the result 
              if mergeaction="add" is specified
 
     The following attributes are only vailable for installfeatures that are part of the initial product 
     install.
     
        name (optional) 
              The name of the installfeature. Available only for installfeatures that are part 
              of the initial product install. The value of this attribute can be contributed to an 
              offering installer's UI when the show attribute is set to true and the offering installer has 
              ShowCustomFeatures property set to true.
 
        description (optional)
              The description of the installfeature. Available only for installfeatures that are part 
              of the initial product install. The value of this attribute can be contributed to an 
              offering installer's UI when the show attribute is set to true and the offering installer has 
              ShowCustomFeatures property set to true.
 
        show (optional)
              Used to indicate whether the installfeature should be shown in the offering installer
              feature panel. Available only for installfeatures that are part of the initial product install.
              Default value of this attribute is false.
-->
 
<!ELEMENT feature EMPTY>
<!ATTLIST feature 
	id CDATA #REQUIRED
  	version CDATA #REQUIRED
	match (perfect|compatible|equivalent|greaterOrEqual) #IMPLIED
	url CDATA #REQUIRED
  	size CDATA #IMPLIED
	download-size CDATA #IMPLIED
  	shared CDATA #IMPLIED
 	remove CDATA "true"
	config CDATA #IMPLIED
	action (install|installonly|deferredenable|enable|disable|uninstall|ignore) "install"
  	mergeaction (add|remove) #IMPLIED >
	
Note: When a new feature is installed that is not a part of the existing provisioning manifest, the feature will be added to the provisioning manifest automatically. See Deploying features to the platform for information on how to deploy features. A new installfeature element will be added to the provisioning manifest. The example shows the installfeature element that is automatically added when a new feature is installed but is not part of the original installation:
<installfeature id="Admin.added.requests" required="true">
<requirements>
<feature action="install" id="com.ibm.rcp.aaf.feature" match="compatible" 
shared="true" version="1.0.1"/>
</requirements>
</installfeature>

Using this provisioning manifest structure, any number of features can be specified, and each feature can come from different originating update sites. Each feature can provide a match rule for determining if it should be installed or updated. The feature's destination site and configuration can also be specified (using the shared and config attributes), and provided sizes will be added to the size of the install reported by the installer so that an accurate total platform size (including installed and provisioned files) can be presented to the user.

Note: When the platform is upgraded, it is important to realize the upgrade provisioning manifest does not contain the new installfeature element. Before the upgrade is performed, the upgrade provisoning manifest should be modified to include the new installfeature element. When the platform is upgraded, the new and old provisoning manifests are merged. See Understanding the merge processing for the provisioning manifest for more information.
Examples
  1. Installation of the Order Entry sample located on an Lotus Expeditor Client CD-ROM:
    Note: The feature version shown here may differ from the version shipped with the product.
    <ibm-portal-composite>
         <domain-object name="com.ibm.rcp.installmanifest">
             <object-data>
                  <install>
                        <installfeature>
                              <requirements>
                                  <feature id="com.ibm.rcp.samples.orderentry.feature" version="6.1.0.0-20060815" action="install" size="25"/>
                              </requirements>
                        </installfeature>
                  </install>
             </object-data>
         </domain-object>
    </ibm-portal-composite>
  2. Installation of features located on two different HTTP server sites:
    <ibm-portal-composite>
         <domain-object name="com.ibm.rcp.installmanifest">
             <object-data>
                  <install>
                        <installfeature>
                              <requirements>
                                   <feature id="com.aaa.feature1" version="1.0.0" url="http://company1.com/updates" action="install" size="900"/>
                                   <feature id="com.aaa.feature2" version="5.6.0" url="http://company1.com/updates" action="install" size="300"/>
                                   <feature id="com.bbb.feature1" version="1.2.0" url="http://company2.com/site" action="install" size="50" shared="false"/>
                                   <feature id="com.bbb.feature2" version="3.0.5" url="http://company2.com/site" action="install" size="2100" match="equivalent"/>
                              </requirements>
                        </installfeature>
                  </install>
             </object-data>
         </domain-object>
    </ibm-portal-composite>

Installing additional languages content

The IBM Lotus Expeditor runtimes have been translated for Group 1, Group 2, and Group 3 languages.

The Group 1 languages include:
  • Chinese (simplified)
  • Chinese (traditional)
  • Japanese
  • Korean
  • French
  • German
  • Italian
  • Spanish
  • Portuguese (Brazilian)
The Group 2 languages include:
  • Arabic
  • Czech
  • Danish
  • Dutch
  • Finnish
  • Greek
  • Hebrew
  • Hungarian
  • Norwegian
  • Polish
  • Portuguese
  • Russian
  • Swedish
  • Turkish
Note: When installing a platform on Linux, Hebrew and Arabic locale specific fragments are not installed on Linux. Installation of the Hebrew and Arabic locales on Linux and launching with those locales is also not supported.
The Group 3 languages include:
  • Thai
  • Catalan
  • Romanian
  • Slovak
  • Slovenian
  • Ukrainian

U.S. English is packaged within all IBM Lotus Expeditor features and plug-ins and is available by default.

During the initial installation of the platform, only the national language features that contain the current locale are installed and enabled.

Note: If you are using Windows Vista, be sure to review Administering the platform on Windows Vista prior to installing the language features.

To enable locale specific content, additional national language features must be installed. The platform must be started in the desired locale to install and enable the national language features for that locale. This can be accomplished by switching the system to the appropriate locale before starting IBM Lotus Expeditor. It can also be accomplished by starting IBM Lotus Expeditor with a –nl command argument. For example, to start the platform in French, enter <install dir>/rcp/rcplauncher.exe –nl fr.

When IBM Lotus Expeditor has started, install the appropriate group of languages. If you need to install another group, you must shutdown IBM Lotus Expeditor and change locale using one of the above methods.

If National Language Features are installed but do not match the current platform locale, then the features will not be enabled.

When viewed in the Application > Application Management dialog, the list of installed and enabled features is filtered based upon the locale. For example, if both the Group 1 and Group 2 language features are installed, and you have started the platform using the Finnish locale, then the Application Management dialog will only show the Group 2 language features, and will not show the Group 1 language features.

When supporting a language other than English on an system with multiple users, you, as the administrator, must install the correct groups of languages. If space permits, install all language groups. If you only need French then install only the Group 1 language translation. There are restrictions on how this can be done. To install Group 1 languages, you must start the platform in a language that Group 1 supports.

The provisioning system will automatically enable a single locale group per user and does not support automatic switching between locale groups. In an environment with multiple users, each user can have a different locale group as long as the administrator has installed all of the required NL packs before users launch IBM Lotus Expeditor and provision their own workspaces.

Upgrading features on the platform

Choose from various mechanisms for upgrading features on the platform.

You can upgrade the features existing on the platform using these mechanisms:
  • Use the Update Manager user interface (File > Application > Install > Search for new features to install) to manually install new versions of features.
  • Distribute new feature versions through the Composite Application Infrastructure (CAI) and provisioning from the server.
  • Distribute new feature versions through the Client Management server.
  • Use an alternative management system to provide a provisioning manifest and call the ProvisioningApplication to install new updates.
  • Configure the platform to use an automatically scheduled Scan for Updates.

The Scan for Updates mechanism scans the set of update sites defined by features on the platform and the policy, as filtered by the white list processing. You can set preferences so that it looks for updates to existing features on the platform, searches for only new features to install, or searches for both new features and updates to existing features. The set of features located will be proposed as updates to the platform. To configure the platform to scan for updates automatically, use the Automatic Updates preferences page.

For any of the processes outlined above, the updated features will be installed and enabled in the current configuration. According to the setting for the com.ibm.rcp.provisioning/feature.history.size preference, once a feature with an updated version has been installed and enabled, previous versions can be removed.

Unless the platform provisioning manifest (defined in the rcplauncher.properties and defaulting to the rcp\deploy\install.xml file) is updated to reflect these feature updates, new workspace creation will attempt to use the previously defined feature versions. If these previous feature versions are no longer installed, new workspace creation might fail.

The mergemanifest command of the platform global install handler provides a mechanism for automatically updating the provisioning manifest to stay consistent with the installed features and provides a powerful mechanism for updating the platform. Using the mergemanifest reduces the focus from updating several features, to focusing on the update of one feature, which will then drive the remainder of the feature updates. The following scenario illustrates how the mergemanifest command for the platform global install handler can be used:
  1. Define a feature called CompanyApplications and give it a version 1.0.0. This feature does not need to contain any plug-ins. Distribute the CompanyApplications feature on an update site.
  2. Create an update policy XML file on a Web or shared file server that refers all scan for updates to the update site containing only the CompanyApplications feature.
  3. Customize the initial platform installation to include the CompanyApplications feature.
  4. Customize the plugin_customization.ini file to include the update policy URL preference and configure the platforms to automatically scan for updates.
  5. Install the platform, which will now install the CompanyApplications feature. The provisioning manifest will contain the CompanyApplications feature, and, if a new workspace is required to be created, the CompanyApplications feature will be in all platforms.
When there are updates to be applied to the platform, perform the following steps:
  1. Create a provisioning manifest file that references the new or updated features that need to be distributed to the clients and containing the appropriate mergeaction tags. Include the provisioning manifest file in the feature.
  2. Create a handler.properties file to contain the mergemanifest command referencing the provisioning manifest included in the feature
  3. Update the CompanyApplications feature to a new version, such as 1.0.1.
  4. Distribute the other new or updated features to a second update site. (By using a second update site, the scan for updates will only identify the CompanyApplications feature to be updated, reducing the confusion in the number of features to be distributed).
  5. Distribute the updated CompanyApplications feature to the update site referenced by the update policy.
As the clients perform their scheduled scan for updates, they will detect the new CompanyApplications feature and propose the installation of the feature. When the feature is installed and enabled, the mergemanifest command will be processed, which results in an update to the provisioning manifest and an update to the provisioning.manifest.version property in the rcplauncher.properties file. On restart of the platform, the platform launcher will detect the difference in the provisioning.manifest.version from its previous setting (compared to the value in the rcpinstall.properties file) and process the contents of the provisioning manifest file. Since new or updated features were merged into the provisioning manifest by the mergemanifest command, the ProvisioningApplication will process those changes, installing or enabling the new or updated features for each workspace.

While this scenario uses the scan for updates, the same basic process can be repeated by distributing the CompanyApplications feature in other ways, such as through the Client Management server or through the Portal server.

The Lotus Expeditor platform branding feature contains a mergemanifest command for its install handler, referring to a install.xml contained within the branding feature. If the Lotus Expeditor branding feature is installed from an update site, it will merge the contents of the install.xml with the provisioning manifest on the platform.

As the Lotus Expeditor provides future platform upgrades by updating the branding feature on the platform, other updates will automatically be installed using the provisioning manifest.

Uninstalling features on the platform

When new versions of existing features are installed on the platform, the previous versions are immediately disabled.

Depending on the preference setting for com.ibm.rcp.provisioning.feature.history.size, the previous versions may also be physically removed from the system.

Features that were installed into one workspace cannot be uninstalled from a different workspace. For example, when you initially launch Lotus Expeditor using the default workspace, a set of features are installed and provisioned for you. If you later launch with a different workspace using the rcpData launch option, the features that were installed into the default workspace cannot be uninstalled from the new workspace. If you attempt to uninstall these features, they will not be uninstalled and errors will be written to the error log.

Contributing to the deferred actions list

The provisioning system maintains a set of requests that are deferred for processing until the platform restarts.

Physical uninstall of features is deferred until the platform restarts. Actions can only be added to the list as an indirect result of requesting the uninstall of a feature.

Deferred actions are processed through the org.eclipse.ui.startup extension point. Therefore, the deferred actions will run only when the workbench is available, which is after the user authentication has occurred. The Provisioning Application will synchronously process deferred actions prior to beginning the requested operations.

Deploying applications through Web Start

This section describes how to export and deploy a Client Services RCP application through the Java Web Start mechanism.

The Java Web Start mechanism supports the deployment of Java applications from a Web server, onto a client. The Client Services Web Start tools support the packaging of RCP applications for subsequent deployment through the Web Start mechanism. These applications run against an installed IBM Lotus Expeditor runtime on the client. Each application is launched as a self-contained RCP application running in its own VM. The application is not installed into the IBM Lotus Expeditor platform. Instead, it can reference required features from the IBM Lotus Expeditor platform that it needs. When the application ends, it may be cached on the client for future invocations, or may be removed if the cache is full. In this respect, the application is transient, like Java applications that are run through Web Start.

Further information on Java Web Start can be found in the documentation provided with Java J2SE 1.5.

Supported applications and environments

All application types that can be run on the Lotus Expeditor Client can also be deployed and run through Web Start. All that is required is that the application be packaged in one or more features, and that a product configuration be created for it.

Java Web Start requires J2SE support on the client. For this reason, only the J2SE JRE that is delivered through the DRE is supported as a Java runtime. The DesktopEE and DeviceEE JREs are not supported.

Supported operating system platforms include:
  • Microsoft Windows XP Professional Service Pack 1 and 2
  • Microsoft Windows XP Home Edition Service Pack 1 and 2
  • Microsoft Windows Vista
  • Red Hat EL 4.0 WS with GTK support - Update 4
  • Red Hat EL 5.0 WS with GTK support
  • SUSE Linux Enterprise Desktop 10

Lotus Expeditor Runtimes DRE feature must be installed on the client. For more information, see Installing Web Start support on the client.

Differences from the Eclipse Web Start support

This section describes the differences between the Client Services Web Start support and the Eclipse Web Start support.

The Client Services Web Start tools differ from the Eclipse tools in the following areas:
  • The Eclipse Web Start tools package up an RCP application with all of the features referenced by the application. In essence, this provides a standalone application. The Client Services tools assume the existence of an installed Lotus Expeditor runtime on the client machine. This allows the RCP application’s packaging to only contain the application unique features. The benefits of this are two-fold:
    • The application to be downloaded from the server is potentially much smaller, leading to a faster download.
    • The Lotus Expeditor runtime can be updated independently from the application, avoiding the need to re-build and re-deploy all applications in order to take advantage of Lotus Expeditor feature updates.
  • The Lotus Expeditor tools understand the Lotus Expeditor runtime, and can properly set up the application’s Lotus Expeditor launch environment.
  • Only the common launch jar that is provided with the Client Services Web Start support needs to be signed. This can be done once by the administrator since this jar is common to all Client Services Web Start applications.

Multi-user support

A Web Start-deployed application references the shared features from a multi-user installation.

Web Start does not reference a particular user’s Lotus Expeditor configuration.

Structure of a Client Services Web Start application

Expeditor Deployers: Structure of a Client Services Web Start application

The RCP JNLP application contains the following resources:
Common launch component
Contains common logic required to setup and launch the RCP application. It is contained in jar file com.ibm.rcp.jnlp.launch_1.0.0.jar.
Top level JNLP descriptor
Specifies the common launch component and the application extension.
Application extension JNLP descriptor
Specifies the application jar.
Application jar
Contains the RCP application itself in the form of an Eclipse install directory.

Splitting the JNLP description into a top level jnlp and an extension jnlp allows full access security to be specified at the top level for the common launch component, without requiring the resources referenced in the application extension to be signed. Only the common launch component com.ibm.rcp.jnlp.launch_1.0.0.jar needs to be signed, and a single instance can be shared by all of the RCP applications.

Developing a Web Start application

This section describes the basics involved in developing a Web Start application.

All Client Services application types can be deployed through Web Start. The application itself is a Client Services application, and as such, is developed using the existing tools available in the Lotus Expeditor Toolkit. It can be tested using the Client Services launch or Client Services server support.

The Client Services Web Start export wizard assembles the necessary metadata and packages the application in a form suitable for Web Start deployment. See Exporting the Web Start application for more information on this process.

Exporting the Web Start application

This section describes how to export the Web Start application.

The following prerequisites must be met before an application can be exported for Web Start:
  • The application must be structured as one or more features.
  • A product configuration must be created which defines the features that make up the application along with application launch details.
Creating and editing a product configuration follows the same steps as used when exporting a client runtime image. See ../com.ibm.rcp.tools.doc.appdev/pb_creatingawedclientplatform.html for further information.
When one or more features have been created for the application and a product configuration has been created, the application can be exported using the following steps:
  1. Select File > Export.
  2. From the Client Services folder, select Client Services Web Start, and click Next.
  3. Select the product configuration for the application.
  4. Specify the destination directory for the export, and optionally change the application jar name.
  5. Optionally, provide a version specification for the target runtime. Blank (default) indicates any version.
  6. Indicate whether to export the common launch component. This component is required to run the application through Web Start, but a single instance of this can be deployed to the Web server and shared by multiple applications.
  7. Optionally, you can have the export wizard sign the common launch component. The common launch component must be signed, but you can opt to sign it after it is exported using a utility such as the Java jarsigner.
  8. You can select Finish to export the application using the default JNLP options, or select Next to bring up the JNLP options page, followed by the Properties page.
Note: The exported Web Start application will be configured to use a J2SE environment matching the workspace JDK Compiler compliance level.

The default JNLP URL settings used by the export wizard will reference the application as exported to the destination directory. If you use these defaults, you can run your application directly from that directory by browsing to the main jnlp file in the directory. On Windows, you can also double-click on the jnlp file to run the application. You must have Web Start properly installed on your development machine for this to work. See Installing Web Start support on the client.

See Structure of a Client Services Web Start application for further information on the resources that are exported to the target directory. See Deploying the application on the server for information on how to deploy these resources on a web server.

JNLP options

The following table lists the JNLP options that can be specified during export. A default value of <blank> also implies that the option is not written to the JNLP file.
Table 35. JNLP options
JNLP option Description Default value
Application codebase URL of location containing the application jar Export destination
Common launch component URL URL of the common launch component location Location of the common launch component in the export destination directory
Title Application title Product configuration name
Vendor Application vendor <blank>
Description Application description <blank>
Offline allowed If true, Web Start is allowed to run a cached version of the application if the client is not connected to the network true
Homepage URL to a homepage containing application information <blank>
Icon URL to an application icon <blank>

Properties

The Web Start Export wizard Properties page allows you to specify name and value pair properties to pass to the application. These properties are passed as Java System properties, and can be accessed by the application through the System.getProperty and System.getProperties Java APIs.

Installing Web Start support on the client

This section describes how to install Web Start support on the client.

Installing Web Start support for Client Services applications on the client consists of the following three steps:
  1. Configure the Lotus Expeditor Client for Web Start support.
  2. Configure the browser for Web Start support.
  3. Configure the client for Web Start support.
Note: It is important to apply these steps whenever the Lotus Expeditor Client is re-installed or updated.

Configuring the Lotus Expeditor Client

To properly configure Lotus Expeditor Client for Web Start support, perform the following steps:
  1. Install the Lotus Expeditor Client.
  2. Install the Lotus Expeditor Runtimes DRE feature. The DRE provides J2SE support required for running applications through Web Start.
  3. Copy the rcpbootcp.jar to the J2SE lib/ext directory.
    1. The rcpbootcp.jar can be found in the com.ibm.rcp.base plug-in at: <Expeditor_Install>/rcp/eclipse/plugins/com.ibm.rcp.base_X.X.X
    2. Copy rcpbootcp.jar to the following directory:
      On Windows:
      <Expeditor_Install>/rcp/eclipse/plugins/com.ibm.rcp.j2se.win32.x86_X.X.X.<version>/jre/lib/ext
      On Linux:
      <Expeditor_Install>/rcp/eclipse/plugins/com.ibm.rcp.j2se.linux.x86_X.X.X.<version>/jre/lib/ext
Depending on the IBM Lotus Expeditor capabilities required by your Web Start applications, additional updates to the environment might be needed on Linux:
  • To support the Expeditor managed browser, set MOZILLA_FIVE_HOME to the appropriate Mozilla browser directory in /usr/lib. See Software Requirements - Lotus Expeditor 6.2 Client for Desktop for information on locating this directory on your system. For example:
    export MOZILLA_FIVE_HOME=/usr/lib/firefox-X.X.X.X 
  • If applications will be using DB2e, add the following location to the LD_LIBRARY_PATH environment variable:
    <Expeditor>/rcp/eclipse/plugins/com.ibm.db2e.linux.x86_<version>/os/linux/x86
  • If applications will be using ISync, add the following location to the LD_LIBRARY_PATH environment variable:
    <Expeditor>/rcp/eclipse/plugins/com.ibm.mobileservices.isync.linux.x86_<version>/os/linux/x86 
In the above paths, <Expeditor> is the install location of the Expeditor runtime and <version> is the version of the plug-in.

Configuring the browser

To configure the browser, you must install the Java 1.5 JRE on the client using the Java install program. The installation program for the JRE contains the logic to update the system and associate Java and Web Start with the browsers.

Once the Java JRE has been installed, configure Web Start to reference the Expeditor platform J2SE as follows:
  1. Open the Java Control Panel. On Windows, this can be found in the Windows Control Panel. On Linux, run application ControlPanel, found in jre/bin of the Java home directory.
  2. On the Java tab, click View for the Java Application Runtime Settings.

    The JNLP Runtime Settings page is displayed.

  3. On the User tab, click the Find button and browse to the Lotus Expeditor Runtimes DRE install location. This will be at the following location:
    On Windows:
    /rcp/eclipse/plugins/com.ibm.rcp.j2se.win32.x86_X.X.X.<version>
    On Linux:
    /rcp/eclipse/plugins/com.ibm.rcp.j2se.linux.x86_X.X.X.<version>
  4. Continue clicking Next until finished.
  5. Uncheck all other JREs listed on the JNLP Runtime Settings page except for the Expeditor platform DRE.
  6. Click OK.

Configuring the client

To configure the Client Services Web Start support, create a configuration file that specifies where the IBM Lotus Expeditor platform is located on the client. This configuration file allows multiple IBM Lotus Expeditor-based platforms to be supported on a client machine. The configuration is an xml file with root element <webstart> and one or more <platform> elements. Each <platform> element specifies the location and optional version of a IBM Lotus Expeditor platform on the client. The following is an example of a simple configuration specifying a single IBM Lotus Expeditor platform:
<webstart>
      <platform
             type="expeditor"
             version="6.2.0"
             location="C:/IBM/Lotus/Expeditor"/>
</webstart>
Set the environment variable RCP_JNLP_LAUNCH_CONFIG to the location of this configuration file.

Deploying the application on the server

This section describes the steps involved in deploying a Client Services Web Start application on the Web server.

Perform the following steps to deploy a Client Services Web Start application on a web server:
  1. Ensure that the Web server maps .jnlp files to mime type application/x-java-jnlp-file
  2. Sign the common launch jar com.ibm.rcp.jnlp.launch_1.0.0.jar
  3. Add the common launch jar as a resource to the Web server. This can either be in a common location referenced by all applications, or it can be copied into each application's codebase directory. This decision affects the contents of the application's JNLP file. In particular, the resource must have its href attribute properly set to the Common Launch component's location.
  4. Install the application jar file and JNLP files produced by the Web Start export to the Web server under the codebase specified in their JNLP files (or update the JNLP file's codebase attribute to correspond to where you are placing them).

Running an application through Web Start

This section describes how to run an application through Web Start.

To run an application through Web Start, use a Web Start-enabled browser to browse to the jnlp file of the application to be run.

Internationalization considerations

Considerations for using the characters that are not part of the ASCII character set.

  • A Web Start application can be deployed locally on a client machine's file system, rather than on a Web server. When this is done, the application's codebase must only contain ASCII characters or characters that are part of the client machine's current language.
  • The Client Services Web Start export wizard cannot export to a file location containing characters that are not ASCII or not a part of the development machine's current language.
  • The Client Services Web Start export wizard will automatically replace non-ASCII characters in an http: URL with their corresponding %xx URL encoding representation. This applies to the codebase and common launch component URL fields.

Managing the client runtime

The following sections provide general task information necessary to manage the client runtimes. Use the tasks specified in these sections as general patterns for managing the client runtimes.

You will need to refer to Configuring the platform and Extending the platform for the details to be supplied when completing each task.

Managing with a Client Management server

Lotus Expeditor Server provides client management services to install applications, and manage applications and runtimes.

The Enterprise Management Agent enables you to connect to a Expeditor Server. The Expeditor Server contains the Client Management server component, which provides basic platform management of the client, along with additional features, such as database synchronization (DB2e) and a messaging gateway (MQe).

This section includes the following main topics:

Introducing Client Management services

Client Management services provides a flexible solution for robust management of clients, regardless of connection types or client capabilities. Network connected or offline clients can be targeted for management.

For Client Management services, clients include any of the devices and computers supported by Lotus Expeditor for Desktop and Devices clients. This can include devices and computers running other products that include the Lotus Expeditor client.

Client Management Services is used to enroll devices into a database and perform many tasks for managing devices, such as:
  • Device configuration: Setting client parameters for software.
  • Inventory collection: Collecting software information about the client.
  • Software distribution: Distributing, installing, and removing software for the client.
  • Additional tasks are also implemented on particular clients, depending on client capabilities, such as:

Client Management Services provides a graphical user interface (GUI) for client management. The Client Management administration interface is integrated with the Integrated Solutions Console provided by WebSphere Application Server. Administrators typically use the Client Management administration interface. Client Management also provides application programming interfaces to manage clients. For more information, see Developing Client Management applications.

For Client Management Services, management actions are called tasks. Tasks can be applied to or targeted to a single client, or a group of clients. Groups of clients are defined by a list of clients, or by characterizing the group, such as by the client owner, owner group, some attributes of the client inventory, or a combination of characteristics. Groups of clients are defined to Client Management Services as filters.

Tasks are targeted to a client and the task is run when the client connects to the Client Management server. The server maintains a history of task status for all tasks and all clients. Client Management Services can also notify the client that a task is waiting for the client.

Client Management Services requires an agent on the managed client. The agent is supplied with the Lotus Expeditor client.

The client agents communicates with the Client Management server using HTTP or HTTPS. The protocol running on top of HTTP is a standard protocol called the OMA DM protocol used with OSGi devices. With HTTP and HTTPS communications between devices and Device Manager, requests and responses can pass through various network elements, such as firewalls. OMA DM is a specification created by the Open Mobile Alliance (OMA) organization for device management of wireless devices.

Launching the client management services administration interface

The Lotus Expeditor client management module provides administrator access to functions for managing Expeditor based clients.

The Expeditor Client Management module installs in the WebSphere Integrated Solutions Console as part of the client management server installation. See Installing Lotus Expeditor Server for information on installing the Client Management server. For information on accessing the WebSphere Integrated Solutions Console, refer to the WebSphere Application Server information center.

Launching the management console in an unmanaged Portal server environment

Portal Server, when installed into a WebSphere Application Server 6.1 environment, configures a profile with the WebSphere Integrated Solutions Console on both server1 and the WebSphere_Portal application server. The Client Management Services Administration interface is functional only from the WebSphere Integrated Solutions Console running on server1. This applies to an unmanaged environment only.

Client management services limitations

Keep these limitations in mind when using Client Management services.

Limitations are as follows:
  • Client Management Services can only be used to manage Expeditor 6.1 and above clients.
  • Managing Expeditor 6.1 or 6.1.1 clients with multi-user support enabled is not supported. Expeditor 6.1.2 and above with multi-user support enabled is supported.
  • The following functions are only supported with Expeditor 6.2 and above clients:
    • Run IBM Support Assistant task
    • Retrieve File task
    • Client Restart task (Computer restart is supported on Expeditor 6.1.2 and above)
  • Known issues when using an Oracle database:
    • The sorting for the Client Management data in the administrative console may not be correct.

    • Some double byte character Client Management data in the administrative console is not displayed correctly.

  • Known issues when using the Client Management GUI:
    • The order of day and month for the "Day of the year" when scheduling yearly tasks is incorrect for non-English locales.

Managing clients

Use the administrative console to manage registered clients. Clients register with the Client Management server the first time they connect.

The Clients view in the console displays the clients that have registered with the client management server. To view this administrative console page, click Expeditor Client Management > Clients. The Clients view shows the user ID used to register the client, the unique device ID, an optional description, and the last time the client connected. Selecting the device ID displays the client details view, which displays additional information about the client, allows you to edit the description, and provides links to the client's inventory and task history.

To filter or search views, see Filtering display information.

Table column Description
User ID Specifies the ID used to register the client.
Client ID Specifies the unique client ID. Click to display details about the client. The Client Details view allows you to edit the client description, and provides links to client options and task history.
Description Specifies an optional client description.
Last Connection Specifies the last time that the client connected to the server. For example: 07/16/08 9:50:19 AM