OSGi Event Admin - Publish & Subscribe

In this blog post I want to write about the publish & subscribe mechanism in OSGi, provided via the OSGi Event Admin Service. Of course I will show this in combination with OSGi Declarative Services, because this is the technology I currently like very much, as you probably know from my previous blog posts.

I will start with some basics and then show an example as usual. At last I will give some information about how to use the event mechanism in Eclipse RCP development, especially related to the combination between OSGi services and the GUI.

If you want to read further details on the Event Admin Service Specification have a look at the OSGi Spec. In Release 7 it is covered in the Compendium Specification Chapter 113.

Let’s start with the basics. The Event Admin Service is based on the Publish-Subscribe pattern. There is an event publisher and an event consumer. Both do not know each other in any way, which provides a high decoupling. Simplified you could say, the event publisher sends an event to a channel, not knowing if anybody will receive that event. On the other side there is an event consumer ready to receive events, not knowing if there is anybody available for sending events. This simplified view is shown in the following picture:

Technically both sides are using the Event Admin Service in some way. The event publisher uses it directly to send an event to the channel. The event consumer uses it indirectly by registering an event handler to the EventAdmin to receive events. This can be done programmatically. But with OSGi DS it is very easy to register an event handler by using the whiteboard pattern.

Event

An Event object has a topic and some event properties. It is an immutable object to ensure that every handler gets the same object with the same state.

The topic defines the type of the event and is intended to serve as first-level filter for determining which handlers should receive the event. It is a String arranged in a hierarchical namespace. And the recommendation is to use a convention similar to the Java package name scheme by using reverse domain names (fully/qualified/package/ClassName/ACTION). Doing this ensures uniqueness of events. This is of course only a recommendation and you are free to use pseudo class names to make the topic better readable.

Event properties are used to provide additional information about the event. The key is a String and the value can be technically any object. But it is recommended to only use String objects and primitive type wrappers. There are two reasons for this:

1. Other types cannot be passed to handlers that reside external from the Java VM.
2. Other classes might be mutable, which means any handler that receives the event could change values. This break the immutability rule for events.

Common Bundle

It is some kind of best practice to place common stuff in a common bundle to which the event publisher bundle and the event consumer bundle can have a dependency to. In our case this will only be the definition of the supported topics and property keys in a constants class, to ensure that both implementations share the same definition, without the need to be dependent on each other.

• Create a new project org.fipro.mafia.common
• Create a new package org.fipro.mafia.common
• Create a new class MafiaBossConstants

public final class MafiaBossConstants {

    private MafiaBossConstants() {
        // private default constructor for constants class to avoid someone extends the class
    }

    public static final String TOPIC_BASE = "org/fipro/mafia/Boss/"; 
    public static final String TOPIC_CONVINCE = TOPIC_BASE + "CONVINCE"; 
    public static final String TOPIC_ENCASH = TOPIC_BASE + "ENCASH"; 
    public static final String TOPIC_SOLVE = TOPIC_BASE + "SOLVE"; 
    public static final String TOPIC_ALL = TOPIC_BASE + "*";
    public static final String PROPERTY_KEY_TARGET = "target";
}

• PDE
  • Open the MANIFEST.MF file and on the Overview tab set the Version to 1.0.0 (remove the qualifier).
  • Switch to the Runtime tab and export the org.fipro.mafia.common package.
  • Specify the version 1.0.0 on the package via Properties…
• Bndtools
  • Open the bnd.bnd file
  • Add the package org.fipro.mafia.common to the Export Packages

In MafiaBossConstants we specify the topic base with a pseudo class org.fipro.mafia.Boss, which results in the topic base org/fipro/mafia/Boss. We specify action topics that start with the topic base and end with the actions CONVINCE, ENCASH and SOLVE. And additionally we specify a topic that starts with the base and ends with the wildcard ‘*’.

These constants will be used by the event publisher and the event consumer soon.

Event Publisher

The Event Publisher uses the Event Admin Service to send events synchronously or asynchronously. Using DS this is pretty easy.

We will create an Event Publisher based on the idea of a mafia boss. The boss simply commands a job execution and does not care who is doing it. Also it is not of interest if there are many people doing the same job. The job has to be done!

• Create a new project org.fipro.mafia.boss
• PDE
  • Open the MANIFEST.MF file of the org.fipro.mafia.boss project and switch to the Dependencies tab
  • Add the following dependencies on the Imported Packages side:
    • org.fipro.mafia.common (1.0.0)
    • org.osgi.service.component.annotations (1.3.0)
    • org.osgi.service.event (1.3.0)
  • Mark org.osgi.service.component.annotations as Optional via Properties…
  • Add the upper version boundaries to the Import-Package statements.
