Event Admin Bundle

The Event Admin bundle implements the OSGi Event Admin Service Specification from the OSGi Service Platform Service Compendium. It uses an inter-bundle communication mechanism to simplify sending and receiving of events between bundles.

Contents:

• Bundle Information
  • Bundle JAR
  • Import
  • Export
• Services
• Event Admin Service
  • Overview
  • Events
  • Publishing Events
  • Subscribing to Events
• Managed Service Factory
• Event Pool Utility
• Configuration
• Configuration Resources
• Visual Administration
• System Properties
• References

Bundle Information

Bundle JAR

The JAR file of the Event Admin bundle is eventadmin.jar, and is located in the bundles folder.

Import

The Event Admin bundle imports the following packages:

Export

The Event Admin bundle does not export any packages.

Services

Event Admin Service

Overview

The Event Admin service provides a publish-subscribe model for handling events. It is realized according to the OSGi Event Admin Service Specification.

The Event Admin service dispatches events between Event Publishers and Event Subscribers (Event Handlers) by interposing an event channel. Publishers post events to the channel and the event channel defines which handlers needs to be notified. Thus publishers and handlers have no direct knowledge of each other, which simplifies event management.

Figure 1: Event Admin Architecture.

The Event Admin service can have multiple instances. Creating a configuration instance from the FPID mbs.eventadmin.factory.pid configuration factory and a custom Event Admin service is registered with specific service properties. Retrieve the custom Event Admin service from the OSGi framework using the same custom service properties. See the "Configuration Resources" section for more information about creating custom Event Admin services.

Events

An event is represented by an org.osgi.service.event.Event object. It has two attributes: topic and properties. Topics define the type of the event and are used for matching the event with the appropriate Event Handler. They are case-sensitive and are used as a service registration property by the Event Handlers. The properties attribute provides information about the actual event. Its name is a case-sensitive String and its value can be any object.

There are two ways in which events can be delivered: synchronous and asynchronous.

When a synchronous event publishing is used, the Event Admin service finds all Event Handlers subscribed to the topic of this event object and notifies each one in turn. After each interested Event Handler is successfully notified of the event, the method returns to the Event Publisher.

Asynchronous event publishing is used in case it is irrelevant for the Event Publisher when the Event Handlers will receive and process a specific event. The Event Admin service determines which Event Handlers have been registered for the specified topic at the time the event has been posted. Then each Event Subscriber receives notifications for the events in the order in which they have been posted.

Publishing Events

To use this service, an Event Publisher must retrieve the Event Admin service. Create an event object with two attributes - topic and properties. The topic specifies the action which Event Handlers are interested in. Additional information about the event is provided as properties.

To publish events synchronously, call the sendEvent(Event) method from the org.osgi.service.event.EventAdmin interface. To post events in an asynchronous manner, invoke the the postEvent(Event) method of the org.osgi.service.event.EventAdmin interface.

The example that follows delivers events using the sendEvent(Event) method of the org.osgi.service.event.EventAdmin interface. This method initiates a synchronous delivery of events and does not return to the caller until the event delivery is successfully completed.

import java.util.Hashtable;
	
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.BundleException;
import org.osgi.framework.ServiceEvent;
import org.osgi.framework.ServiceListener;
import org.osgi.framework.ServiceReference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventAdmin;
	
