Creating collaborative components for IBM Lotus Expeditor Property Broker

Get an introduction to the IBM Lotus Expeditor Property Broker and learn how you can create a component that contributes to the declarative communication offered by the broker. We show you how to wire components declaratively using extension points, the IBM WebSphere Portal Wiring Tool, and the Property Broker APIs.


Bob Balfe (, Senior Software Engineer, IBM, Software Group

Bob Balfe is a Senior Software Engineer on the Lotus Expeditor team. He is the architect for the Portal Administered client and is responsible for a consistent programming model between WebSphere Portal and the Expeditor client. Bob was previously on the Lotus Notes and Domino core development team, serving as the team leader for the Automation Development team. His more than 17 years of software engineering experience include roles as an IT professional and a commercial software developer.

19 December 2006

Also available in Japanese

This article introduces you to the IBM Lotus Expeditor Property Broker. We show how you can create a component and how it can contribute to the declarative communication the Property Broker offers. The primary task of the Property Broker is to provide communication between completely decoupled components. These components can be any defined Java objects that properly register themselves with the Property Broker as identifiable properties or actions. You can then wire together the components declaratively using extension points, the IBM WebSphere Portal Wiring Tool, or the Property Broker APIs.

This article is intended for application developers with familiarity with Lotus Expeditor (formerly IBM WebSphere Everyplace Deployment). It assumes that you understand terminology such as action, property, and so on.

Comparing IBM Lotus Expeditor and IBM WebSphere Portal Property Brokers

The Lotus Expeditor Property Broker closely matches the capabilities of the WebSphere Portal Property Broker. When used in the context of composite applications, the XML from WebSphere Portal drives the wiring and communication of the decoupled components. The composite application infrastructure (CAI) takes care of registration and activation of wires. In the case of a component developed for use in CAI, your main concerns are publishing property changes and acting on property changes. If you create components outside of the CAI, then you need to account for wire registration, activation, and deactivation.

Given the complexities of a multi-windowed and multi-tasking environment offered by the Eclipse platform and Lotus Expeditor, the biggest differentiating factor of the client-side Property Broker from its sister WebSphere Portal Broker is its ability to extend additional action frameworks. WebSphere Portal allows communication between different kinds of portlets; however, the client Property Broker allows you to create new extensions to the broker using an Eclipse extension point. Lotus Expeditor ships with three action handler extensions, all of which can be used for compatibility with existing code. The three out-of-the-box action handlers that are shipped with Lotus Expeditor are the:

  • Eclipse Core Commands
  • Standard Widget Toolkit (SWT)-based actions
  • Abstract Windows Toolkit (AWT) components

Lastly, the Property Broker is a different type of messaging system because actions can be called with input property changes and also provide any number of output property changes. This in effect can have a chain reaction of property changes. Figure 1 shows a sample execution flow.

Figure 1. Sample execution flow
Sample execution flow

Architecting your components properly

To have good encapsulation and proper decoupling, your component should fit a true component model. This means you should define your components to be used in contexts not yet thought of and should apply proper componentization principles to your design.

Here are some design tips to consider:

  1. Declare your views and actions in the same package for clarity. This way, even though the classes are separate in nature, they are tied under the same package structure. One way is to use a sub-package under a view named Actions where all your action classes reside.
  2. To keep things simple, you should provide one Web Services Description Library (WSDL) file for each action. Although the Property Broker allows multiple actions to be defined in a single WSDL, this is not recommended unless your action is acting as a generic container for other actions.
  3. Using the Property Broker in conjunction with CAI is the easiest path. If you intend to use the Property Broker and actions outside this framework, you may need to provide code that properly enables and disables actions and wires. You must also provide the code that registers the wires; when you use composite application XML from WebSphere Portal, the wires are defined in the XML.
  4. Be aware that property namespaces have a limitation in which a property must be unique within that namespace. You cannot have a property named URL in one component and a property named URL in another component that shares the same namespace. You may need to preface the property name with a distinguisher identifiable by the view or action for uniqueness.
  5. If your action is to update a UI component, then ensure you are in the UI thread when making the call to update a label or UI control. The templates assume this and provide the code for you.

Sample application

The sample application, which demonstrates two decoupled components, shows at a basic level how two components are created and then wired together using WebSphere Portal. The application has two components: a URL Selector view on the left and a Managed Browser view on the right (see figure 2). Both views were developed in their own plug-ins and have no binary dependencies on each other.

The Selector view is a simple view with a list control with URLs that the user can select. This view publishes a property named URL From Tree and is of type URL. The Browser view is an SWT view with the Embedded Browser control on it. This view registers an action named loadURL that accepts a single input parameter named URLIn.

Figure 2. URL Selector and Managed Browser views
URL Selector and Managed Browser views

When the Selector view publishes the property, it goes through the Property Broker into the SWT action handler and into the action in the ManagedBrowser plug-in. That action then uses the SWTHelper class to locate the view instance and to call the method loadURL() on the view object.

Action handlers

To understand the architecture of the Property Broker, you need to understand what an action handler is. The fundamental reason the action handler extension point exists is to allow for existing event- or message-based systems to contribute actions to the declarative broker model. As stated above, Lotus Expeditor ships with three action handlers. You should use the appropriate action implementations based on the requirements by the action handlers. Ultimately, your action is called by one of these handlers. The broker passes the property change off to the registered handler of your action object type. Table 1 shows the three handlers available.

Table 1. Available action handlers
Plug-in NameDescriptionDependencies broker, core handler

Handler Type: COMMAND

Interface for actions: org.eclipse.core.commands.IHandler

org.eclipse.core.runtime handler:

Handler Type: SWT_ACTION

Interface for actions: org.eclipse.core.commands.IHandler
org.eclipse.ui 168 Portlet handler

Handler Type: PORTLET

Interface for actions: JSR 168 Portlet
org.eclipse.ui Action handler

Handler Type: AWT_ACTION

Interface for actions: java.awt.Component

The most critical piece to understand is the dependencies column of the table. If you write headless actions (a plug-in or code that cannot have UI dependencies), then use the org.eclipse.core.commands.IHandler interface when implementing your action. If your component is a graphically based component such as an SWT view, then you should implement the org.eclipse.core.commands.IHandler interface, but specify the SWT_ACTION type when creating your action. The SWT action handler eliminates the worry of enabling and disabling page-level wires. Any wires defined in the composite application XML are properly enabled or disabled when the perspectives are shown or hidden, respectively.

As mentioned previously, the action handler is responsible for implementing a compatible object with the callable action and also provides the PropertyChangeEvent interface, so that the property and wire information is available to the action (see figure 3). In most cases, you create only the action, not the action handler.

Figure 3. Action handler flow
Action handler flow

Creating actions in your component

In this section, we focus on the creation of an action. To begin, you must understand that an action is a piece of code that implements a predefined interface. A method is called in that code when a property value changes and when the property is properly wired to the actions component.

You start by creating an extension to the PropertyBrokerDefinitions extension point. To create this extension point, you must have a dependency on the bundle. This extension properly registers your action along with its input and output properties.

To get started quickly, you can use one of the templates provided with Lotus Expeditor Toolkit. The Property Broker Definitions template creates the extension, the WSDL file, and the action Java class. There are two templates from which to choose: one for a basic Eclipse action and one for an SWT action (see figure 4).

Figure 4. Choosing Extension Points
Choosing Extension Points

The template displays a screen in which you fill out the input and output property names along with the namespace in which you want to declare them (see figure 5). The templates should be considered starting points because they create actions with only one input property and one output property. You can always manually change the WSDL file to include additional output parameters.

NOTE: Currently the Property Broker supports only a single input property.

The next input screen is for defining your action class, which package it is in, and all the other elements to create an action with input and output parameters.

NOTE: All this can be changed directly in the WSDL and in the action code when it is generated.

Figure 5. Definitions template
Definitions template

You've now created an action class that is the entry point when a property change has occurred.

Figure 6 shows the Eclipse integrated development environment (IDE) and the artifacts that are created by the template from the information provided. Position 1 in the figure is the action Java file for either a core Eclipse command or SWT-based action; position 2 is the fully functional WSDL file from the above input; position 3 is the extension point; and position 4 is the association to the generated WSDL.

Figure 6. Eclipse IDE
Eclipse IDE

Lastly, when the Property Broker processes the PropertyBrokerDefinitions extension, it registers the properties with plug-in ID as the owner ID. It is important to understand this because an owner in the Property Broker must have unique components in it. A single owner can have only unique property and action names.

Using SWT actions with the Property Broker

Let's now discuss how SWT-based components, that is views, are used in the Property Broker framework. First, you must understand that the action code is not directly tied to any particular view or view instance. You can, however, update a specific instance of a view with the combination of the CAI and the data passed into the action. Unfortunately, this does not come easily in SWT actions, but there are helper APIs available to assist you.

When your action is called in the execute() method, you must call a couple helper functions to update the specific view instance (if that is what your action is intended to do). The sample code created looks similar to listing 1.

Listing 1. Sample code

public Object execute(ExecutionEvent event) throws ExecutionException {

  final Object eventTrigger = event.getTrigger();
  if (eventTrigger instanceof PropertyChangeEvent){
	final PropertyChangeEvent pce = (PropertyChangeEvent)eventTrigger;
	final PropertyValue value = pce.getPropertyValue();
	Display.getDefault().asyncExec(new Runnable() {
		public void run(){

		Wire def = pce.getWireDefinition();
		ViewPart view = SWTHelper.locateView(def.getTargetEntityId());
  return null;

Notice the lines highlighted in bold. The SWTHelper class has static methods that help identify the specific view instance you work with. The view ID is contained in the wire definition object, which is contained by the PropertyChangeEvent. In the wire definition, you can reference the source view and the target view of the wire. The CAI takes care of ensuring your action is called with the correct information. The locateView() call returns the IViewPart that is the target view instance. You should perform an instanceOf operation to make sure it is the view you are looking for, and then type cast it to the appropriate view class.

Integrating your component with WebSphere Portal CAI

The next step is to get your component registered with WebSphere Portal to integrate into the CAI. The primary artifact is the WSDL file created for your action extension. This same WSDL file must be used in a portlet defined on WebSphere Portal. The reason is that the portlet registers the properties and actions with the WebSphere Portal Property Broker and allows the portlet to be wired with other portlets (remember that all components in WebSphere Portal must be portlets to start with). When using Eclipse-based views as the runtime, it is only necessary to register a portlet with WebSphere Portal, so properties and actions can be registered for the component. The portlet is essentially a placeholder on the screen for where your component will display on the client.

For this exercise, we create a sample portlet in IBM Rational Application Developer and attach our WSDL file to it. The portlet code does not need to do anything because we are not using a portlet for the runtime. The portlet is configured to tell the client-side CAI to use our SWT view instead of a portlet.

After you have created your portlet, add the WSDL to it the same way you would when creating a collaborative portlet. Edit the portlet.xml file and point it to the location in the WAR file where your WSDL file was placed (see figure 7).

NOTE: You should name your portlet something similar to the name of your Eclipse view for clarity. When you place your portlet on a page, it makes more sense if it closely matches the name of your SWT view.

Figure 7. Editing of portlet.xml for the WSDL location
Editing of portlet.xml for the WSDL location

In figure 7, you can see that the portlet preference that must be specified is For each portlet and WSDL file you have, you must add this preference to the portlet.xml.

The next step is to export your WAR file from Rational Application Developer, and then, using the Portal Admin tool under Portlet Management, import it into WebSphere Portal (see figure 8).

Figure 8. Importing a WAR file
Importing a WAR file

You can bundle the portlets that represent your views into a single WAR file. Also, it's recommended that you align your WAR file and Eclipse plug-in as much as possible.

Next, place your portlets on a page (see figure 9) and edit their preferences with the Rich Client tab, which is installed when your administrator installs the Network Client Installer (NCI) on WebSphere Portal.

Figure 9. Edit Layout page
Edit Layout page

After the portlets are placed on the screen, you can edit their portlet instance preferences (see figure 10).

Figure 10. Rich Client tab
Rich Client tab

The Rich Client tab takes care of the underlying complexities of setting portlet preferences. The code sets a preference named to the text you place in the Eclipse view id field. This should be the primary view ID of your SWT component. When CAI creates the perspective and registers the view, the portlet ID is the secondary ID of the view.

After you configure your components and insert them on the page, you can wire the compatible properties and actions using the Portal Wiring Tool, located under the Wires tab. Figure 11 shows the URLSelector portlet wired to the Managed Browser portlet.

Figure 11. Portlet Wiring Tool
Portlet Wiring Tool

Deploying your component for provisioning

To distribute your component as part of a composite application from WebSphere Portal, you must deploy the component plug-ins to an HTTP server and point your components to that server. To do this, specify the Eclipse update site URL in the Rich Client tab of the portlet preference editor.

First, bundle your plug-in into an Eclipse feature, and then deploy that feature to an update site. After your update site is created, you must copy the site to a remote HTTP server to which your clients can connect.

Figure 12 shows the URL and the requirement specified in the Rich Client tab for a portlet. Notice that you specify the feature ID, version, and matching rule along with the URL from which to retrieve it.

Figure 12. Portlet feature requirements of the Rich Client tab
Portlet feature requirements of the Rich Client tab

By specifying a feature in a portlet preference, you tell the CAI to download these features prior to launching the application. Thus, the features are downloaded, installed, and activated prior to the screen launching.

Debugging with the OSGi console

When you launch Lotus Expeditor or the Eclipse platform with the -console switch, you can call into the Property Broker with some console-level commands. These commands are for debugging purposes only. As declarative systems can be quite complex in nature, these commands should assist you in figuring out which components, if any, are called by the Property Broker.

The Property Broker has a set of OSGi console commands that can be issued to assist in debugging and testing. The commands are present only when the platform is launched with the – console command, and you can access the list of commands by typing help at the console. Here is the current list of commands supported by the Property Broker (note that all the commands begin with pb):

Listing 2. Property Broker commands

---Property Broker Commands---
	pbsh a - Show all Actions
	pbsh aa - Show all Active Actions
	pbsh p - Show all properties by owner
	pbsh p <owner> - Show all properties for this owner (string owners only)
	pbsh w - Show all enabled wires
	pbsh aw - Show all wires
	pbsh ns - Show registered name spaces
	pbt <Property> - Trace the path for the specified property
	pbut <Property> - UnTrace the specified property, removes the trace
	pblt - Show a list of the currently traced Properties

As stated previously, the owner for actions and properties by default is the plug-in ID in which the extension is created. For wires, when used in CAI, the owner of the wire is the perspective ID. When CAI registers the wires, it automatically assigns the perspective ID as the wire owner. When perspectives are switched, CAI automatically enables and disables the wires appropriately. If you are registering wires manually, using the APIs or Extension Point, you are responsible for enabling, disabling, and un-registering them.

Debugging tips

Below are some possible problems areas and tips for debugging them:

  • Tracing a property
    If you are not sure why a component does not accept a property change, you can trace that property using the Property Broker trace command pbt. This command prints debug information to the console and log, essentially tracing the path of the changed property. If no output is shown, then you may have typed the property name wrong or the source component never published the property, for instance:

    osgi> pbt mypropery
    osgi> pbt “my property with spaces”
  • Wires not working
    If your component does not seem to be working or accepting any property changes, then make sure the wires and actions are enabled. You can use the pbsh w command to show all active wires and use the pbsh aa command to show all active actions.
  • Your WSDL registration
    Use the basic show commands for properties and actions to make sure your WSDL file is properly registered with the Property Broker. The pbsh p and pbsh p <owner> commands list all registered properties. For actions, you can use the pbsh a command to obtain a list of all registered actions.

Debugging WebSphere Portal topologies

You can have many WebSphere Portal applications, and within those applications, there can be many pages and within the pages, many components. The client-side topology manager is what takes the composite application XML from WebSphere Portal and dynamically creates the perspectives, its layout, and views for Eclipse. The topology handler also provides the data model for perspectives and views and associates Eclipse activities to the pages.

The following is a list of OSGi commands available for debugging purposes (recall that you can display this list by typing help at the OSGi console):

Listing 3. OSGi commands for debugging

---Topology Handler UI Commands---
thuish desc - Show all Perspective Descriptors
thuish del <perspective id> - Delete a Perspective Descriptor
thuish lp Show all Launcher Item IDs
thuish cd Show Current Perspective Descriptor
thuish ea Show Current Enabled Activities
thuish a <activity id> Show Activity State

---Topology Handler Commands--- thsh n - Show all navigation elements thsh p - Show all Pages thsh l - Show all Labels thsh f - Show all topology files thsh apps - Show all application GUIDs thsh e <namespace> - Show all registered extensions under the given namespace thsh dp - Show all dirty pages thsh nattr <navigation id> - Show all navigation preferences


Composite applications are a powerful concept. The openness in the runtime architecture allows for many possibilities with regard to integrating different components and technology in a seamless and consistent manner. This article explained at the root level how composite applications can be built and then aggregated into a single user interface.





developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

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


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

All information submitted is secure.

Choose your display name

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

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

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

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


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks

ArticleTitle=Creating collaborative components for IBM Lotus Expeditor Property Broker