Remote Events and Subscriptions Management

Elaborates common behaviors and basic resource representation patterns relative to the remote events support for RESTful Web Services.

The main mechanisms for subscribing and consuming remote events are explained along with common models for discovery of event-related resources and versioning information and approaches for introspecting events subscriptions and customizing event representations. Remote Events support conforms to the Common Behaviors and Definitions for RESTful Web Services.

General Idea

Remote events management employs a centralized model which implies that clients can create event subscriptions using a single dedicated URI instead of subscribing on various URIs exposed by the RESTful web services.

Each remote event has an event topic and event properties. The topic reflects the possible state changes of a resource of interest:

creation;
removal;
modification.

The event properties reflect the fields of the resource which state has been changed and may optionally include some additional properties specific to the event topic semantics.

To subscribe for events and receive notifications for resources of interest a client must specify a subscription criteria which defines the relevant event topics and optional LDAP filters defined over the event properties. There are two mechanisms supported for event subscriptions and receiving event notifications:

Event subscriptions are considered private thus only the subscriber would know the subscription identifier and be able to unsubscribe and consume the events that have matched the subscription filtering criteria. Clients that are operating in scoped case and wish to make an event subscription scoped for single OSGi service gateway need to explicitly encode the gateway identifier in the URIs for subscribing and receiving events. In this case, similarly to local event subscriptions, identifiers included in the events will be returned as specified by the underlying services. Event representations are encoded in JSON, as specified in RFC 4267; in future XML serialization may be supported as well.

General Event Format

Field	Type	Resolution	Description
properties	Map <String, Object>	mandatory	Event properties. Keys are string and values may be any serializable type which implies java primitive types, primitive wrapper classes, strings, java bean classes and JAXB elements. Any of the properties except for links can be used to construct a LDAP filter for event subscriptions. In general, event property fields reflect the fields of the resource which state change triggered the event. There are several common event properties which are included for all remote events, please see Common Event Properties.
topic	String	mandatory	Event topic identifying state change of a resource of interest. Can be used in event subscriptions.

Common Event Properties

Field	Type	Resolution	Description
timestamp	long	mandatory	Specifies the time the event was generated on the server.
sequence	Integer	mandatory	Specifies the sequence number of the event in the scope of a given event subscription starting from zero.
subscription.id	String	optional	Specifies the identifier of the subscription that the event is relevant to. The property is included only in the event properties for remote events delivered over web sockets.

General Event Subscription Format

Field	Type	Resolution	Description
criteria	Event Subscription Criterion Description []	mandatory	Collection of event filtering criteria entities. For more details, please see Event Subscription Criterion Description Format. Clients that wish to subscribe for events and receive event notifications of interest must specify a filtering criteria in the subscription which is based on event topics and optional LDAP filter defined over the event properties.

Event Subscription Criterion Description Format

Field	Type	Resolution	Description
topics	Sting[]	mandatory	Collection of one or more event topic of interest.
filter	Sting	optional	LDAP filter defined over the properties of the events of interest.

Protection and Clean-up Mechanisms for Remote Events

The following protection and clean-up mechanisms are supported for remote events subscriptions and notifications via long polling and web sockets:

A subscription expiration mechanism is supported for all event subscriptions created on the server. A subscription is considered expired if a predefined timeout has elapsed since the subscription has been created. Expired subscriptions are automatically deleted by the server and all relevant client connections (opened web sockets/long poll requests), if there are any, are forced closed by the server. It it assumed that clients would expect that the connection might be closed by the server and a reconnect would be attempted in case the forcibly closed connection was not obsolete. The subscription expiration timeout is configurable via an OSGi configuration.

A maximum permissible count limitation is applied by the server for simultaneous subscriptions. No new subscriptions are accepted by the server after a predefined maximum permissible subscriptions count has been reached. The maximum permissible subscriptions count is configurable via an OSGi configuration.

A maximum permissible size limitation is applied by the server for the temporally cached events within the scope of a certain event subscription. All locally delivered events that satisfy the event subscription criteria must be stored in an event queue with a predefined maximum permissible size. If a new event is locally delivered after a predefined maximum permissible queue size is reached then the oldest event in the queue is removed and never delivered to the remote client. It is assumed that clients would consider the events sequence number for detecting event loss. The maximum permissible event queue size per subscription is configurable via an OSGi configuration.

Security for Remote Events

Support for securing and controlling the access to events is enabled via integration with Policy Admin. Remote events subscriptions can be associated with an identity based on the remote user in the HTTP session and access to events can be controlled via a policy defined for that identity.