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 either:

Some implementations of the Typed Event Service may support Type Safe Event classes that do not conform to these 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 rules for acceptable type safe event classes. 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

Typical Event Sources publish single events at irregular intervals. These event sources are best served by using the deliver methods on the TypedEventBus. Some Event Sources, however, produce bursts of events, or frequent, regular events to a topic. In these cases there can be overhead associated with validating the topic and security context each time an event is published.

A TypedEventPublisher is associated with a single topic which is set during creation. All events published using the TypedEventPublisher are delivered to that topic. A TypedEventPublisher can be obtained from the TypedEventBus using one of the createPublisher methods.

A TypedEventPublisher is AutoCloseable and the isOpen method may be used to determine whether it has been closed. Once closed the object may no longer be used to publish events, and all event delivery methods will throw IllegalStateException.

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

    public void sendEvents() {
    
        try(TypedEventPublisher<ExampleEvent> publisher 
                = bus.createPublisher("my/topic/name", ExampleEvent.class)) {
        
            for(int i = 0; i < 100; i++) {
                ExampleEvent event = new ExampleEvent();
                event.message = "The event is " + i;
                publisher.deliver(event);
            }
        }
    }
}

Because the topic for a TypedEventPublisher is defined at creation time the implementation may only validate it once. Also, the TypedEventBus implementation must check the caller's permission to publish to the topic during the call to createPublisher, but should not check it again for each delivery. Note that this means an Event Source must not share a TypedEventPublisher outside its own bundle.

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 including one or more wildcards.

@Component
@EventTopics("foo/+/foobar")
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"));
    }
}

@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"));
    }
}

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.

Event Handlers may be registered at any time, which can lead to ordering problems with respect to Event Sources publishing their first events. Specifically a late arriving Event Handler may miss the first message(s) from an early registering Event Source.

While this situation can be detected by the Event Source (for example by using an Unhandled Event Handler) or by the Event Handler (for example by using the TypedEventMonitor) doing so is relatively verbose.

In simple situations, such as watching the value of an irregularly updating Event Source, it is much easier for the Event Handler to have the last event(s) replayed to it before it starts receiving newly published events. This behaviour can be enabled using the TYPED_EVENT_HISTORY service property of the Event Handler.

The event.history property is of type Integer and must be greater than or equal to zero. The value of the property defines the maximum number of historical events that should be replayed to the Event Handler before normal event delivery begins. If the event.history property is not set then it should be assumed to have the value zero.

When the Typed Safe Events implementation detects the registration of an Event Handler service which has requested that one or more historical events should be replayed then it should follow the following non normative steps:

The above algorithm is intended to be illustrative rather than normative and it is expected that implementations will optimise their approaches.

As retaining history is an optional feature of the Type Safe Events implementation, and even where history is retained there may not be any history to replay, it is possible that there will be insufficient events to supply the number requested in event.history. This situation is not an error, and an Event Handler service must not require that any historical events are delivered to it. The only guarantee is that no more than event.history historical events will be delivered before normal event delivery commences.

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 four 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.

It is not usually the case that the history for every event topic is equally important. In fact for many topics history is unimportant, while for others it is highly desirable to keep a small number of historical messages indefinitely. To support this the Typed Event Service implementation allows for history storage to be configured on a per-topic basis, with a RangePolicy which defines both a minimum and maximum event requirement. The minimum requirement guarantees that at least the N most recent events are kept for the topic and will never be discarded in favour of events on other topics. The maximum requirement provides a ceiling on the number of events that will be kept in history for a given topic, ensuring that one busy topic does not dominate the whole history. The implementation is free to discard events between the minimum and maximum requirements at any time to manage its storage efficiently

As the primary means of accessing historical events the Typed Event Monitor service also provides the ability to introspect and customise the historical event storage.

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.1"

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.