A Type Safe Event is one in which the Event Schema is defined as a Java class. Using a Java class provides a formal definition of the schema - event data uses field names in the class as the keys, and each field definition defines the permitted type of the value.

Type Safe Event classes are expected to conform to OSGi DTO rules. The architecture of OSGi DTOs is described in OSGi Core Release 8. All methods, all static fields, and any non public instance fields of an event object must be ignored by the Typed Event Service when processing the Event data.

Some implementations of the Typed Event Service may support Type Safe Event classes that do not conform to the DTO rules, transforming them as needed in an implementation specific way. This is permitted by this specification, however consumers which rely on this behaviour may not be portable between different implementations of this specification.

An Untyped Event is one in which there is no Java class defining the Event Schema. In this case the event data is defined using a Map type with String keys and values limited to types acceptable as fields in a DTO, excepting:

Untyped Event instances are capable of representing exactly the same data as present in a Type Safe Event instance, and are also subject to the same restrictions, that is the data must be a tree. Nested data should be included as sub-maps within the event map, and these sub-maps may in turn contain nested data.

Some Event schemas may be represented by an existing type which does not match the OSGi DTO rules. In this case there are two main options:

For example, the following code demonstrates how an object following the JavaBeans pattern can be converted into a DTO type or an untyped map:

public class ExampleJavaBean {
    private String message;
    
    public String getMessage() { return message; }

    public void setMessage(String message) { this.message = message; }
}
      
public class ExampleEvent {
    public String message;
}
                       
@Component
public class ExampleEventSource {
    private ExampleEvent createEventFromJavaBean(ExampleJavaBean bean) {
        return Converters.standardConverter().convert(bean)
                .to(ExampleEvent.class);
    }
    
    private Map<String, Object> createMapFromJavaBean(ExampleJavaBean bean) {
        return Converters.standardConverter().convert(bean)
                .to(new TypeReference<Map<String, Object>>(){});
    }
}

The Typed Event Service is inherently multi-threaded. Events may be published from multiple threads, and event data may be delivered to consumers on multiple threads. Event Sources and Event Consumers must therefore assume that event data is shared between threads from the moment that it is first passed to the TypedEventBus.

Events are always published to a topic. The topic of an event defines the schema of the event. Topics exist in order to give Event Consumers information about the schema of the event, and the opportunity to register for just the events they are interested in. When a topic is designed, its name should not include any other information, such as the publisher of the event or the data associated with the event, those parts are intended to be stored in the event properties.

The topic therefore serves as a first-level filter for determining which handlers should receive the event. Typed Event service implementations use the structure of the topic to optimize the dispatching of the events to the handlers. The following example code demonstrates how to send an event to a topic.

public class ExampleEvent {
    public String message;
}         
            
@Component
public class ExampleEventSource {
    @Reference
    TypedEventBus bus;

    public void sendEvent() {
        ExampleEvent event = new ExampleEvent();
        event.message = "The time is " + LocalDateTime.now();

        bus.deliver("org/osgi/example/ExampleEvent", event);
    }
}

Topics are arranged in a hierarchical namespace. Each level is defined by a token and levels are separated by solidi ('/' \u002F). More precisely, the topic must conform to the following grammar:

// For further information see General Syntax Definitions in Core

topictoken  :: ( jletterordigit | '-' ) +
      
topic       ::= topictoken ( '/' topictoken ) *

Topics should be designed to become more specific when going from left to right. Consumers can provide a prefix that matches a topic, using the preferred order allows a handler to minimize the number of prefixes it needs to register.

Topics are case-sensitive. As a convention, topics should follow the reverse domain name scheme used by Java packages to guarantee uniqueness. The separator must be a solidus ('/' \u002F) instead of the full stop ('.' \u002E).

This specification uses the convention fully/qualified/package/ClassName/ACTION. If necessary, a pseudo-class-name is used.

