Sun Java Communications Suite 5 Event Notification Service Guide

Event Notification Service Architecture

On the Solaris platform, ENS runs as a daemon, enpd, along with other daemons in various calendar or messaging server configurations, to collect and dispatch events that occur to properties of resources. On Windows platforms, ENS runs as a service, enpd.exe.

For ENS, an event is a change that happens to a resource, while a resource is an entity such as a calendar or inbox. For example, adding an entry to a calendar (the resource) generates an event, which is stored by ENS. This event can then be subscribed to, and a notification would then be sent to the subscriber.

The ENS architecture enables the following three things to occur:

Notification - This is a message that describes an event occurrence. Sent by the event publisher, it contains a reference to the event, as well as any additional parameter/value pairs added to the URI, and optional data (the payload) used by the event consumers, but opaque to the notification service. Whoever is interested in the event can subscribe to it.
Subscription - This is a message sent to subscribe to an event. It contains an event reference, a client-side request identifier, and optional parameter/value pairs added to the URI. The subscription applies to upcoming events (that is, a subscriber asks to be notified of upcoming events).
Unsubscription - This message cancels (unsubscribes) an existing subscription. An event subscriber tells ENS to stop relaying notifications for the specified event.

Notify

ENS notifies its subscribers of an event by sending a notification. Notify is also referred to as “publish.” A notification can contain the following items:

An event reference (which, optionally, can contain parameter/value pairs)
Optional application-specific data (“opaque” for ENS, but the publisher and subscriber agree apriori to the format of the data)

The optional application-specific data is referred to as the “payload.”

There are two kinds of notifications:

Unreliable notification - Notification sent from an event publisher to a notification server. If the publisher does not know nor care about whether there are any consumers, or whether they get the notification, this request does not absolutely need to be acknowledged. However, a publisher and a subscriber, who are mutually aware of each other, can agree to set up a reliable event notification link (RENL) between themselves. In this case, once the subscriber has processed the publisher’s notification, it sends an acknowledgment notification back to the publisher.
Reliable notification - Notification sent from a server to a subscriber as a result of a subscription. This type of notification should be acknowledged. A reliable notification contains the same attributes as an unreliable notification.

See Publisher API for more information.

ENS receives a request to be notified of events. The request sent by the event subscriber is a subscription. The subscription is valid during the life of the session, or until it is cancelled (unsubscribed).

A subscription can contain the following items:

An event reference (which, optionally, can contain parameter/value pairs)
A request identifier

See Subscriber API for more information.

Unsubscribe

ENS receives a request to cancel an existing subscription. See Subscriber API for more information.

How Calendar Server Interacts with ENS

Figure 1–1 shows how ENS interacts with Calendar Server through the alarm queue and two daemons, csadmind and csnotifyd.

Figure 1–1 ENS in Calendar Server Overview

Calendar Server Alarm Queue

ENS is an alarm dispatcher. This decouples alarm delivery from alarm generation. It also enables the use of multiple delivery methods, such as email and wireless communication. The csadmind daemon detects events by sensing changes in the state of the alarm queue. The alarm queue’s state changes every time an alarm is placed in the queue. An alarm is queued when a calendar event generates an alarm. The following URIs represent these kind of events:

for events:

enp:///ics/eventalarm?calid=calid&uid=uid&rid=rid&aid=aid

for todos (tasks):

enp:///ics/todoalarm?calid=calid&uid=uid&rid=rid&aid=aid

where:

calid is the calendar ID.
uid is the event/todo (task) ID within the calendar.
rid is the recurrence id for a recurring event/todo (task).
aid is the alarm ID within the event/todo (task). In case there are multiple alarms, the aid identifies the correct alarm.

The publisher csadmind dequeues the alarms and sends notifications to enpd. The enpd daemon then checks to see if anyone is subscribed to this kind of event and sends notifications to the subscriber, csnotifyd, for any subscriptions it finds. Other subscribers to alarm notifications (reminders) can be created and deployed within an Calendar Server installation. These three daemons interacting together implement event notification for Calendar Server.

Calendar Server Daemons

Calendar Server includes two daemons that communicate to the ENS daemon, enpd:

csadmind

The csadmind daemon contains a publisher that submits notifications to the notification service by sending alarm events to ENS. It manages the Calendar Server alarm queue. It implements a scheduler, which lets it know when an alarm has to be generated. At such a point, csadmind publishes an event. ENS receives and dispatches the event notification.