public class EventPublisher extends Thread implements BundleActivator,
  ServiceListener{
	
  private BundleContext bcontext= null;
  ServiceReference sr = null;
  EventAdmin ea = null;
  Event event = null;
  Hashtable properties = null;
  boolean sending = true;
      
  public void start(BundleContext bc) throws Exception {
    this.bcontext = bc;
	   
    // Adding the ServiceListener 
    bc.addServiceListener(this);
	   
    // Retrieving the Event Admin service from the OSGi framework
    sr = bc.getServiceReference(EventAdmin.class.getName());
      if (sr == null){
      throw new Exception("Failed to obtain EventAdmin service reference!");
      }
    ea = (EventAdmin) bc.getService(sr);
      if (ea == null) {
      throw new Exception("Failed to obtain EventAdmin service object!");
      }
    start();
  }


  public void run() {
    while(sending){
      if(ea != null){
        properties = new Hashtable();
        properties.put(EventConstants.BUNDLE_SYMBOLICNAME, "test.first");
		 
        // Creating and firing events with topic
        // "org/osgi/framework/BundleEvent/STARTED" every 2 seconds
        event = new Event("org/osgi/framework/BundleEvent/STARTED", properties);
        ea.sendEvent(new Event(event);
          try {
            Thread.sleep(2000);
          } catch(InterruptedException ie) {}
      }
    }
  }
    
  public void stop(BundleContext bc) throws Exception {
    bc.ungetService(sr);
    sending = false;
    bc.removeServiceListener(this);
  }
	
  // Method inherited from the ServiceListener interface
  public void serviceChanged(ServiceEvent se){
	
    // Stops the bundle sending events when the Event Admin service 
    // is no more obtainable.
    if ((se.getServiceReference() == sr) && 
      (se.getType() == ServiceEvent.UNREGISTERING)){
        try{
          bc.getBundle().stop();
        } catch(BundleException be){}
      }
    }
  }
	  

Subscribing to Events

Event Subscribers must be registered as services under the org.osgi.service.event.EventHandler interface. They must have a service property org.osgi.service.event.EventConstants.EVENT_TOPIC ("event.topic") describing the event topics which the corrresponding Event Handler is interested in. It takes String [] values. Subscribers may also be registered with org.osgi.service.event.EventConstants.EVENT_FILTER ("event.filter") service property.

The example that follows receives events through the OSGi Event Admin service from the Event Publisher, shown in Listing 1.The example subscribes to Bundle events with a level of STARTED as indicated by the value of the handler's EventConstants.EVENT_TOPIC registration property. The handler additionally narrows the events of interest to events about bundles with symbolic name starting with "test", as indicated by the EventConstants.EVENT_FILTER property.

import java.util.Dictionary;
import java.util.Hashtable;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventConstants;
import org.osgi.service.event.EventHandler;

public class EventHandler implements EventHandler, BundleActivator {

  final static String[] topic = { "org/osgi/framework/BundleEvent/STARTED" };
  String filter = "(bundle.symbolicName=test.*)";
  ServiceRegistration register;

  public void start(BundleContext bc) throws Exception {
    Dictionary dict = new Hashtable();
    dict.put(EventConstants.EVENT_TOPIC, topic);
    dict.put(EventConstants.EVENT_FILTER, filter);
	
    // Registering the EventHandler
    register = bc.registerService(EventHandler.class.getName(), this, dict);
  }

  public void stop(BundleContext bc) throws Exception {
    register.unregister();
  }
  
  // Method inherited from the EventHandler interface
  public void handleEvent(Event e) {
  // Do something with the received events
                   ...         
  }
}
	  

Managed Service Factory

The Event Admin bundle registers the org.osgi.service.cm.ManagedServiceFactory service in the framework with FPID mbs.eventadmin.factory.pid. This allows the bundle to store configuration properties through the OSGi Configuration Admin service registered by the Config Bundle . The properties can be easily managed through the config console commands or through the property editor in mConsole. See the "Configuration" section for full information about the Event Admin configuration properties.

Event Pool Utility

The event pool utility, org.mbs.eventadmin.EventPool, provides a pool of reusable event objects. Each event instance is associated with an EventLocker object to avoid event "stealing". To obtain an event from the pool:

1. Implement the org.mbs.eventadmin.EventLocker interface.
2. Call the getEvent(String, Dictionary, EventLocker) method passing as parameters the event topic and properties and the EventLocker instance.

When the event object is no longer needed, invoke the releaseEvent(Event, EventLocker) method to release it, if synchronous event delivery is used. Call the allPostFinish(Event) method before releasing the event objects, in case asynchronous event delivery is used. See "Events" for more information about dispatching events in a synchronous and asynchronous manner.

Configuration

Configuration Resources

The Event Admin bundle stores configurable properties in the OSGi Configuration Admin. The bundle provides a configuration factory under FPID mbs.eventadmin.factory.pid.Creating another configuration instance from the factory can result in creating an instance of the OSGi Event Admin Service (depending on the value of the isMain configuration property). This service can be allocated specially for custom events depending on the system requirements.

Visual Administration

User-friendly visual administration on the Event Admin bundle is performed through the mConsole application and its general property editor. You can modify the main parameters of a separate configuration though the Event Admin property editor. To activate it :

1. Start ProSyst mBS and make sure it is on before continuing.
2. Start mConsole and log in mBS.
3. Locate the Event Admin bundle node which is within the osgi category in the bundle tree and unfold it.
4. Go to the EventAdmin node which stands for the mbs.eventadmin.factory.pid configuration factory.

Figure 1: Event Admin service properties.

The configuration of the Event Admin bundle is managed through the ManagedServiceFactory service. The configuration dictionaries of the Event Admin bundle configuration factory are shown in the general property editor. You may edit the attributes included in a single configuration by using the Edit button. See "Working with the General Property Editor" chapter in the "OSGi Framework Administration through mConsole" document for more information about editing configurations.

To enforce the changes you have made to the configuration properties, click the Set button. The Refresh button updates the configuration information in case another administrator has made changes meanwhile.

System Properties

The Event Admin service uses the following system properties:

References

• OSGi Service Platform Service Compendium, Release 4
• OSGi Event Admin Service Specification API
• ProSyst Event Pool API

OSGi Bundles