Chapter 4   Event Notification Service (ENS) Overview


The Event Notification Service (ENS) is a generic publish-and-subscribe service shipped with iPlanet Calendar Server 5.0. ENS acts as a dispatcher used by iPlanet applications as a central point of collection for certain types of events that are of interest to them. Specifically, ENS accepts reports of events that can be categorized, and notifies other applications that have registered an interest in certain categories of events.

In summary, ENS is an internet service used by applications to:

• Notify whomever is interested of an event.

• Subscribe to upcoming events (that is, ask to be notified of upcoming events).

• Cancel existing subscriptions (unsubscribe).

---

Note

iPlanet offers a generic message-oriented middleware system, distinct from ENS, called Java Message Queue (JMQ). JMQ is a Java Message Service (JMS) implementation. For now the ENS subscriber API is the only interface which can be used to access Calendar Server events. In particular, JMS may not be used to access such events. In the future, iPlanet messaging middleware APIs will consolidate around JMS, and JMS will, therefore, become the primary method to access Calendar Server events.

---

This chapter contains the following topics:

• ENS Glossary

• Events

• Event References

• Event Notification Service

• Calendar Server Interaction with ENS

• Building and Running Custom Applications

ENS Glossary

---

event	A change in a resource. For instance, someone adds a new meeting to a calendar (the resource). For ENS, events are a change in the state of the alarm queue.
event consumer	Synonym for event subscriber.
event producer	Synonym for event publisher.
event publisher	An application that makes events known to other applications.
event reference	Identifies an event handled by ENS. It complies with URI syntax defined by RFC 2396.
event subscriber	An application that consumes events.
notification	Message describing an event occurrence. Sent by the event publisher, it contains a reference to the event as well as optional data used by the event consumers, but opaque to the notification service.
notification service	Receives subscriptions and notifications from other servers. Relays notifications to subscribers.
notification server	A notification service is made up of one or more server instances, each running on a separate host.
notify	A synonym for publish.
publish	Send a notification. An event publisher makes an event available to the notification service.
reliable event notification link (RENL)	An RENL has a publisher, a subscriber, and a unique ID, which identify notifications that are subject to acknowledgment.
resource	A piece of data accessed from the IP network. For example, a calendar is a resource.
resource state	The value of attributes that describe a resource. For example, a meeting time.
subscribe	Send a subscription. An event subscriber tells the notification service that it wants to receive notifications of a specific event.
subscription	Message sent by the event subscriber. Contains an event reference, a client-side request identifier, and optional access control rules.
unsubscribe	Cancels a subscription. An event subscriber tells the event notification service to stop relaying notifications for the specified event.

Events

---

Events are changes to the value of one or more properties of a resource, a URI represents an event. Any application that wants to know when these types of events occur registers with ENS, which identifies events in order and matches notifications with subscriptions.

Event References

---

Event references identify an event handled by ENS. They use the URI syntax specified by RFC 2396.

URI syntax:

event reference:= scheme ":" authority resource ["?" param "=" value *("&" param "=" value)]

where:

• scheme is the access method, such as http, imap, ftp, wcap.

  For iPlanet Calendar Server 5.0, the ENS scheme is enp.

• authority is the DNS domain or hostname which controls access to the resource.

• resource is the path leading to the resource in the context of the authority. It may be composed of several path components separated by "/".

• param is the name of a parameter describing the state of a resource.

• value is its value. There can be zero or more parameter/value pairs.

The following is the URI scheme for all iPlanet Calendar Server events:

enp://domain.com/calendar/ics/v50/instance

Example

As an example, for an iPlanet Calendar Server 5.0 user to subscribe to all event alarms with a specific unique ID, the URI would look like:

enp://domain.com/calendar/ics/v50/ics-hostname/alarms?type=events
&uid=XXXX

Event Notification Service

---

The Event Notification Service is an internet service used by applications to:

• Notify

• Subscribe

• Unsubscribe

ENS runs as a daemon, enpd, along with other iPlanet Calendar Server 5.0 daemons in various calendar server configurations. For further explanation of how ENS integrates with iPlanet Calendar Server 5.0, see Calendar Server Interaction with ENS of this chapter, and Horizontal Scalability in Chapter 1 "Architecture Overview".

Notify

ENS notifies its subscribers of an event by sending a notification containing an event reference, optional access control rules, and optional application-specific (opaque for ENS) data. Also called "publish".

There are two kinds of notifications:

• Unsolicited 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, may 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.

• Server notification. Notification sent from a server to a subscriber as a result of a subscription. This type of notification should be acknowledged. A server notification contains the same attributes as a spontaneous notification.

Subscribe

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 contains an event name, a client-side request identifier, and optional access control rules. .

Unsubscribe

ENS receives a request to cancel an existing subscription. The client-side request id, and the session id identify the subscription.

Calendar Server Interaction with ENS

---

ENS interacts with Calendar Server through the alarm queue and two daemons, csadmind, and csnotifyd. Figure 4-1 illustrates the interaction between the two Calendar Server daemons and the ENS daemon.

Figure 4-1    ENS Overview

Alarm Queue

ENS is an alarm dispatcher. This decouples alarm delivery from alarm generation. It also allows for the use of multiple delivery methods, such as email and wireless. csadmind 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 an event producer generates an alarm. The following URIs represents these kind of events:

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

for todos:

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

where:

• calid is the calendar ID.

• uid is the event/todo ID within the calendar.

• rid is the recurrence id for a recurring event/todo.

• aid is the alarm ID within the event/todo. In case there are multiple alarms, the aid identifies the correct alarm.

csadmind dequeues the alarms and sends notifications to enpd. enpd then checks to see if anyone is subscribed to this kind of event and sends notifications to csnotifyd for any subscriptions it finds. These three daemons interacting together implement event notification.

Daemons

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

• csadmind

  csadmind is the publisher that submits notifications to the notification service by sending event alarms to ENS. It manages the iPlanet Calendar Server 5.0 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 in this chapter.) csadmind uses Reliable Event Notification Links (RENLs) to accomplish acknowledgment.

• csnotifyd

  csnotifyd is the subscriber that expresses interest in particular events (subscribes), and receives notifications about these subscribed-to events from the event notification service, and sends notice of these events and todos 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.

  It subscribes to ics://hostname/alarm/pop, and therefore receives all alarm notifications for the host, hostname. Upon receipt of an alarm notification, csnotifyd generates email messages.

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.

Example

A typical ENS publish and subscribe cycle:

1. The event subscriber, csnotifyd, expresses interest in an event (subscribes).

2. The event publisher, csadmind, detects events and sends notification (publishes).

3. ENS publishes the event to the subscriber.

4. The event subscriber cancels interest in the event (unsubscribes). This step happens implicitly when the connection to ENS is shutdown.

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

Figure 4-2    Example Event Notification Service Publish and Subscribe Cycle

• 
  

  Table 4-1 Example Event Notification Service Publish and Subscribe Cycle
  
  

  Action	ENS Response
  csnotifyd sends a subscription request to ENS.	ENS stores the subscription in the subscriptions database.
  csadmind sends a notification request to ENS.	ENS queries the subscriptions database for subscriptions matching the notification.
  csnotifyd receives a notification from ENS.	For each matching subscription, access controls are applied and a notification request per qualifying subscription is added to the deliver queue. csnotifyd asynchronously dequeues requests from the deliver queue and sends out notifications.
  Currently, csnotifyd does not bother sending cancellation requests to ENS.	Since the subscriptions store is in memory only (not in a database), all subscriptions are implicitly unsubscribed when the connection to ENS is shutdown.