The goal of the Event Handler is to allow event communications between iPOJO component instances. The implementation of this handler relies on an event admin services. It enables the iPOJO component to listen to a list of topics and to receive all related event, in an easy way.

Hereafter is presented a small example of the metadata.xml file:

<ipojo xmlns:ev="org.apache.felix.ipojo.handler.event.EventAdminSubscriberHandler">
<component className="...FooEventSubscriber">
		<ev:subscriber topic="foo" callback="handleEvent" name="myEvent"/>
</component>
</ipojo>

You need to specify the namespace of the Handler.
In the description, you have to specify the topic on which you want to listen, the callback method in your POJO, and a name which acts as an identifier. The topic is not mandatory, as it can be configured in the instance configuration. The callback method and the name are mandatory. The callback method must have a single argument of type org.osgi.event.Event. This will be checked by the handler. The following method is valid for the given description :

public void handleEvent(Event ev) {
   System.out.println("Receive an event : " + ev);
 }

Download

You can download the event handler. Binaries are available here (Jar compiled with Java 1.5). Sources are available here.
Sources are hosted inside the Felix sandbox on http://svn.apache.org/repos/asf/felix/sandbox/clement/event.handler.

How does it work?

The handler will parse the description provided in the metadata, and register for you the EventHandler in the OSGi Registry. Your POJO will receive each event through the handler. With this handler you can specify different callback methods for different topics.

EventHandler Features

Instance customization

You can specify the topic in each instance. Hereafter is an example of this feature.

<ipojo xmlns:ev="org.apache.felix.ipojo.handler.event.EventAdminSubscriberHandler">
<component className="FooEventSubscriber">
		<ev:subscriber callback="handleEvent" name="myEvent" />
</component>

<instance component="FooEventSubscriber" name="Foo">
	<property name="event.topics">
		<property name="myEvent" value="foo"/>
	</property>
</instance>
<instance component="FooEventSubscriber" name="Bar">
	<property name="event.topics">
		<property name="myEvent" value="bar"/>
	</property>
</instance>
</ipojo>

Listenning several topics

You can specify several topics for one callback method. For this you must separate each topic by a coma. Hereafter is an example of this feature.

<ipojo xmlns:ev="org.apache.felix.ipojo.handler.event.EventAdminSubscriberHandler">
<component className="FooEventSubscriber">
		<ev:subscriber callback="handleEvent" name="myEvent" />
</component>

<instance component="FooEventSubscriber" name="FooBar">
	<property name="event.topics">
		<property name="myEvent" value="foo,bar"/>
	</property>
</instance>
<instance component="FooEventSubscriber" name="BarBaz">
	<property name="event.topics">
		<property name="myEvent" value="bar,baz"/>
	</property>
</instance>
</ipojo>

Events filtering

You can specify a filter, as specified in the EventAdmin documentation. If you don't precise the filter, you will receive all event on the specified topic. It is also possible to specialize the filter in the instance configuration. The filter specified in the Instance configuration replaces the filter specified in the component. Here after is an example of this feature.

<ipojo xmlns:ev="org.apache.felix.ipojo.handler.event.EventAdminSubscriberHandler">
<component className="FooEventSubscriber">
		<ev:subscriber topic="foo" callback="handleEvent" filter="(event.value=Foo)" name="myEvent" />
</component>

<instance component="FooEventSubscriber" name="Foo1">
	<property name="event.filter">
		<property name="myEvent" value="(event.value=Foo1)"/>
	</property>
</instance>
</ipojo>

Several subscribers in one component

You can have several method receiving different events. Here after is an example of this feature

<ipojo xmlns:ev="org.apache.felix.ipojo.handler.event.EventAdminSubscriberHandler">
<component className="FooEventSubscriber">
		<ev:subscriber topic="foo" callback="handleFooEvent" name="myFooEvent" />
 		<ev:subscriber topic="bar" callback="handleBarEvent" name="myBarEvent"/>
</component>
</ipojo>