SnTT : Quite possibly the simplest property broker example

I've completed step two of my "Adventures in Expeditor Toolkit". It is quite possibly the simplest property broker example. One target view, one source view and one property.

I looked the the Color Swatch example that comes with the toolkit. It had multiple properties and three views and the naming convention for a beginner was a little convoluted.

I decided to create my own 'hello world' property broker example. I've attached a zip of the workspace it you want to run it or browse the files.

This purpose of this post is to share with you a very simple example to get to grips with the Property Broker and Wires. Something that the average Lotus/Notes Developer can look at, run and understand.

About the Hello World Example

I wanted a component where I could enter some text and using the property broker, send this to another component for display.

I started with the New > Project > Client Services > Client Services Project followed the prompts including choosing the 'rich basic application' which generates some of the bits required for the project. I then looked at the Color Swatch sample and worked out which parts needed changing. If you need step by step instructions on how to create a composite application, wires and actions in Expeditor then you should look at the redpiece, redbook, and the tutorial posted in the nd8 forum .

So lets have a quick look at the parts of the puzzle.

Perspective.java - this pulls the components/view parts into the application and is one of the first files run
SourceView.java - the view part that contains, the field to enter the message and a button to trigger the location of a property, changing the value and sending the notification that a property had changed
TargetView.java - the view part that sets the text box with the value of the change property
TargetHandler.java - the action that is called by the property broker, and checks if the event is a property change event, and calls the TargetView to update the text box with the new value.
source.wsdl - contains getSourceMessage action and outgoing property MessageItemValue
target.wsdl - contains setTargetMessage action and incoming property MessageItemValue

I had all the parts of the puzzle there, but I couldn't get the Wiring Properties Editor to produce the same WSDL file as the Color Swatch example, so in the end I updated the file manually to set the actionNameParameter attribute and remove the boundTo="request-attribute" attribute. I also renamed the <portlet:param name/> to setMessageValue for target.wsdl and getMessageValue for source.wsdl

I could run up the application, but nothing happened. I added a few debug lines and I could see that the property was being set in java but what about the property broker.The post on the Composite App details how to trouble shoot with the OSGi console. You can enter these commands in the eclipse console at the osgi>

pbsh p - showed me the current properties

-----------------------------------------
Owner = com.scius.examples.helloworld
There are 2 properties registered.
-----------------------------------------
Name: setMessageValue
Namespace: http://www.w3.org/2001/XMLSchema
Type: string
Class: class com.ibm.rcp.propertybroker.internal.property.PropertyImpl
Default: null
Direction: [IN]
Is Wired: NO
-----------------------------------------
Name: getMessageValue
Namespace: http://www.w3.org/2001/XMLSchema
Type: string
Class: class com.ibm.rcp.propertybroker.internal.property.PropertyImpl
Default: null
Direction: [OUT]
Is Wired: YES
-----------------------------------------

pbsh a - shows me the actions
-----------------------------
NAME: getSourceMessage
Handler Type: SWT_ACTION
Runnable Type: com.scius.examples.helloworld.actions.SourceAction
Owner ID: com.scius.examples.helloworld
Name Parameter: ACTION_NAME
Parameters: 1 parameters
Property = getMessageValue
Property NS = http://www.w3.org/2001/XMLSchema
Type: string
Property ClassName = java.lang.String
Property default Value = null
Direction: [OUT]
-----------------------------
NAME: setTargetMessage
Handler Type: SWT_ACTION
Runnable Type: com.scius.examples.helloworld.actions.TargetHandler
Owner ID: com.scius.examples.helloworld
Name Parameter: ACTION_NAME
Parameters: 1 parameters
Property = setMessageValue
Property Title =
Property NS = http://www.w3.org/2001/XMLSchema
Type: string
Property ClassName = java.lang.String
Property default Value = null
Direction: [IN]
-------------------------

pbsh aw - shows me the active wires

-----------------------------
Owner = com.scius.examples.helloworld
There are 1 wires registered.
-----------------------------------------
Title: Source to Target Message
Id: PROPERTY_TO_ACTION_WIRE:getMessageValue:setTargetMessage:com.scius.examples.helloworld.richapp.SourceView:com.scius.examples.helloworld.richapp.TargetView
Owner Id: com.scius.examples.helloworld
Ordinal: 100
Type: PROPERTY_TO_ACTION_WIRE
Source Name: getMessageValue
Source Entity ID: com.scius.examples.helloworld.richapp.SourceView
Source Param: null
Target Name: setTargetMessage
Target Entity ID: com.scius.examples.helloworld.richapp.TargetView
Target Param: null
Is Cross Page: false
-----------------------------

In the documentation the description of how a wire docking point is described as such.

In order to wire a docking or end point the location is uniquely identified by the following

• The property’s namespace
• The property’s name
• The property’s type
• The component’s entity ID

When I looked through the information from the diagnostics it all looks good so why is the example not working ?

OSGi console allows you to trace properties, so I registered each property.

pbt setMessageValue
pbt getMessageValue

osgi> pblt
-----------------------------------------
Registered Property Traces are:
-----------------------------------------
1. setMessageValue
2. getMessageValue

I tried again and this time there was more information from the trace

osgi> com.scius.examples.helloworld.richapp.SourceView:Text to be sent:hello world com.scius.examples.helloworld.richapp.SourceView$Listener:Sending Property Change Notification 2007/11/16 10:09:50.062 WARNING PBTRACE(getMessageValue) changedProperties was called. ::class.method=com.ibm.rcp.propertybroker.internal.PropertyBrokerDispatcher.changedProperties() ::thread=main ::loggername=com.ibm.rcp.propertybroker

So it looks like the notification is being sent correctly, but the TargetHandler.java isn't being called. Why ? This paragraph in the redpiece fills in the last piece of the puzzle.

However, as a view can be used in multiple places, sometimes even on the same page, a secondary ID is required to uniquely identify a view. If you declared your application through a perspective as described in 3.9, “Laying out applications programmatically” on page 53, you might not have provided any secondary IDs for your views. You must, however, always do so. Property broker assumes, that all views have secondary IDs.

So even though I was only using one instance of TargetView.java I needed to uniquely identify the View. I'd seen the ":fore" and ":back" seconday ids for the Color Swatch but thought that I didn't need them - once I added the ":hello" secondary id to the TargetView.java id and all references the sample worked.


So there you have it - one working very simple property broker and wires example.

SnTT