• Bndtools
  • Open the bnd.bnd file of the org.fipro.mafia.boss project and switch to the Build tab
  • Add the following bundles to the Build Path
    • org.apache.felix.eventadmin
    • org.fipro.mafia.common

Note:
Adding org.osgi.service.event to the Imported Packages with PDE on a current Equinox target will provide a package version 1.3.1. You need to change this to 1.3.0 if you intend to run the same bundle with a different Event Admin Service implementation. In general it is a bad practice to rely on a bugfix version. Especially when thinking about interfaces, as any change to an interface typically is a breaking change. To clarify the statement above. As the package org.osgi.service.event contains more than just the EventAdmin interface, the bugfix version increase is surely correct in Equinox, as there was probably a bugfix in some code inside the package. The only bad thing is to restrict the package wiring on the consumer side to a bugfix version, as this would restrict your code to only run with the Equinox implementation of the Event Admin Service.

• Create a new package org.fipro.mafia.boss
• Create a new class BossCommand

@Component(
    property = {
        "osgi.command.scope=fipro",
        "osgi.command.function=boss"
    },
    service = BossCommand.class) 
public class BossCommand {

    @Reference
    EventAdmin eventAdmin;

    @Descriptor("As a mafia boss you want something to be done") 
    public void boss(
        @Descriptor("the command that should be executed. " + "possible values are: convince, encash, solve")
        String command,
        @Descriptor("who should be 'convinced', " + "'asked for protection money' or 'finally solved'")
        String target) {

        // create the event properties object 
        Map<String, Object> properties = new HashMap<>(); 
        properties.put(MafiaBossConstants.PROPERTY_KEY_TARGET, target); 
        Event event = null;
	
        switch (command) { 
            case "convince":
                event = new Event(MafiaBossConstants.TOPIC_CONVINCE, properties); 
                break; 
            case "encash":
                event = new Event(MafiaBossConstants.TOPIC_ENCASH, properties); 
                break; 
            case "solve":
                event = new Event(MafiaBossConstants.TOPIC_SOLVE, properties); 
                break; 
            default:
                System.out.println("Such a command is not known!"); 
        }

        if (event != null) { 
            eventAdmin.postEvent(event); 
        } 
    } 
}

Note:
The code snippet above uses the annotation @Descriptor to specify additional information for the command. This information will be shown when executing help boss in the OSGi console. To make this work with PDE you need to import the package org.apache.felix.service.command with status=provisional. Because the PDE editor does not support adding additional information to package imports, you need to do this manually in the MANIFEST.MF tab of the Plugin Manifest Editor. The Import-Package header would look like this:

Import-Package: org.apache.felix.service.command;status=provisional;version="0.10.0",
 org.fipro.mafia.common;version="[1.0.0,2.0.0)",
 org.osgi.service.component.annotations;version="[1.3.0,2.0.0)";resolution:=optional,
 org.osgi.service.event;version="[1.3.0,2.0.0)"

With Bndtools you need to add org.apache.felix.gogo.runtime to the Build Path in the bnd.bnd file so the @Descriptor annotation can be resolved.

There are three things to notice in the BossCommand implementation:

• There is a mandatory reference to EventAdmin which is required for sending events.
• The Event objects are created using a specific topic and a Map<String, Object> that contains the additional event properties.
• The event is sent asynchronously via EventAdmin#postEvent(Event)

The BossCommand will create an event using the topic that corresponds to the given command parameter. The target parameter will be added to a map that is used as event properties. This event will then be send to a channel via the EventAdmin. In the example we use EventAdmin#postEvent(Event) which sends the event asynchronously. That means, we send the event but do not wait until available handlers have finished the processing. If it is required to wait until the processing is done, you need to use EventAdmin#sendEvent(Event), which sends the event synchronously. But sending events synchronously is significantly more expensive, as the Event Admin Service implementation needs to ensure that every handler has finished processing before it returns. It is therefore recommended to prefer the usage of asynchronous event processing.

Note:
The code snippet uses the Field Strategy for referencing the EventAdmin. If you are using PDE this will work with Eclipse Oxygen. With Eclipse Neon you need to use the Event Strategy. In short, you need to write the bind-event-method for referencing EventAdmin because Equinox DS supports only DS 1.2 and the annotation processing in Eclipse Neon also only supports the DS 1.2 style annotations.

