This document elaborates on common behaviors and basic resource representation patterns relative to Remote Manager's remote events support.
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.
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 whose state has been changed and may 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 subscription criteria which define 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:
- Remote Events Subscription and Push Notifications via Web Sockets.
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 cases and wish to make an event subscription scoped for a 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.
General Event Format
Field | Type | Resolution | Description |
|---|---|---|---|
properties | Map <String, Object> | mandatory | Event property keys are of string type and their 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 an 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 the table below. |
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 | String[] | mandatory | Collection of one or more event topic of interest. |
filter | String | 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 was created. Expired subscriptions are automatically deleted by the server and all relevant client connections (opened web sockets/long poll requests), i any, are force closed by the server. It is 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 size limitation is applied by the server for the temporarily 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.