In many cases the name of a topic contains no information other than defining the schema of the events sent on that topic. Therefore, when publishing a Typed Event to the Typed Event Bus, the Typed Event implementation is able to automatically generate a topic name based on the the type of the event object being published.

For the deliver(Object) method on the Typed Event Bus where no topic string is provided, the implementation must create a topic string using the fully qualified class name of the event object. To convert the class name into a valid topic the full stop . separators must be converted into solidus / separators. A non-normative example implementation follows:

public void deliver(Object event) {
    String topicName = event.getClass().getName().replace('.', '/');
    
    this.deliver(topicName, event);
}

The following example demonstrates how an Event Source can make use of an automatically generated topic name.

package org.osgi.example;

public class ExampleEvent {
    public String message;
}          
            
@Component
public class ExampleEventSource {
    @Reference
    TypedEventBus bus;

    public void sendEvent() {
        ExampleEvent event = new ExampleEvent();
        event.message = "The time is " + LocalDateTime.now();

        // This event will be delivered to the 
        // topic "org/osgi/example/ExampleEvent"
        bus.deliver(event);
    }
}

The TypedEventBus implementation must be thread safe and allow for simultaneous event publication from multiple threads. For any given source thread, events must be delivered in the same order as they were published by that thread. Events published by different threads, however, may be delivered in a different order from the one in which they were published.

For example, if thread A publishes events 1, 2 and 3, while thread B publishes events 4, 5 and 6, then the events may be delivered:

but events will never be delivered 1, 2, 6, 4, 5, 3

Typed Events are received by registering a TypedEventHandler implementation. This service has a single method notify which receives the String topic name and Object event data. The TypedEventHandler implementation must be registered as a service in the service registry using the TypedEventHandler interface.

The TypedEventHandler interface is parameterized, and so it is expected that the implementation reifies the type parameter into a specific type. In this case the Typed Event implementation must adapt the Event object into the type defined by the TypedEventHandler implementation. Implementations of this specification are free to choose their own adaptation mechanism, however it must guarantee at least the same functionality as Converter Specification.

A simple example of receiving a typed event follows:

public class ExampleEvent {
    public String message;
}         
            
@Component
public class ExampleTypedConsumer implements TypedEventHandler<ExampleEvent> {
    @Override
    public void notify(String topic, ExampleEvent event) {
        System.out.println("Received event: " + event.message);
    }
}

If the TypedEventHandler implementation is unable to reify the type, or the required type is more specific than the reified type, then the Typed Event Handler must be registered with the event.type service property. This property has a string value containing the fully-qualified type name of the type that the Typed Event Handler expects to receive. This type must be loaded by the Typed Event implementation using the classloader of the bundle which registered the Typed Event Handler service. The loaded type must then be used as the target type when converting events. For example:

public class ExampleEvent {
    public String message;
}
            
public class SpecialisedExampleEvent extends ExampleEvent {
    public int sequenceId = Integer.MIN_VALUE;
}
            
@Component
@EventType(SpecialisedExampleEvent.class)
public class ExampleTypedConsumer implements TypedEventHandler<ExampleEvent> {
    @Override
    public void notify(String topic, ExampleEvent event) {
        System.out.println("Received event: " + event.message);
        
        // The event will always be of type SpecialisedExampleEvent
        System.out.println("Event sequence id was " + 
            ((SpecialisedExampleEvent) event).sequenceId);
    }
}

By default the reified type of the TypedEventHandler will be used as the target topic for the Event Handler. If the event.type property is set then this is used as the default topic instead of the reified type. To use a specific named topic the Typed Event Handler service may be registered with an event.topics service property specifying the topic(s) as a String+ value.

public class ExampleEvent {
    public String message;
}
                       
@Component
@EventTopics({"foo", "foo/bar"})
public class ExampleTypedConsumer implements TypedEventHandler<ExampleEvent> {
    @Override
    public void notify(String topic, ExampleEvent event) {
        System.out.println("Event received on topic: " + topic + 
                " with message: " + event.message);
    }
}