Event Consumer

In our example the boss does not have to tell someone explicitly to do the job. He just mentions that the job has to be done. Let’s assume we have a small organization without hierarchies. So we skip the captains etc. and simply implement some soldiers. They have specialized, so we have three soldiers, each listening to one special topic.

• Create a new project org.fipro.mafia.soldier
• PDE
  • Open the MANIFEST.MF file of the org.fipro.mafia.soldier project and switch to the Dependencies tab
  • Add the following dependencies on the Imported Packages side:
    • org.fipro.mafia.common (1.0.0)
    • org.osgi.service.component.annotations (1.3.0)
    • org.osgi.service.event (1.3.0)
  • Mark org.osgi.service.component.annotations as Optional via Properties…
  • Add the upper version boundaries to the Import-Package statements.
• Bndtools
  • Open the bnd.bnd file of the org.fipro.mafia.boss project and switch to the Build tab
  • Add the following bundles to the Build Path
    • org.apache.felix.eventadmin
    • org.fipro.mafia.common
• Create a new package org.fipro.mafia.soldier
• Create the following three soldiers Luigi, Mario and Giovanni

@Component(property = EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_CONVINCE) 
public class Luigi implements EventHandler {

    @Override
    public void handleEvent(Event event) { 
        System.out.println("Luigi: "
            + event.getProperty(MafiaBossConstants.PROPERTY_KEY_TARGET)
            + " was 'convinced' to support our family"); 
    }
}

@Component(property = EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_ENCASH) 
public class Mario implements EventHandler {

    @Override 
    public void handleEvent(Event event) { 
        System.out.println("Mario: "
            + event.getProperty(MafiaBossConstants.PROPERTY_KEY_TARGET)
            + " payed for protection"); 
    }
}

@Component(property = EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_SOLVE) 
public class Giovanni implements EventHandler {

    @Override 
    public void handleEvent(Event event) { 
        System.out.println("Giovanni: We 'solved' the issue with "
            + event.getProperty(MafiaBossConstants.PROPERTY_KEY_TARGET)); 
    }
}

Technically we have created special EventHandler for different topics. You should notice the following facts:

• We are using OSGi DS to register the event handler using the whiteboard pattern. On the consumer side we don’t need to know the EventAdmin itself.
• We need to implement org.osgi.service.event.EventHandler
• We need to register for a topic via service property event.topics, otherwise the handler will not listen for any event.
• Via Event#getProperty(String) we are able to access event property values.

The following service properties are supported by event handlers:

Service Registration Property	Description
event.topics	Specify the topics of interest to an EventHandler service. This property is mandatory.
event.filter	Specify a filter to further select events of interest to an EventHandler service. This property is optional.
event.delivery	Specifying the delivery qualities requested by an EventHandler service. This property is optional.

The property keys and some default keys for event properties are specified in org.osgi.service.event.EventConstants.

Launch the example

Before moving on and explaining further, let’s start the example and verify that each command from the boss is only handled by one soldier.

With PDE perform the following steps:

• Select the menu entry Run -> Run Configurations…
• In the tree view, right click on the OSGi Framework node and select New from the context menu
• Specify a name, e.g. OSGi Event Mafia
• Deselect All
• Select the following bundles (note that we are using Eclipse Oxygen, in previous Eclipse versions org.apache.felix.scr and org.eclipse.osgi.util are not required)
  • Application bundles
    • org.fipro.mafia.boss
    • org.fipro.mafia.common
    • org.fipro.mafia.soldier
  • Console bundles
    • org.apache.felix.gogo.command
    • org.apache.felix.gogo.runtime
    • org.apache.felix.gogo.shell
    • org.eclipse.equinox.console
  • OSGi framework and DS bundles
    • org.apache.felix.scr
    • org.eclipse.equinox.ds
    • org.eclipse.osgi
    • org.eclipse.osgi.services
    • org.eclipse.osgi.util
  • Equinox Event Admin
    • org.eclipse.equinox.event
• Ensure that Default Auto-Start is set to true
• Click Run

With Bndtools perform the following steps:

• Open the launch.bndrun file in the org.fipro.mafia.boss project
• On the Run tab add the following bundles to the Run Requirements
  • org.fipro.mafia.boss
  • org.fipro.mafia.common
  • org.fipro.mafia.soldier
