Apache

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 topics="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

The event admin handler is available in the Felix trunk in the iPOJO project. See the Download page to download and compile these sources.

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 topics="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 topics="foo" callback="handleFooEvent" name="myFooEvent" />
 		<ev:subscriber topics="bar" callback="handleBarEvent" name="myBarEvent"/>
</component>
</ipojo>
Overview
Getting Started
User Guide
Tools
Developer Guide
Misc & Contact