Nearly all the bundles in an OSGi framework must deal with events, either as an event publisher or as an event handler. So far, the preferred mechanism to disperse those events have been the service interface mechanism.
Dispatching events for a design related to X, usually involves a
service of type XListener
. However, this model does not scale
well for fine grained events that must be dispatched to many different
handlers. Additionally, the dynamic nature of the OSGi environment
introduces several complexities because both event publishers and event
handlers can appear and disappear at any time.
The Event Admin service provides an inter-bundle communication mechanism. It is based on a event publish and subscribe model, popular in many message based systems.
This specification defines the details for the participants in this event model.
-
Simplifications - The model must significantly simplify the process of programming an event source and an event handler.
-
Dependencies - Handle the myriad of dependencies between event sources and event handlers for proper cleanup.
-
Synchronicity - It must be possible to deliver events asynchronously or synchronously with the caller.
-
Event Window - Only event handlers that are active when an event is published must receive this event, handlers that register later must not see the event.
-
Performance - The event mechanism must impose minimal overhead in delivering events.
-
Selectivity - Event listeners must only receive notifications for the event types for which they are interested
-
Reliability - The Event Admin must ensure that events continue to be delivered regardless the quality of the event handlers.
-
Security - Publishing and receiving events are sensitive operations that must be protected per event type.
-
Extensibility - It must be possible to define new event types with their own data types.
-
Native Code - Events must be able to be passed to native code or come from native code.
-
OSGi Events - The OSGi Framework, as well as a number of OSGi services, already have number of its own events defined. For uniformity of processing, these have to be mapped into generic event types.
-
Event - An
Event
object has a topic and aDictionary
object that contains the event properties. It is an immutable object. -
Event Admin - The service that provides the publish and subscribe model to Event Handlers and Event Publishers.
-
Event Handler - A service that receives and handles
Event
objects. -
Event Publisher - A bundle that sends event through the Event Admin service.
-
Event Subscriber - Another name for an Event Handler.
-
Topic - The name of an Event type.
-
Event Properties - The set of properties that is associated with an Event.
The Event Admin service provides a place for bundles to publish events, regardless of their destination. It is also used by Event Handlers to subscribe to specific types of events.
Events are published under a topic, together with a number of event properties. Event Handlers can specify a filter to control the Events they receive on a very fine grained basis.
-
Architects - The Event Admin Architecture provides an overview of the Event Admin service.
-
Event Publishers - The Event Publisher provides an introduction of how to write an Event Publisher. The Event Admin Architecture provides a good overview of the design.
-
Event Subscribers/Handlers - The Event Handler provides the rules on how to subscribe and handle events.
The Event Admin is based on the Publish-Subscribe pattern. This pattern decouples sources from their handlers by interposing an event channel between them. The publisher posts events to the channel, which identifies which handlers need to be notified and then takes care of the notification process. This model is depicted in Figure 113.2.
In this model, the event source and event handler are completely decoupled because neither has any direct knowledge of the other. The complicated logic of monitoring changes in the event publishers and event handlers is completely contained within the event channel. This is highly advantageous in an OSGi environment because it simplifies the process of both sending and receiving events.
Events have the following attributes:
-
Topic - A topic that defines what happened. For example, when a bundle is started an event is published that has a topic of
org/osgi/framework/BundleEvent/STARTED
. -
Properties - Zero or more properties that contain additional information about the event. For example, the previous example event has a property of
bundle.id
which is set to aLong
object, among other properties.
The topic of an event defines the type of the event. It is fairly granular in order to give handlers 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 is intended to serve as a first-level filter for determining which handlers should receive the event. Event Admin service implementations use the structure of the topic to optimize the dispatching of the events to the handlers.
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:
topic ::= token ( '/' token ) * // See General Syntax Definitions in Core
Topics should be designed to become more specific when going from left to right. Handlers 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.
Information about the actual event is provided as properties. The
property name is a case-sensitive string and the value can be any
object. Although any Java object can be used as a property value, only
String
objects and the eight primitive types (plus their
wrappers) should be used. Other types cannot be passed to handlers that
reside external from the Java VM.
Another reason that arbitrary classes should not be used is the mutability of objects. If the values are not immutable, then any handler that receives the event could change the value. Any handlers that received the event subsequently would see the altered value and not the value as it was when the event was sent.
The topic of the event is available as a property with the key EVENT_TOPIC. This allows filters to include the topic as a condition if necessary.
An event processing system can become a bottleneck in large systems. One expensive aspect of the Event object is its properties and its immutability. This combination requires the Event object to create a copy of the properties for each object. There are many situations where the same properties are dispatched through Event Admin, the topic is then used to signal the information. Creating the copy of the properties can therefore take unnecessary CPU time and memory. However, the immutability of the Event object requires the properties to be immutable.
For this reason, this specification also provides an immutable Map with the Event Properties class. This class implements an immutable map that is recognized and trusted by the Event object to not mutate. Using an Event Properties object allows a client to create many different Event objects with different topics but sharing the same properties object.
The following example shows how an event poster can limit the copying of the properties.
void foo(EventAdmin eventAdmin) {
Map<String,Object> props = new HashMap<String,Object>();
props.put("foo", 1);
EventProperties eventProps = new EventProperties( props);
for ( int i=0; i<1000; i++)
eventAdmin.postEvent( new Event( "my/topic/" + i, eventProps));
}
Event handlers must be registered as services with the OSGi
framework under the object class
org.osgi.service.event.EventHandler
.
Event handlers should be registered with a property (constant from
the EventConstants
class) EVENT_TOPIC. The value being a String
,
String[]
or Collection<String>
object that
describes which topics the handler is interested in.
A wildcard asterisk ('*' \u002A
) may be used as the last
token of a topic name, for example com/action/*
. This matches
any topic that shares the same first tokens. For example,
com/action/*
matches com/action/listen
.
Event Handlers which have not specified the EVENT_TOPIC service property must not receive events.
The value of each entry in the EVENT_TOPIC service registration property must conform to the following grammar:
topic-scope ::= '*' | ( topic '/*'? )
The EventTopics component property type can be used for this property on Declarative Services components.
Event handlers can also be registered with a service property named EVENT_FILTER. The value of this property must be a string containing a Framework filter specification. Any of the event's properties can be used in the filter expression.
event-filter ::= filter // See Filter Syntax in Core
Each Event Handler is notified for any event which belongs to the topics the handler has expressed an interest in. If the handler has defined a EVENT_FILTER service property then the event properties must also match the filter expression. If the filter is an error, then the Event Admin service should log a warning and further ignore the Event Handler. The EventFilter component property type can be used for this property on Declarative Services components.
For example, a bundle wants to see all Log Service events with a
level of WARNING
or ERROR
, but it must ignore
the INFO
and DEBUG
events. Additionally, the
only events of interest are when the bundle symbolic name starts with
com.acme
.
public AcmeWatchDog implements BundleActivator,
EventHandler {
final static String [] topics = new String[] {
"org/osgi/service/log/LogEntry/LOG_WARNING",
"org/osgi/service/log/LogEntry/LOG_ERROR" };
public void start(BundleContext context) {
Dictionary d = new Hashtable();
d.put(EventConstants.EVENT_TOPIC, topics );
d.put(EventConstants.EVENT_FILTER,
"(bundle.symbolicName=com.acme.*)" );
context.registerService( EventHandler.class.getName(),
this, d );
}
public void stop( BundleContext context) {}
public void handleEvent(Event event ) {
//...
}
}
If there are multiple Event Admin services registered with the Framework then all Event Admin services must send their published events to all registered Event Handlers.
In the default case, an Event Handler will receive posted (asynchronous) events from a single thread in the same order as they were posted. Maintaining this ordering guarantee requires the Event Admin to serialize the delivery of events instead of, for example, delivering the events on different worker threads. There are many scenarios where this ordering is not really required. For this reason, an Event Handler can signal to the Event Admin that events can be delivered out of order. This is notified with the EVENT_DELIVERY service property. This service property can be used in the following way:
-
Not set or set to both - The Event Admin must deliver the events in the proper order.
-
DELIVERY_ASYNC_ORDERED - Events must be delivered in order.
-
DELIVERY_ASYNC_UNORDERED - Allow the events to be delivered in any order.
The EventDelivery component property type can be used for this property on Declarative Services components.
To fire an event, the event source must retrieve the Event Admin service from the OSGi service registry. Then it creates the event object and calls one of the Event Admin service's methods to fire the event either synchronously or asynchronously.
The following example is a class that publishes a time event every 60 seconds.
public class TimerEvent extends Thread
implements BundleActivator {
Hashtable time = new Hashtable();
ServiceTracker tracker;
public TimerEvent() { super("TimerEvent"); }
public void start(BundleContext context ) {
tracker = new ServiceTracker(context,
EventAdmin.class.getName(), null );
tracker.open();
start();
}
public void stop( BundleContext context ) {
interrupt();
tracker.close();
}
public void run() {
while ( ! Thread.interrupted() ) try {
Calendar c = Calendar.getInstance();
set(c,Calendar.MINUTE,"minutes");
set(c,Calendar.HOUR,"hours");
set(c,Calendar.DAY_OF_MONTH,"day");
set(c,Calendar.MONTH,"month");
set(c,Calendar.YEAR,"year");
EventAdmin ea =
(EventAdmin) tracker.getService();
if ( ea != null )
ea.sendEvent(new Event("com/acme/timer",
time ));
Thread.sleep(60000-c.get(Calendar.SECOND)*1000);
} catch( InterruptedException e ) {
return;
}
}
void set( Calendar c, int field, String key ) {
time.put( key, new Integer(c.get(field)) );
}
}
Some handlers are more interested in the contents of an event rather than what actually happened. For example, a handler wants to be notified whenever an Exception is thrown anywhere in the system. Both Framework Events and Log Entry events may contain an exception that would be of interest to this hypothetical handler. If both Framework Events and Log Entries use the same property names then the handler can access the Exception in exactly the same way. If some future event type follows the same conventions then the handler can receive and process the new event type even though it had no knowledge of it when it was compiled.
The following properties are suggested as conventions. When new
event types are defined they should use these names with the
corresponding types and values where appropriate. These values should be
set only if they are not null
A list of these property names can be found in the following table.
Table 113.1 General property names for events
Name | Type | Notes |
---|---|---|
String | Collection <String> |
A bundle's signers DN |
|
Version |
A bundle's version |
|
String |
A bundle's symbolic name |
|
Object |
The actual event object. Used when rebroadcasting an event that was sent via some other event mechanism |
|
Throwable |
An exception or error |
|
String |
Must be equal to
|
|
String |
Must be equal to the name of the
|
|
String |
A human-readable message that is usually not localized. |
|
Service Reference |
A Service Reference |
|
Long |
A service's id |
|
String[] |
A service's |
|
String | Collection <String> |
A service's persistent identity. A PID that is
specified with a |
|
Long |
The time when the event occurred, as reported by
|
The topic of an OSGi event is constructed by taking the fully
qualified name of the event class, substituting a solidus ('/'
\u002F
)for every full stop, and appending a solidus followed by
the name of the constant that defines the event type. For example, the
topic of
BundleEvent.STARTED
Event becomes
org/osgi/framework/BundleEvent/STARTED
If a type code for the event is unknown then the event must be ignored.
In order to present a consistent view of all the events occurring in the system, the existing Framework-level events are mapped to the Event Admin's publish-subscribe model. This allows event subscribers to treat framework events exactly the same as other events.
It is the responsibility of the Event Admin service implementation to map these Framework events to its queue.
The properties associated with the event depends on its class as outlined in the following sections.
Framework Events must be delivered asynchronously with a topic of:
org/osgi/framework/FrameworkEvent/<eventtype>
The following event types are supported:
STARTED
ERROR
PACKAGES_REFRESHED
STARTLEVEL_CHANGED
WARNING
INFO
Other events are ignored, no event will be send by the Event Admin. The following event properties must be set for a Framework Event.
-
event
- (FrameworkEvent
) The original event object.
If the FrameworkEvent getBundle
method returns a
non-null
value, the following fields must be set:
-
bundle.id - (Long
) The source's bundle id. -
bundle.symbolicName
- (String)
The source bundle's symbolic name. Only set if the bundle's symbolic name is notnull
. -
bundle.version
-(Version)
The version of the bundle, if set. -
bundle.signer
-(String|Collection<String>)
The DNs of the signers. -
bundle
- (Bundle
) The source bundle.
If the FrameworkEvent
getThrowable
method returns a non-null
value:
-
exception.class
- (String
) The fully-qualified class name of the attached Exception. -
exception.message
-(String)
The message of the attached exception. Only set if the Exception message is notnull
. -
exception
- (Throwable) The Exception returned by thegetThrowable
method.
Framework Events must be delivered asynchronously with a topic of:
org/osgi/framework/BundleEvent/<event type>
The following event types are supported:
INSTALLED
STARTED
STOPPED
UPDATED
UNINSTALLED
RESOLVED
UNRESOLVED
Unknown events must be ignored.
The following event properties must be set for a Bundle Event. If listeners require synchronous delivery then they should register a Synchronous Bundle Listener with the Framework.
-
event
- (BundleEvent
) The original event object. -
bundle.id - (Long
) The source's bundle id. -
bundle.symbolicName
- (String)
The source bundle's symbolic name. Only set if the bundle's symbolic name is notnull
. -
bundle.version
-(Version)
The version of the bundle, if set. -
bundle.signer
-(String|Collection<String>)
The DNs of the signers. -
bundle
- (Bundle
) The source bundle.
Service Events must be delivered asynchronously with the topic:
org/osgi/framework/ServiceEvent/<eventtype>
The following event types are supported:
REGISTERED
MODIFIED
UNREGISTERING
Unknown events must be ignored.
-
event
- (ServiceEvent
) The original Service Event object. -
service
- (ServiceReference
) The result of thegetServiceReference
method -
service.id
- (Long
) The service's ID. -
service.pid
- (String or Collection<String>
) The service's persistent identity. Only set if notnull
. If the PID is specified as aString[]
then it must be coerced into aCollection<String>
. -
service.objectClass
- (String[]
) The service's object class.
Several OSGi service specifications define their own event model. It is the responsibility of these services to map their events to Event Admin events. Event Admin is seen as a core service that will be present in most devices. However, if there is no Event Admin service present, applications are not mandated to buffer events.
The Event Admin service must be registered as a service with the
object class org.osgi.service.event.EventAdmin
. Multiple
Event Admin services can be registered. Publishers should publish their
event on the Event Admin service with the highest value for the
SERVICE_RANKING
service property. This is the service
selected by the getServiceReference
method.
The Event Admin service is responsible for tracking the registered handlers, handling event notifications and providing at least one thread for asynchronous event delivery.
Synchronous event delivery is initiated by the
sendEvent
method. When this method is invoked, the Event
Admin service determines which handlers must be notified of the event
and then notifies each one in turn. The handlers can be notified in the
caller's thread or in an event-delivery thread, depending on the
implementation. In either case, all notifications must be completely
handled before the sendEvent
method returns to the
caller.
Synchronous event delivery is significantly more expensive than asynchronous delivery. All things considered equal, the asynchronous delivery should be preferred over the synchronous delivery.
Callers of this method will need to be coded defensively and
assume that synchronous event notifications could be handled in a
separate thread. That entails that they must not be holding any monitors
when they invoke the sendEvent
method. Otherwise they
significantly increase the likelihood of deadlocks because Java monitors
are not reentrant from another thread by definition. Not holding
monitors is good practice even when the event is dispatched in the same
thread.
Asynchronous event delivery is initiated by the
postEvent
method. When this method is invoked, the Event
Admin service must determine which handlers are interested in the event.
By collecting this list of handlers during the method invocation, the
Event Admin service ensures that only handlers that were registered at
the time the event was posted will receive the event notification. This
is the same as described in Delivering Events of
OSGi Core Release 8.
The Event Admin service can use more than one thread to deliver
events. If it does then it must guarantee that each handler receives the
events in the same order as the events were posted, unless this handler
allows unordered deliver, see Ordering. This ensures
that handlers see events in their expected order. For example, for some
handlers it would be an error to see a destroyed
event
before the corresponding created
event.
Before notifying each handler, the event delivery thread must ensure that the handler is still registered in the service registry. If it has been unregistered then the handler must not be notified.
Asynchronous events are delivered in the order in which they arrive in the event queue. Thus if two events are posted by the same thread then they will be delivered in the same order (though other events may come between them). However, if two or more events are posted by different threads then the order in which they arrive in the queue (and therefore the order in which they are delivered) will depend very much on subtle timing issues. The event delivery system cannot make any guarantees in this case. An Event Handler can indicate that the ordering is not relevant, allowing the Event Admin to more aggressively parallelize the event deliver, see Ordering.
Synchronous events are delivered as soon as they are sent. If two events are sent by the same thread, one after the other, then they must be guaranteed to be processed serially and in the same order. However, if two events are sent by different threads then no guarantees can be made. The events can be processed in parallel or serially, depending on whether or not the Event Admin service dispatches synchronous events in the caller's thread or in a separate thread.
Note that if the actions of a handler trigger a synchronous event, then the delivery of the first event will be paused and delivery of the second event will begin. Once delivery of the second event has completed, delivery of the first event will resume. Thus some handlers may observe the second event before they observe the first one.
If a handler throws an Exception during delivery of an event, it must be caught by the Event Admin service and handled in some implementation specific way. If a Log Service is available the exception should be logged. Once the exception has been caught and dealt with, the event delivery must continue with the next handlers to be notified, if any.
As the Log Service can also forward events through the Event Admin service there is a potential for a loop when an event is reported to the Log Service.
Event handlers should not spend too long in the
handleEvent
method. Doing so will prevent other handlers in
the system from being notified. If a handler needs to do something that
can take a while, it should do it in a different thread.
An event admin implementation can attempt to detect stalled or deadlocked handlers and deal with them appropriately. Exactly how it deals with this situation is left as implementation specific. One allowed implementation is to mark the current event delivery thread as invalid and spawn a new event delivery thread. Event delivery must resume with the next handler to be notified.
Implementations can choose to deny list any handlers that they determine are misbehaving. Deny listed handlers must not be notified of any events. If a handler is deny listed, the event admin should log a message that explains the reason for it.
Implementations of the Event Admin service can support passing events to, and/or receiving events from native applications.
If the implementation supports native interoperability, it must be able to pass the topic of the event and its properties to/from native code. Implementations must be able to support property values of the following types:
-
String
objects, including full Unicode support -
Integer, Long, Byte, Short, Float, Double, Boolean, Character
objects -
Single-dimension arrays of the above types (including
String
) -
Single-dimension arrays of Java's eight primitive types (
int, long, byte, short, float, double, boolean, char
)
Implementations can support additional types. Property values of unsupported types must be silently discarded.
The Event Admin implementation bundle must provide the osgi.implementation
capability with the name EVENT_ADMIN_IMPLEMENTATION. This capability can be used by provisioning
tools and during resolution to ensure that an Event Admin implementation
is present. The capability must also declare a uses constraint for the
org.osgi.service.event
package and provide the version of
this specification:
Provide-Capability: osgi.implementation;
osgi.implementation="osgi.event";
uses:="org.osgi.service.event";
version:Version="1.4"
The RequireEventAdmin annotation can be used to require this capability.
This capability must follow the rules defined for the osgi.implementation Namespace.
The bundle providing the Event Admin service must provide a
capability in the osgi.service
namespace representing this service. This capability must also declare a
uses constraint for the org.osgi.service.event
package:
Provide-Capability: osgi.service;
objectClass:List<String>="org.osgi.service.event.EventAdmin";
uses:="org.osgi.service.event"
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 register an event handler must be granted
ServicePermission
[org.osgi.service.event.EventHandler
,
REGISTER
]. In addition, handlers require
TopicPermission[ <topic>, SUBSCRIBE ]
for each topic
they want to be notified about.
Bundles that need to publish an event must be granted
ServicePermission[ org.osgi.service.event.EventAdmin, GET]
so that they may retrieve the Event Admin service and use it. In
addition, event sources require TopicPermission[ <topic>,
PUBLISH]
for each topic they want to send events to.
Bundles that need to iterate the handlers registered with the
system must be granted
ServicePermission[org.osgi.service.event.EventHandler, GET]
to retrieve the event handlers from the service registry.
Only a bundle that contains an Event Admin service implementation
should be granted ServicePermission[
org.osgi.service.event.EventAdmin, REGISTER]
to register the
event channel admin service.
During an event notification, the Event Admin service's Protection Domain will be on the stack above the handler's Protection Domain. In the case of a synchronous event, the event publisher's protection domain can also be on the stack.
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.
Event Admin Package Version 1.4.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.service.event; version="[1.4,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.service.event; version="[1.4,1.5)"
-
Event
- An event. -
EventAdmin
- The Event Admin service. -
EventConstants
- Defines standard names forEventHandler
properties. -
EventHandler
- Listener for Events. -
EventProperties
- The properties for an Event. -
TopicPermission
- A bundle's authority to publish or subscribe to event on a topic.
An event.
Event
objects are delivered to EventHandler
services which
subscribe to the topic of the event.
Immutable
The topic of the event.
The event's properties (may be null
). A
property whose key is not of type String
will be ignored.
If the specified properties is an EventProperties object,
then it will be directly used. Otherwise, a copy of the specified
properties is made.
Constructs an event.
IllegalArgumentException
– If topic is not a valid topic name.
1.2
The topic of the event.
The event's properties (may be null
). A
property whose key is not of type String
will be ignored.
A copy of the specified properties is made.
Constructs an event.
IllegalArgumentException
– If topic is not a valid topic name.
The name of the property.
Indicate the presence of an event property. The event topic is present using the property name "event.topics".
true
if a property with the specified name is in the
event. This property may have a null
value. false
otherwise.
1.3
The Event
object to be compared.
Compares this Event
object to another object.
An event is considered to be equal to another event if the topic
is equal and the properties are equal. The properties are compared using
the java.util.Map.equals()
rules which includes identity
comparison for array values.
true
if object
is a Event
and is equal to
this object; false
otherwise.
The name of the property to retrieve.
Retrieve the value of an event property. The event topic may be retrieved with the property name "event.topics".
The value of the property, or null
if not found.
Returns a list of this event's property names. The list will include the event topic property name "event.topics".
A non-empty array with one element per property.
Returns a hash code value for this object.
An integer which is a hash code value for this object.
The filter to test.
Tests this event's properties against the given filter using a case sensitive match.
true If this event's properties match the filter, false otherwise.
The Event Admin service. Bundles wishing to publish events must obtain the Event Admin service and call one of the event delivery methods.
Thread-safe
Consumers of this API must not implement this type
The event to send to all listeners which subscribe to the topic of the event.
Initiate asynchronous, ordered delivery of an event. This method returns to the caller before delivery of the event is completed. Events are delivered in the order that they are received by this method.
SecurityException
– If the caller does not have
TopicPermission[topic,PUBLISH]
for the topic specified in
the event.
The event to send to all listeners which subscribe to the topic of the event.
Initiate synchronous delivery of an event. This method does not return to the caller until delivery of the event is completed.
SecurityException
– If the caller does not have
TopicPermission[topic,PUBLISH]
for the topic specified in
the event.
Defines standard names for EventHandler
properties.
Consumers of this API must not implement this type
The Bundle object of the bundle relevant to the event. The type of the value for this event property is Bundle.
1.1
The Bundle id of the bundle relevant to the event. The type of the value
for this event property is Long
.
1.1
The Distinguished Names of the signers of the bundle relevant to the
event. The type of the value for this event property is String
or
Collection
of String
.
The Bundle Symbolic Name of the bundle relevant to the event. The type of
the value for this event property is String
.
The version of the bundle relevant to the event. The type of the value for this event property is Version.
1.2
Event Handler delivery quality value specifying the Event Handler requires asynchronously delivered events be delivered in order. Ordered delivery is the default for asynchronously delivered events.
This delivery quality value is mutually exclusive with DELIVERY_ASYNC_UNORDERED. However, if both this value and DELIVERY_ASYNC_UNORDERED are specified for an event handler, this value takes precedence.
1.3
Event Handler delivery quality value specifying the Event Handler does not require asynchronously delivered events be delivered in order. This may allow an Event Admin implementation to optimize asynchronous event delivery by relaxing ordering requirements.
This delivery quality value is mutually exclusive with DELIVERY_ASYNC_ORDERED. However, if both this value and DELIVERY_ASYNC_ORDERED are specified for an event handler, DELIVERY_ASYNC_ORDERED takes precedence.
1.3
The forwarded event object. Used when rebroadcasting an event that was
sent via some other event mechanism. The type of the value for this event
property is Object
.
The name of the implementation capability for the Event Admin specification
1.4
The version of the implementation capability for the Event Admin specification
1.4
Service Registration property specifying the delivery qualities requested by an Event Handler service.
Event handlers MAY be registered with this property. Each value of this property is a string specifying a delivery quality for the Event handler.
The value of this property must be of type String
,
String[]
, or Collection<String>
.
DELIVERY_ASYNC_ORDERED, DELIVERY_ASYNC_UNORDERED
1.3
Service Registration property specifying a filter to further select
Event
s of interest to an Event Handler service.
Event handlers MAY be registered with this property. The value of this property is a string containing an LDAP-style filter specification. Any of the event's properties may be used in the filter expression. Each event handler is notified for any event which belongs to the topics in which the handler has expressed an interest. If the event handler is also registered with this service property, then the properties of the event must also match the filter for the event to be delivered to the event handler.
If the filter syntax is invalid, then the Event Handler must be ignored and a warning should be logged.
The value of this property must be of type String
.
Event, Filter
Service registration property specifying the Event
topics of
interest to an Event Handler service.
Event handlers SHOULD be registered with this property. Each value of this property is a string that describe the topics in which the handler is interested. An asterisk ('*') may be used as a trailing wildcard. Event Handlers which do not have a value for this property must not receive events. More precisely, the value of each string must conform to the following grammar:
topic-description := '*' | topic ( '/*' )?
topic := token ( '/' token )*
The value of this property must be of type String
,
String[]
, or Collection<String>
.
An exception or error. The type of the value for this event property is
Throwable
.
The name of the exception type. Must be equal to the name of the class of
the exception in the event property EXCEPTION. The type of the
value for this event property is String
.
1.1
The exception message. Must be equal to the result of calling
getMessage()
on the exception in the event property
EXCEPTION. The type of the value for this event property is
String
.
This constant was released with an incorrectly spelled name. It has been replaced by EXCEPTION_CLASS
As of 1.1. Replaced by EXCEPTION_CLASS.
A human-readable message that is usually not localized. The type of the
value for this event property is String
.
A service reference. The type of the value for this event property is ServiceReference.
A service's id. The type of the value for this event property is
Long
.
A service's objectClass. The type of the value for this event property is
String[]
.
A service's persistent identity. The type of the value for this event
property is String
or Collection
of String
.
Listener for Events.
EventHandler
objects are registered with the Framework service
registry and are notified with an Event
object when an event is sent
or posted.
EventHandler
objects can inspect the received Event
object to
determine its topic and properties.
EventHandler
objects must be registered with a service property
EventConstants.EVENT_TOPIC whose value is the list of topics in which
the event handler is interested.
For example:
String[] topics = new String[] {"com/isv/*"};
Hashtable ht = new Hashtable();
ht.put(EventConstants.EVENT_TOPIC, topics);
context.registerService(EventHandler.class.getName(), this, ht);
Event Handler services can also be registered with an EventConstants.EVENT_FILTER service property to further filter the events. If the syntax of this filter is invalid, then the Event Handler must be ignored by the Event Admin service. The Event Admin service should log a warning.
Security Considerations. Bundles wishing to monitor Event
objects
will require ServicePermission[EventHandler,REGISTER]
to register an
EventHandler
service. The bundle must also have
TopicPermission[topic,SUBSCRIBE]
for the topic specified in the event
in order to receive the event.
Thread-safe
The event that occurred.
Called by the EventAdmin service to notify the listener of an event.
The properties for an Event. An event source can create an EventProperties object if it needs to reuse the same event properties for multiple events.
The keys are all of type String
. The values are of type
Object
. The key "event.topics" is ignored as event topics
can only be set when an Event is constructed.
Once constructed, an EventProperties object is unmodifiable. However, the values of the map used to construct an EventProperties object are still subject to modification as they are not deeply copied.
1.3
Immutable
The properties to use for this EventProperties object
(may be null
).
Create an EventProperties from the specified properties.
The specified properties will be copied into this EventProperties.
Properties whose key is not of type String
will be ignored. A
property with the key "event.topics" will be ignored.
This method throws UnsupportedOperationException.
UnsupportedOperationException
– if called.
The property name.
Indicates if the specified property is present.
true
If the property is present, false
otherwise.
The property value.
Indicates if the specified value is present.
true
If the value is present, false
otherwise.
Return the property entries.
A set containing the property name/value pairs.
The EventProperties
object to be compared.
Compares this EventProperties
object to another object.
The properties are compared using the java.util.Map.equals()
rules which includes identity comparison for array values.
true
if object
is a EventProperties
and
is equal to this object; false
otherwise.
The name of the specified property.
Return the value of the specified property.
The value of the specified property.
Returns a hash code value for this object.
An integer which is a hash code value for this object.
Indicate if this properties is empty.
true
If this properties is empty, false
otherwise.
Return the names of the properties.
The names of the properties.
This method throws UnsupportedOperationException.
UnsupportedOperationException
– if called.
This method throws UnsupportedOperationException.
UnsupportedOperationException
– if called.
This method throws UnsupportedOperationException.
UnsupportedOperationException
– if called.
Returns the string representation of this object.
The string representation of this object.
A bundle's authority to publish or subscribe to event on a topic.
A topic is a slash-separated string that defines a topic.
For example:
org/osgi/service/foo/FooEvent/ACTION
TopicPermission
has two actions: publish
and
subscribe
.
Thread-safe
Topic name.
publish
,subscribe
(canonical order).
Defines the authority to publish and/or subscribe to a topic within the EventAdmin service.
The name is specified as a slash-separated string. Wildcards may be used. For example:
org/osgi/service/fooFooEvent/ACTION
com/isv/*
*
A bundle that needs to publish events on a topic must have the
appropriate TopicPermission
for that topic; similarly, a bundle
that needs to subscribe to events on a topic must have the appropriate
TopicPermssion
for that topic.
The object to test for equality with this
TopicPermission
object.
Determines the equality of two TopicPermission
objects.
This method checks that specified TopicPermission
has the same
topic name and actions as this TopicPermission
object.
true
if obj
is a TopicPermission
, and has
the same topic name and actions as this TopicPermission
object; false
otherwise.
Returns the canonical string representation of the
TopicPermission
actions.
Always returns present TopicPermission
actions in the following
order: publish
,subscribe
.
Canonical string representation of the TopicPermission
actions.
Returns the hash code value for this object.
A hash code value for this object.
The target permission to interrogate.
Determines if the specified permission is implied by this object.
This method checks that the topic name of the target is implied by the
topic name of this object. The list of TopicPermission
actions
must either match or allow for the list of the target object to imply the
target TopicPermission
action.
x/y/*,"publish" -> x/y/z,"publish" is true
*,"subscribe" -> x/y,"subscribe" is true
*,"publish" -> x/y,"subscribe" is false
x/y,"publish" -> x/y/z,"publish" is false
true
if the specified TopicPermission
action is
implied by this object; false
otherwise.
Event Admin Annotations Package Version 1.4.
This package contains annotations that can be used to require the Event Admin implementation.
Bundles should not normally need to import this package as the annotations are only used at build-time.
-
RequireEventAdmin
- This annotation can be used to require the Event Admin implementation.
This annotation can be used to require the Event Admin implementation. It can be used directly, or as a meta-annotation.
This annotation is applied to several of the Event Admin component property type annotations meaning that it does not normally need to be applied to Declarative Services components which use the Event Admin.
1.4
CLASS
TYPE
, PACKAGE
Event Admin Component Property Types Package Version 1.4.
When used as annotations, component property types are processed by tools to generate Component Descriptions which are used at runtime.
Bundles wishing to use this package at runtime must list the package in the Import-Package header of the bundle's manifest.
Example import for consumers using the API in this package:
Import-Package: org.osgi.service.event.propertytypes; version="[1.4,2.0)"
-
EventDelivery
- Component Property Type for the EventConstants.EVENT_DELIVERY service property of an EventHandler service. -
EventFilter
- Component Property Type for the EventConstants.EVENT_FILTER service property of an EventHandler service. -
EventTopics
- Component Property Type for the EventConstants.EVENT_TOPIC service property of an EventHandler service.
Component Property Type for the EventConstants.EVENT_DELIVERY service property of an EventHandler service.
This annotation can be used on an EventHandler component to declare the value of the EventConstants.EVENT_DELIVERY service property.
Component Property Types
1.4
CLASS
TYPE
Service property specifying the Event
delivery qualities
requested by an EventHandler service.
The supported delivery qualities are:
The requested event delivery qualities.
Component Property Type for the EventConstants.EVENT_FILTER service property of an EventHandler service.
This annotation can be used on an EventHandler component to declare the value of the EventConstants.EVENT_FILTER service property.
Component Property Types
1.4
CLASS
TYPE
Service property specifying the Event
filter to an
EventHandler service.
The event filter.
Component Property Type for the EventConstants.EVENT_TOPIC service property of an EventHandler service.
This annotation can be used on an EventHandler component to declare the values of the EventConstants.EVENT_TOPIC service property.
Component Property Types
1.4
CLASS
TYPE
Service property specifying the Event
topics of interest to an
EventHandler service.
The event topics.