• Click Resolve to ensure all required bundles are added to the Run Bundles via auto-resolve
• Click Run OSGi

Execute the boss command to see the different results. This can look similar to the following:

g! boss convince Angelo
Luigi: Angelo was 'convinced' to support our family
g! boss encash Wong
Mario: Wong payed for protection
g! boss solve Tattaglia
Giovanni: We 'solved' the issue with Tattaglia

Handle multiple event topics

It is also possible to register for multiple event topics. Say Pete is a tough guy who is good in ENCASH and SOLVE issues. So he registers for those topics.

@Component(
    property = {
        EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_CONVINCE,
        EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_SOLVE
    }) 
public class Pete implements EventHandler {

    @Override public void handleEvent(Event event) { 
        System.out.println("Pete: I took care of "
            + event.getProperty(MafiaBossConstants.PROPERTY_KEY_TARGET)); 
    }
}

As you can see the service property event.topics is declared multiple times via the @Component annotation type element property. This way an array of Strings is configured for the service property, so the handler reacts on both topics.

If you execute the example now and call boss convince xxx or boss solve xxx you will notice that Pete is also responding.

It is also possible to use the asterisk wildcard as last token of a topic. This way the handler will receive all events for topics that start with the left side of the wildcard.

Let’s say we have a very motivated young guy called Ray who wants to prove himself to the boss. So he takes every command from the boss. For this we set the service property event.topics=org/fipro/mafia/Boss/*

@Component(property = EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_ALL) 
public class Ray implements EventHandler {

    @Override 
    public void handleEvent(Event event) { 
        String topic = event.getTopic();
        Object target = event.getProperty(MafiaBossConstants.PROPERTY_KEY_TARGET);

        switch (topic) { 
            case MafiaBossConstants.TOPIC_CONVINCE:
                System.out.println("Ray: I helped in punching the shit out of" + target); 
                break; 
            case MafiaBossConstants.TOPIC_ENCASH:
                System.out.println("Ray: I helped getting the money from " + target); 
                break; 
            case MafiaBossConstants.TOPIC_SOLVE:
                System.out.println("Ray: I helped killing " + target); 
                break; 
            default:
                System.out.println("Ray: I helped with whatever was requested!"); 
        } 
    }
}

Executing the example again will show that Ray is responding on every boss command.

It is also possible to filter events based on event properties by setting the service property event.filter. The value needs to be an LDAP filter. For example, although Ray is a motivated and loyal soldier, he refuses to handle events that target his friend Sonny.

The following snippet shows how to specify a filter that excludes event processing if the target is Sonny.

@Component(
    property = {
        EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_ALL,
        EventConstants.EVENT_FILTER + "=" + "(!(target=Sonny))"
    })
public class Ray implements EventHandler {

Execute the example and call two commands:

• boss solve Angelo
• boss solve Sonny

You will notice that Ray will respond on the first call, but he will not show up on the second call.

Note:
The filter expression can only be applied on event properties. It is not possible to use that filter on service properties.

At last it is possible to configure in which order the event handler wants the events to be delivered. This can either be ordered in the same way they are posted, or unordered. The service property event.delivery can be used to change the default behavior, which is to receive the events from a single thread in the same order as they were posted.

If an event handler does not need to receive events in the order as they were posted, you need to specify the service property event.delivery=async.unordered.

@Component(
    property = {
        EventConstants.EVENT_TOPIC + "=" + MafiaBossConstants.TOPIC_ALL,
        EventConstants.EVENT_FILTER + "=" + "(!(target=Sonny))",
        EventConstants.EVENT_DELIVERY + "=" + EventConstants.DELIVERY_ASYNC_UNORDERED
    })

The value for ordered delivery is async.ordered which is the default. The values are also defined in the EventConstants.

Capabilities

By using the event mechanism the code is highly decoupled. In general this is a good thing, but it also makes it hard to identify issues. One common issue in Eclipse RCP for example is to forget to automatically start the bundle org.eclipse.equinox.event. Things will simply not work in such a case, without any errors or warnings shown on startup.

The reason for this is that the related interfaces like EventAdmin and EventHandler are located in the bundle org.eclipse.osgi.services. The bundle wiring therefore shows that everything is ok on startup, because all interfaces and classes are available. But we require a bundle that contains an implementation of EventAdmin. If you remember my Getting Started Tutorial, such a requirement can be specified by using capabilities.

To show the implications, let’s play with the Run Configuration:

• Uncheck org.eclipse.equinox.event from the list of bundles
• Launch the configuration
• execute lb on the command line (or ss on Equinox if you are more familiar with that) and check the bundle states
  • Notice that all bundles are in ACTIVE state
• execute scr:list (or list on Equinox < Oxygen) to check the state of the DS components
  • Notice that org.fipro.mafia.boss.BossCommand has an unsatisfied reference
  • Notice that all other EventHandler services are satisfied

That is of course a the correct behavior. The BossCommand service has a mandatory reference to EventAdmin and there is no such service available. So it has an unsatisfied reference. The EventHandler implementations do not have such a dependency, so they are satisfied. And that is even fine when thinking in the publish & subscribe pattern. They can be active and waiting for events to process, even if there is nobody available to send an event. But it makes it hard to find the issue. And when using Tycho and the Surefire Plugin to execute tests, it will even never work because nobody tells the test runtime that org.eclipse.equinox.event needs to be available and started in advance.

This can be solved by adding the Require-Capability header to require an osgi.service for objectClass=org.osgi.service.event.EventAdmin.

Require-Capability: osgi.service; filter:="(objectClass=org.osgi.service.event.EventAdmin)"

By specifying the Require-Capability header like above, the capability will be checked when the bundles are resolved. So starting the example after the Require-Capability header was added will show an error and the bundle org.fipro.mafia.boss will not be activated.

If you add the bundle org.eclipse.equinox.event again to the Run Configuration and launch it again, there are no issues.

As p2 does still not support OSGi capabilities, the p2.inf file needs to be created in the META-INF folder with the following content:

requires.1.namespace = osgi.service requires.1.name = org.osgi.service.event.EventAdmin

Typically you would specify the Require-Capability to the EventAdmin service with the directive effective:=active. This implies that the OSGi framework will resolve the bundle without checking if another bundle provides the capability. It can then be more seen as a documentation which services are required from looking into the MANIFEST.MF.

Important Note:
Specifying the Require-Capability header and the p2 capabilities for org.osgi.service.event.EventAdmin will only work with Eclipse Oxygen. I contributed the necessary changes to Equinox for Oxygen M1 with Bug 416047. With a org.eclipse.equinox.event bundle in a version >= 1.4.0 you should be able to specify the capabilities. In previous versions the necessary Provide-Capability and p2 capability configuration in that bundle are missing.

Handling events in Eclipse RCP UI

When looking at the architecture of an Eclipse RCP application, you will notice that the UI layer is not created via OSGi DS (actually that is not a surprise!). And we can not simply say that our view parts are created via DS, because the lifecycle of a part is controlled by other mechanics. But as an Eclipse RCP application is typcially an application based on OSGi, all the OSGi mechanisms can be used. Of course not that convenient as with using OSGi DS directly.

The direction from the UI layer to the OSGi service layer is pretty easy. You simply need to retrieve the service you want to uw3. With Eclipse 4 you simply get the desired service injected using @Inject or @Inject in combination with @Service since Eclipse Oxygen (see OSGi Declarative Services news in Eclipse Oxygen). With Eclipse 3.x you needed to retrieve the service programmatically via the BundleContext.

The other way to communicate from a service to the UI layer is something different. There are two ways to consider from my point of view:

• make use of the Observer pattern
• make use of the Publish & Subscribe pattern

This blog post is about the event mechanism in OSGi, so I don’t want to go in detail with the observer pattern approach. It simply means that you extend the service interface to accept listeners to perform callbacks. Which in return means you need to retrieve the service in the view part for example, and register a callback function from there.

With the Publish & Subscribe pattern we register an EventHandler that reacts on events. It is a similar approach to the Observer pattern, with some slight differences. But this is not a design pattern blog post, we are talking about the event mechanism. And we already registered an EventHandler using OSGi DS. The difference to the scenario using DS is that we need to register the EventHandler programmatically. For OSGi experts that used the event mechanism before DS came up, this is nothing new. For all others that learn about it, it could be interesting.

The following snippet shows how to retrieve a BundleContext instance and register a service programmatically. In earlier days this was done in an Activator, as there you have access to the BundleContext. Nowadays it is recommended to use the FrameworkUtil class to retrieve the BundleContext when needed, and to avoid Activators to reduce startup time.

private ServiceRegistration<?> eventHandler;

...

// retrieve the bundle of the calling class 
Bundle bundle = FrameworkUtil.getBundle(getClass()); 
BundleContext bc = (bundle != null) ? bundle.getBundleContext() : null;
if (bc != null) { 
    // create the service properties instance 
    Dictionary<String, Object> properties = new Hashtable<>(); 
    properties.put(EventConstants.EVENT_TOPIC, MafiaBossConstants.TOPIC_ALL);

    // register the EventHandler service 
    eventHandler = bc.registerService(EventHandler.class.getName(), new EventHandler() {

        @Override
        public void handleEvent(Event event) {
            // ensure to update the UI in the UI thread 
            Display.getDefault().asyncExec(() -> handlerLabel.setText(
                "Received boss command " + event.getTopic()
                + " for target " + event.getProperty(MafiaBossConstants.PROPERTY_KEY_TARGET))); 
        } 
    }, properties); 
}

This code can be technically added anywhere in the UI code, e.g. in a view, an editor or a handler. But of course you should be aware that the event handler also should be unregistered once the connected UI class is destroyed. For example, you implement a view part that registers a listener similar to the above to update the UI everytime an event is received. That means the handler has a reference to a UI element that should be updated. If the part is destroyed, also the UI element is destroyed. If you don’t unregister the EventHandler when the part is destroyed, it will still be alive and react on events and probably cause exceptions without proper disposal checks. It is also a cause for memory leaks, as the EventHandler references a UI element instance that is already disposed but can not be cleaned up by the GC as it is still referenced.

Note:
The event handling is executed in its own event thread. Updates to the UI can only be performed in the main or UI thread, otherwise you will get a SWTException for Invalid thread access. Therefore it is necessary to ensure that UI updates performed in an event handler are executed in the UI thread. For further information have a look at Eclipse Jobs and Background Processing. For the UI synchronization you should also consider using asynchronous execution via Display#asyncExec() or UISynchronize#asyncExec(). Using synchronous execution via syncExec() will block the event handler thread until the UI update is done.

If you stored the ServiceRegistration object returned by BundleContext#registerService() as shown in the example above, the following snippet can be used to unregister the handler if the part is destroyed:

if (eventHandler != null) {
    eventHandler.unregister();
}

In Eclipse 3.x this needs to be done in the overriden dispose() method. In Eclipse 4 it can be done in the method annotated with @PreDestroy.

Note:
Ensure that the bundle that contains the code is in ACTIVE state so there is a BundleContext. This can be achieved by setting Bundle-ActivationPolicy: lazy in the MANIFEST.MF.

Handling events in Eclipse RCP UI with Eclipse 4

In Eclipse 4 the event handling mechanism is provided to the RCP development via the EventBroker. The EventBroker is a service that uses the EventAdmin and additionally provides injection support. To learn more about the EventBroker and the event mechanism provided by Eclipse 4 you should read the related tutorials, like

• Eclipse 4 event system
• OSGi declarative services and the event bus

We are focusing on the event consumer here. Additionally to registering the EventHandler programmatically, it is possible in Eclipse 4 to specify a method for method injection that is called on event handling by additionally providing support for injection.

Such an event handler method looks similar to the following snippet:

@Inject
@Optional 
void handleConvinceEvent(@UIEventTopic(MafiaBossConstants.TOPIC_CONVINCE) String target) { 
    e4HandlerLabel.setText("Received boss CONVINCE command for " + target); 
}

By using @UIEventTopic you ensure that the code is executed in the UI thread. If you don’t care about the UI thread, you can use @EventTopic instead. The handler that is registered in the back will also be automatically unregistered if the containing instance is destroyed.

While the method gets directly invoked as event handler, the injection does not work without modifications on the event producer side. For this the data that should be used for injection needs to be added to the event properties for the key org.eclipse.e4.data. This key is specified as a constant in IEventBroker. But using the constant would also introduce a dependency to org.eclipse.e4.core.services, which is not always intended for event producer bundles. Therefore modifying the generation of the event properties map in BossCommand will make the E4 event handling injection work:

// create the event properties object 
Map<String, Object> properties = new HashMap<>(); 
properties.put(MafiaBossConstants.PROPERTY_KEY_TARGET, target); 
properties.put("org.eclipse.e4.data", target); 

Note:
The EventBroker additionally adds the topic to the event properties for the key event.topics. In Oxygen it does not seem to be necessary anymore.

The sources for this tutorial are hosted on GitHub in the already existing projects:

• DS Getting Started (PDE)
• DS Getting Started (Bndtools)

The PDE version also includes a sample project org.fipro.mafia.ui which is a very simple RCP application that shows the usage of the event handler in a view part.