To ensure alarm transfer reliability, csadmind requires acknowledgment for certain events or event types. (See Alarm Transfer Reliability.) The csadmind daemon uses Reliable Event Notification Links (RENLs) to accomplish acknowledgment.
csnotifyd

The csnotifyd daemon is the subscriber that expresses interest in particular events (subscribes), and receives notifications about these subscribed-to events from ENS, and sends notice of these events and todos (tasks) to its clients by email.

Though the ability to unsubscribe is part of the ENS architecture, csnotifyd does not bother to unsubscribe to events for the following two reasons: there is no need to unsubscribe or resubscribe during normal runtime; and due to the temporary nature of the subscriptions store (it is held in memory), all subscriptions are implicitly unsubscribed when the connection to ENS is shutdown.

The csnotifyd daemon subscribes to enp:///ics/alarm/. The todo (task) or event is specified in a parameter.

Alarm Transfer Reliability

To ensure that no alarm ever gets lost, csadmind and csnotifyd use the RENL feature of ENS for certain types of alarms. For these alarms, csadmind requests an end-to-end acknowledgment for each notification it sends, while csnotifyd, after successfully processing it, generates a notification acknowledgment for each RENL alarm notifications it receives.

For these RENL alarms, should the network, the ENS daemon, or csnotifyd fail to handle a notification, csadmind will not receive any acknowledgment, and will not remove the alarm from the alarm queue. The alarm will, therefore, be published again after a timeout.

Calendar Server Example

A typical ENS publish and subscribe cycle for Calendar Server resembles the following:

The event subscriber, csnotifyd, expresses interest in an event (subscribes).
The event publisher, csadmind, detects events and sends notification (publishes).
ENS publishes the event to the subscriber.
The event subscriber cancels interest in the event (unsubscribes). This step happens implicitly when the connection to ENS is shut down.

Figure 1–2 illustrates this cycle and Table 1–1 provides the narrative for the figure.

Figure 1–2 Example Event Notification Service Publish and Subscribe Cycle for Calendar Server

Table 1–1 Sample ENS Publish and Subscribe Cycle


Action	ENS Response
1. The `csnotifyd` daemon sends a subscription request to ENS.	ENS stores the subscription in the subscriptions database.
2. The `csadmind` daemon sends a notification request to ENS.	ENS queries the subscriptions database for subscriptions matching the notification.
3. The `csnotifyd` daemon receives a notification from ENS.	When ENS receives a notification from a publisher, it looks up its internal subscription table to find subscriptions matching the event reference of the notification. Then for each subscription, it relays a copy of the notification to the subscriber who owns this subscription.
4. Currently, `csnotifyd` does not bother sending cancellation requests to ENS.	Because the subscriptions store is in memory only (not in a database), all subscriptions are implicitly unsubscribed when the connection to ENS is shutdown.

How Messaging Server Interacts with ENS

Figure 1–3 shows how ENS interacts with Messaging Server. In this figure, each oval represents a process, and each rectangle represents a host computer running the enclosed processes.

The ENS server delivers notifications from the Messaging Server notification plug-in to ENS clients (that is, iBiff subscribers). There is no guarantee of the order of notification prior to the ENS server because the events are coming from different processes (MTA, stored, and imapd).

Notifications flow from the iBiff plug-in in the MTA, stored, and imap processes to ENS enpd. The ENS client subscribes to the ENS, and receives notifications. When iBiff is enabled, Messaging Server publishes the notifications with the iBiff plug-in, but no Messaging Server services subscribe to these notifications. A customer-provided ENS subscriber or client should be written to consume the notifications and do whatever is necessary. That is, Messaging Server itself does not depend on or use the notifications for its functions, and this is why ENS and iBiff are not enabled by default when you install Messaging Server.

The Messaging Server architecture enforces that a given set of mailboxes is served by a given host computer. A given mailbox is not served by multiple host computers. There are several processes manipulating a given mailbox but only one computer host serving a given mailbox. Thus, to receive notifications, end-users only need to subscribe to the ENS daemon that serves the mailbox they are interested in.

Messaging Server enables you to have either one ENS server for all mailboxes—that is, one ENS server for all the computer hosts servicing the message store—or multiple ENS servers, perhaps one ENS server per computer host. The second scenario is more scalable. Also, in this scenario, end users must subscribe to multiple ENS servers to get the events for mailboxes they are interested in.

Thus, the architecture requires an ENS server per computer host. The ENS servers and the client processes do not have to be co-located with each other or with messaging servers.