Untyped Events are received by registering an UntypedEventHandler implementation. This service has a single method notifyUntyped which receives the String topic name and Map event data. The Untyped Event Handler implementation must be registered as a service in the service registry using the UntypedEventHandler interface.

When delivering an event to an Untyped Event Handler the Typed Event Service must, if necessary, convert the event data to a nested map structure.

The event.topics service property must be used when registering an Untyped Event Hander service. If it is not, then no events will be delivered to that Untyped Event Handler service.

public class ExampleEvent {
    public String message;
}
                       
@Component
@EventTopics({"foo", "foo/bar"})
public class ExampleUntypedConsumer implements UntypedEventHandler {
    @Override
    public void notifyUntyped(String topic, Map<String,Object> event) {
        System.out.println("Event received on topic: " + topic
                + " with message: " + event.get("message"));
    }
}

The event.topics property may contain one or more wildcard topics. These are Strings which contain a topic name and append “/*”. This value means that the Event Handler must be called for Events sent to sub-topics of the named topic. For example the component:

@Component
@EventTopics("foo/*")
public class ExampleUntypedConsumer implements UntypedEventHandler {
    @Override
    public void notifyUntyped(String topic, Map<String,Object> event) {
        System.out.println("Event received on topic: " + topic
                + " with message: " + event.get("message"));
    }
}

would receive events sent to the topics foo/bar and foo/baz, but not the topics foo or foobar/fizzbuzz.

The * character in a wildcard topic must always follow a solidus / character, and must be the final character in the topic string, meaning that topic names such as foo* and foo/*/bar are not valid. The only exception to this rule is that it is valid to use the topic name * to receive events on all topics. While it is valid to do so, using the topic * is not typically recommended. For a mechanism to monitor the events flowing through the system see Monitoring Events.

Unhandled Events are events sent by an Event Source but which have no Event Handler service listening to their topic. Rather than these events being discarded, the Typed Event implementation will search the service registry for services implementing UnhandledEventHandler.

If any services are found then the Typed Event implementation will call the notifyUnhandled method passing the topic name and event data to all of the registered Unhandled Event Handler services.

public class ExampleEvent {
    public String message;
}
                       
@Component
public class ExampleUnhandledConsumer implements UnhandledEventHandler {
    @Override
    public void notifyUnhandled(String topic, Map<String,Object> event) {
        System.out.println("Unhandled Event received on topic: " + topic);
    }
}

Sometimes the use of a topic is insufficient to restrict the events received by an event consumer. In these cases the consumer can further restrict the events that they receive by using a filter. The filter is supplied using the event.filter service property, the value of which is an LDAP filter string. This filter is applied to the event data, and only events which match the filter are delivered to the event handler service.

Event Handler implementations are called by the Typed Event Bus implementation, and are expected:

If a Typed Event Bus implementation detects an Event Handler that is behaving incorrectly, either by throwing exceptions, or by taking a long time to process the event, or some other problem, then the implementation may block further event delivery to that Event Handler.

If an Event Handler is blocked by the event implementation then this situation must be logged. Also, if a blocked Event Handler service is updated then the block must be removed by the implementation. If the updated service continues to behave incorrectly then the block may be reinstated.

The service properties that can be used to configure an Event Handler service are outlined in the following table.

There are several possible error scenarios for Event Handlers:

It is not possible to know that an Event cannot be delivered until delivery is attempted. It is therefore not possible (or acceptable, given the asynchronous nature of delivery) to throw an exception to the sender of an event if there are problems delivering the event. The Event Bus service should not throw exceptions from any publication methods except:

In a running system it is often useful for monitoring tools to replay recent data immediately after a problem has occurred. For that reason Typed Event Monitor instances may store past events so that they can be replayed if requested. There are two monitorEvents methods capable of replaying history:

Note that storing Event History is considered a best-effort option and it is not required that the implementation supply the full set of requested events. If insufficient past events are available then the implementation must provide the maximum amount of history available.

