Writing a jWidget in Lotus Expeditor 6.2.2
Previous to 6.2.2, a developer had to develop to a lot of IBM-specific interfaces and a WSDL definition as well as manage properties outside the life cycle of their component. They also had to leverage three different extension points for statically defining preferences, dynamic properties and adding themselves to the assembly tool (Composite Application Editor CAE). In addition to the complexity of creating a component, those components could not function while hidden.
In 6.2.2 we provide a new jWidget class that can be extended which will perform all of that logic for Java Eclipse developers, so the developer can just interact with the eclipse provided IWorkBenchPart3 methods of the jWidget. This not only makes it much easier to develop a Java component on Lotus Expeditor and Lotus Notes, but also allows someone to incorporate a pure Eclipse Composite into these frameworks.
This article will cover how to leverage the new jWidget class and show how that class interacts with the composite application infrastructure.
Let’s first talk about what we need to do to create a new composite application component or a jWidget based on the jWidget class. We will do the following steps to create a jWidget, and then we will go into how the framework works under the covers.
- Define your jWidget, jWidget preferences and jWidget events.
- Create your jWidget Class
- Access your jWidget Preferences
- Create your jWidget input event code
- Create your jWidget output event code
- Create a composite for your jWidget
- System jWidget Extension Processing
- jWidget initialization
- jWidget event handling
- Default Composite support
Define your jWidget, jWidget preferences and jWidget events
The first thing you need to do to create a jWidget is define the jWidget with the com.ibm.rcp.composite.jWidget extension point. This allows you to start defining the preferences and events for your component. Each jWidget will have a set of descriptive information and a sequence of preferences and events.
The
jWidget definition has the following properties:
Name Display name of the jWidget.
Id Unique Id of the jWidget.
Description (optional) jWidget description.
Class class to the jWidget implementation.
Icon(optional) default icon for the jWidget.
Category(optional) defines the CAE category and the view category that the jWidget will be part of.
ReceiveEventsWhileInActive(optional) Toggles whether the jWidget will receive events when on a different page. Set to false for better performance if the jWidget does not require updates when in the background.
Preferences(optional) Preferences are used only during initialization of the component. These preferences are set by an assembler with defaults being set by the component developer.
Name Display name of the preference.
Id Unique Id of the preference.
Value Default Value(s) of the preference.
Type The property type. Predefined types are available: string, boolean, number, file, directory, NSF picker, colour or a list of options(choice).
Restrictions(optional) A list of values that can be used when creating the UI for the property. For example a min and max for a number, a list of options for a drop down combo or a list of file types for a file dialog. This value can contain multiple values that must be separated by ';'.
Group(optional) Preferences can be grouped together in the UI. Any preferences that have the same group name will be grouped together.
Help context(optional) This is a context Id for a help context that should be displayed if user hits F1 while this property has focus in UI.
Help tooltip(optional) This is Help text that will be displayed in a tooltip if user hovers over this property in the UI.
Events(optional) Events are dynamic changes to properties during the lifecycle of the component. These events can be published from this component or received by this component. Incoming events will also receive the last updated value of those properties even before the component was initialized during initialization.
Name The event name to be presented to the User.
Id Unique Id of the event.
Description(optional) Event Description.
Direction Direction refers to whether the component will listen (i), publish (o), for this event. These are values defined by the system.
Type(optional) Not used yet - spot for defining property value type, like string, CSV, . . . This is defined by the "event owner"
Create your jWidget Class
So once you have defined the jWidget, you are ready to create your jWidget class. The framework will handle everything for you, you just need to extend the base class and call the super method in the constructor.
package com.ibm.rcp.composite.jWidget.sample1;
import com.ibm.rcp.composite.jwidget.jWidget;
import com.ibm.rcp.composite.jwidget.views.jWidgetViewPart;
public class SamplejWidget1 extends jWidget {
public SamplejWidget1(jWidgetViewPart view) {
super(view);
}
}
The jWidget definition and the very basic jWidget class is enough to add this new jWidget to a composite application. The jWidget itself provides a default UI that you will see at runtime and in the editor.
Access your jWidget preferences
Now that you can add your jWidget to a composite application you will want to use the preferences you defined and the values that are set by the assembler. To access any preference you use the eclipse method;
getPartProperty(key)
where the key is the preference id. This will return you the value of that preference.
Create your jWidget Input Event code
If you have defined events, more specifically input events for this section, you will need to instrument your jWidget to do something with those events.
package com.ibm.rcp.composite.jWidget.sample1;
import com.ibm.rcp.composite.jwidget.jWidget;
import com.ibm.rcp.composite.jwidget.views.jWidgetViewPart;
import org.eclipse.jface.util.IPropertyChangeListener;
import org.eclipse.jface.util.PropertyChangeEvent;
public class SamplejWidget1 extends jWidget {
public class ComponentSampleViewPropertyChangeListener
implements IPropertyChangeListener
{
@Override
public void propertyChange(PropertyChangeEvent arg0) {
if (arg0.getProperty().equals("SampleInputEvent1"))
System.out.println("Value = "+arg0.getNewValue());
}
}
public SamplejWidget1(jWidgetViewPart view) {
super(view);
addPartPropertyListener(new
ComponentSampleViewPropertyChangeListener());
}
}
The first thing we need to do is add a part property listener in the constructor. In the part property listener, we will get notification for every property change for all the inputs events that we defined. So we parse our events and handle them accordingly.
Create your jWidget Output Event code
The typical next step would be to code up your output (or publish) events. This is done via the
setPartProperty(key, value)
method. A good example representing an jWidget at this stage would be one that takes an input value, applies some changes to that value and publishes that new value ( like a filter ). This jWidget type would not require any UI and in fact, when in run mode ( as opposed to edit mode ) would be hidden from the end user.
Create a composite for your jWidget
Most of your jWidgets will contain a UI element. The way you provide that to your jWidget is by implementing the
getComposite(Composite parent)
class.
So that is it. That is all you need to do to create a widget part for the client. The next half of this document will cover how the framework supports this internally.
Framework jWidget Processing
We will break down the framework jWidget flow into 3 parts; jWidget extension handling at system initialization, jWidget initialization, and dynamic events during jWidget life cycle.
Extending the jWidget class
This pretty much covers the first half of the document where the first two steps are creating the jWidget extension and extending the jWidget class. The interesting piece of step two is that the framework is going to create dynamic extensions for the jWidgets viewPart, properties and palette entry.
The viewPart id is what will be embedded in a composite application, and when that composite application is instantiated, all of those views will be created by the system. This is how the jWidget gets launched.
The properties are created using the ca.util extension. This extension provides two pieces of functionality. One is the creation of the preferences in the composite application and the second providing editable controls for modification of the preferences during edit mode.
The palette entry is the extension that associates the view ( jWidget in this case ) with CAE, so that the jWidget will show up on CAE’s palette for the assembler.
Step three is retrieving the preferences, we can use the IWorkbenchPart3 method getPartProperty(key) for all of our initialization preferences. This can be called at any time after we call the super method during our constructor.
getPartProperty(key);
In step four we code the events that the jWidget will either listen for from other components, publish to other components or both. Events are optional.
We handle events that come in from Property Broker (input events identified as ‘i’ in the event extension) by registering a partListener and handling the events in the listener code.
And finally we can write the code that publishes an event (input event defined as an “o” in the event extension).
setPartProperty("MYOUTPUTPROPERTY", myOutputValue);
Now that we have built a jWidget, let’s go over how this works at runtime.
Initialization of the jWidget Extended Component
1) As mentioned in the previous section, when a composite application is instantiated, all the views for the visible page get created. If one of those components is a jWidget, a jWidget viewPart will be launched.
2) That view part will launch the jWidget core which will perform steps three thru five and then register the actual jWidget class with the jWidget manager.
3) The jWidget init method will populate its part property registry with both preferences and events. It will set the values of the preferences from the configuration data stored in the .ca file.
4) The core will process the events defined using the iWidget event extension and create property broker listeners for input events and part property listeners for output events.
5) Then it sets the input event properties with the cached values of the event to get the last update in the system before the component was listening for events.
6) When the core initialization completes, the viewPart will then register the jWidget class with the jWidget manager. The sole job of the manager is to keep a reference to the jWidget class so it is not disposed if the view is disposed. This mechanism allows for one, no requirement on a UI part at all for the jWidget and two, allows the jWidget to function even if it is in a hidden state.
After initialization of the composite application component, the component will receive and publish events in the following manner:
Publishing and Receiving Properties
The property broker and part property listeners that we registered during initialization now come into play during the remainder of the time that the component is running.
1) The jWidget class listens for any property changes from the system which will be delivered by Property Broker. The jWidget PB Listener will then convert that to a setPartProperty to its part property registry which will notify the new components partPropertyListener.
2) The jWidget class also listens for any part property changes and converts them to property broker publishes for interaction with other composite application components.
When the component is disposed the jWidget class cleans up all the resources (listeners and extension maps) used by the new component.
Other Features
When extending the jWidget class, the new component will inherit the component properties “Receive Events while inactive” and “Component visibile”. “Receive Events while inactive” is a boolean property that when true will send the publish event to the component even if the component is inactive on a page. “Component visibile” set the hidden state of the component on the page.
The jWidget will set the assembler given title for the view part.
Use the jWidget to create a container that also provides a set of properties. You can override the container landmark methods on the jWidget and create a container that also will support the event extension.
Michael R Cooper