Support free tutorials:











vogella training Training Books



Eclipse 4 event system (EventAdmin) - Tutorial

Building Eclipse RCP applications based on Eclipse 4

Lars Vogel

Version 6.2

03.07.2013

Revision History
Revision 0.1 14.02.2009 Lars
Vogel
created
Revision 0.2 - 6.2 16.02.2009 - 03.07.2013 Lars
Vogel
bug fixes and enhancements

Using the Eclipse event system within your application

This tutorial gives an overview about the event system of the Eclipse application platform.


Table of Contents

1. Prerequisites
2. Communication within your Eclipse application
2.1. Event based communication
2.2. Event service
2.3. Required plug-ins to use the event service
3. Sending and receiving events
3.1. Sending
3.2. Annotations for receiving events
3.3. Registering listeners for events
3.4. Subscribing to sub-topics
3.5. Eclipse framework events
4. Usage of the event system
5. Asynchronous processing and the event bus
6. Learn more about Eclipse 4 RCP development
7. Support free vogella tutorials
7.1. Thank you
7.2. Questions and Discussion
8. Links and Literature
8.1. Source Code

Get the book Eclipse IDE book

1. Prerequisites

The following assumes that you have already basic Eclipse RCP development experience. See the Eclipse RCP Tutorial for details. .

2. Communication within your Eclipse application

2.1. Event based communication

In your application you frequently have the need to communicate between application components. For example a software component updates your data model and needs to send the information about the update to all interested components.

For this purpose the Eclipse platform provides a global event based communication system, called the event bus. Software components can register for events and other components can send event notifications via the event bus.

Any software component which has access to the event system can send out arbitrary events as depicted in the following graphic.

Sending out events with an event broker

The Eclipse platform will make sure that registered components receive the messages. The Eclipse platform uses this event system for the internal communication.

2.2. Event service

The Eclipse framework provides the event service for event communication. This service can be accessed via dependency injection based on the IEventBroker interface. This communication service can also be used to communicate between your own application components.

The Eclipse event service is based on the OSGi EventAdmin service but has been wrapped with a simpler API.

2.3. Required plug-ins to use the event service

The following plug-ins are required to use the event service functionality:

  • org.eclipse.e4.core.services
  • org.eclipse.osgi.services

3. Sending and receiving events

3.1. Sending

The event service can be injected via dependency injection.

@Inject
private IEventBroker eventBroker; 

The following code examples assume that you have a class named MyEventConstants defined which contains a static final field (constant) for the TOPIC_TODO_NEW string.

The event service collects all events and sends them to the registered classes. This can be done asynchronously or synchronously.

@Inject IEventBroker broker;

...
// asynchronously
broker.post(MyEventConstants.TOPIC_TODO_NEW, "New data"); 

@Inject IEventBroker broker;
...
// synchronously sending a todo
// calling code is blocked until delivery
broker.send(MyEventConstants.TOPIC_TODO_NEW, todo); 

You can now send arbitrary Java objects or primitives through the event bus.

3.2. Annotations for receiving events

You can use dependency injection to register and respond to events. If dependency injection is used, the Eclipse framework automatically removes all event subscriptions when the model class is disposed.

The @EventTopic and @UIEventTopic annotations tag methods and fields that should be notified on event changes. The @UIEventTopic ensures the event notification is performed in the user interface thread.

// MyEventConstants.TOPIC_TODO_UPDATE is 
// a String constant

@Inject
@Optional
private void getNotified(@UIEventTopic(MyEventConstants.TOPIC_TODO_UPDATE) 
    String s) {
  if (viewer!=null) {
    viewer.setInput(model.getTodos());
  }
} 

3.3. Registering listeners for events

An object can also register an instance of the EventHandler directly with the IEventBroker interface via the subscribe() method.

Tip

Using dependency injection for subscribing should be preferred compared to the direct subscription as this way the framework handles the listener registration and de-registration automatically for you.

3.4. Subscribing to sub-topics

You can subscribe to specific topics or use wildcards to subscribe to all sub-events. Sub-events are separated by /. The following example code defines several topics and also the TOPIC_TODO_ALLTOPICS constant which can be used to register for all sub-events.

package com.example.e4.rcp.todo.events;

public interface MyEventConstants {
  
  public static final String TOPIC_TODO_ALLTOPICS = 
      "TOPIC_TODO/*";
  
  public static final String TOPIC_TODO_NEW = 
      "TOPIC_TODO/NEW";
  
  public static final String TOPIC_TODO_DELETE = 
      "TOPIC_TODO/DELETED";
  
  public static final String TOPIC_TODO_UPDATE = 
      "TOPIC_TODO/UPDATED";
} 

3.5. Eclipse framework events

It is also possible to register for Eclipse framework events. The UIEvents class from the org.eclipse.e4.ui.workbench contains all framework events. This class also contains information about the purpose of events in its Javadoc. The Eclipse framework sends out objects of type org.osgi.service.event.Event.

For example the UIEvents.UILifeCycle.APP_STARTUP_COMPLETE event is triggered once the application has started.

Another example is the UIEvents.UILifeCycle.ACTIVATE event which is triggered if a part is activated. Registering for this event is demonstrated in the following code snippet.

@Inject
@Optional
public void partActivation(@UIEventTopic(UIEvents.UILifeCycle.ACTIVATE) 
  Event event) {
  // do something
  System.out.println("Got Part");
} 

4. Usage of the event system

The IEventBroker is a global event bus and is unaware of the IEclipseContext hierarchy. The IEventBroker service supports sending event information without knowing who is receiving it. Interested classes can register for events without knowing who is going to provide them. This is known as the whiteboard pattern and this pattern supports the creation of very loosely coupled application components.

The disadvantage is that it is a global bus, i.e. there is no scoping of the events. Publishers have to ensure they provide enough information in the event for subscribers to discriminate and decide that the particular event is applicable to them.

5. Asynchronous processing and the event bus

Your threads can use the IEventBroker to send event data. Every listener will be automatically called and if you use the UIEventTopic annotation, this method is automatically called in the main thread.

private static final String UPDATE ="update";

// get the IEventBroker injected
@Inject
IEventBroker broker;

// somewhere in you code you do something 
// performance intensive

button.addSelectionListener(new SelectionAdapter() {
      @Override
      public void widgetSelected(SelectionEvent e) {
        Runnable runnable = new Runnable() {
          public void run() {
            for (int i = 0; i < 10; i++) {
              try {
                Thread.sleep(500);
              } catch (InterruptedException e) {
                e.printStackTrace();
              }
              // send out an event to update
              // the UI
              broker.send(UPDATE, i);
            }
          }
        };
        new Thread(runnable).start();
      }
    });



// more code
// ....


// get notified and sync automatically
// with the UI thread

@Inject @Optional
public void  getEvent(@UIEventTopic(UPDATE) int i) {
  // text1 is a SWT Text field
  text1.setText(String.valueOf(i));
  System.out.println(i);
} 

6. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book from this author.

7. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

7.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

7.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

8. Links and Literature

8.1. Source Code

Source Code of Examples

http://wiki.eclipse.org/E4 Eclipse E4 - Wiki

Wiki for the Event Model of Eclipse 4

Eclipse RCP

Eclipse EMF

Dependency Injection