The Typed Event implementation bundle must provide the osgi.implementation capability with the name TYPED_EVENT_IMPLEMENTATION. This capability can be used by provisioning tools and during resolution to ensure that a Typed Event implementation is present. The capability must also declare a uses constraint for the org.osgi.service.typedevent package and provide the version of this specification:

Provide-Capability: osgi.implementation;
 osgi.implementation="osgi.typedevent";
 uses:="org.osgi.service.typedevent";
 version:Version="1.0"

The RequireTypedEvent annotation can be used to require this capability.

This capability must follow the rules defined for the osgi.implementation Namespace.

The bundle providing the Typed Event Bus service must provide capabilities in the osgi.service namespace representing the services it is required to register. This capability must also declare uses constraints for the relevant service packages:

Provide-Capability: osgi.service;
 objectClass:List<String>="org.osgi.service.typedevent.TypedEventBus";
 uses:="org.osgi.service.typedevent",
 osgi.service;
 objectClass:List<String>="org.osgi.service.typedevent.monitor.TypedEventMonitor";
 uses:="org.osgi.service.typedevent.monitor"

This capability must follow the rules defined for the osgi.service Namespace.

The TopicPermission class allows fine-grained control over which bundles may post events to a given topic and which bundles may receive those events.

The target parameter for the permission is the topic name. TopicPermission classes uses a wildcard matching algorithm similar to the BasicPermission class, except that solidi ('/' \u002F) are used as separators instead of full stop characters. For example, a name of a/b/* implies a/b/c but not x/y/z or a/b.

There are two available actions: PUBLISH and SUBSCRIBE. These control a bundle's ability to either publish or receive events, respectively. Neither one implies the other.

Bundles that need to consume events must be granted permission to register the appropriate handler service. For Example: ServicePermission[org.osgi.service.typedevent.TypedEventHandler, REGISTER] or ServicePermission[org.osgi.service.typedevent.UntypedEventHandler, REGISTER] or ServicePermission[org.osgi.service.typedevent.UnhandledEventHandler, REGISTER]. In addition, bundles that consume events require TopicPermission[ <topic>, SUBSCRIBE ] for each topic they want to be notified about.

Bundles that need to publish events must be granted permission to get the TypedEventBus service, that is ServicePermission[ org.osgi.service.typedevent.TypedEventBus, GET] so that they may retrieve the Typed Event Bus and use it. In addition, event sources require TopicPermission[ <topic>, PUBLISH] for each topic they want to send events to. This includes any default topic names that are used when publishing

Bundles that need to monitor events flowing through the bus must be granted permission to get the TypedEventMonitor service, that is ServicePermission[ org.osgi.service.typedevent.monitor.TypedEventMonitor, GET] so that they may retrieve the Typed Event Monitor and use it.

Only a bundle that provides a Typed Event implementation should be granted ServicePermission[ org.osgi.service.typedevent.TypedEventBus, REGISTER] and ServicePermission[ org.osgi.service.typedevent.monitor.TypedEventMonitor, REGISTER] to register the services defined by this specification.

The Typed Event implementation must be granted ServicePermission[org.osgi.service.typedevent.TypedEventHandler, GET], ServicePermission[org.osgi.service.typedevent.UntypedEventHandler, GET], ServicePermission[org.osgi.service.typedevent.UnhandledEventHandler, GET], ServicePermission[org.osgi.service.typedevent.TypedEventBus, REGISTER] and ServicePermission[org.osgi.service.typedevent.monitor.TypedEventMonitor, REGISTER] as these actions are all required to implement the specification.

During an event notification, the Typed Event implementation's Protection Domain will be on the stack above the handler's Protection Domain. Therefore, if a handler needs to perform a secure operation using its own privileges, it must invoke the doPrivileged method to isolate its security context from that of its caller.

The event delivery mechanism must not wrap event notifications in a doPrivileged call.