Chapter 1   Introduction to Event Notification Service


This chapter provides an overview of the iPlanet Event Notification Service (ENS) components, architecture, and Application Programming Interfaces (APIs).

This chapter contains these sections:

• Event Notification Service Overview

• Event Notification Service Architecture

• Event Notification Service API Overview

Event Notification Service Overview

---

The Event Notification Service (ENS) is iPlanet's underlying publish-and-subscribe service available in the following iPlanet products:

• iPlanet Calendar Server, Release 5.0 and later

• iPlanet Messaging Server, Release 5.1 and later (integrated but not enabled)

  
  

  ---

  Note	See Appendix C in the iPlanet Messaging Server 5.2 Administrator's Guide for instructions on enabling and administering ENS in iPlanet Messaging Server.

  ---

  
  

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. Events are changes to the value of one or more properties of a resource. In this structure, a URI (Uniform Resource Identifier) 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 examples include:

• Arrival of new mail to a user's inbox

• User's mailbox has exceeded its quota

• Calendar reminders

Specifically, ENS accepts reports of events that can be categorized, and notifies other applications that have registered an interest in certain categories of events.

Event Notification Service provides a server and APIs for publishers and subscribers. A publisher makes an event available to the notification service; and a subscriber tells the notification service that it wants to receive notifications of a specific event. See "Event Notification Service API Overview" for more information on the ENS APIs.

ENS in iPlanet Calendar Server

By default, ENS is enabled in iPlanet Calendar Server. For iPlanet Calendar Server you do not need to do anything else to use ENS.

A user who wants to subscribe to notifications other than the alarms generated by iPlanet Calendar Server needs to write a subscriber.

There is sample ENS C publisher and subscriber code bundled with iPlanet Calendar Server. See "iPlanet Calendar Server Sample Code" for that code.

Sample iPlanet Calendar Server code is provided with the product in the following directory:

/opt/SUNWics5/cal/csapi/samples/ens

ENS in iPlanet Messaging Server

ENS and iBiff (the ENS publisher for iPlanet Messaging Server, also referred to as the notification plug-in to iPlanet Messaging Server) are bundled in iPlanet Messaging Server. However, by default, they are not enabled.

To subscribe to notifications in iPlanet Messaging Server, you need to first perform the following two items on the iPlanet Messaging Server host:

• Load the iBiff notification plug-in

• Stop and restart the messaging server

See Appendix C in the iPlanet Messaging Server 5.2 Administrator's Guide for the instructions to enable ENS on iPlanet Messaging Server.

A user who wants to subscribe to iPlanet Messaging Server notifications needs to write a subscriber to the ENS API. To do so, the subscriber needs to know what the various iPlanet Messaging Server notifications are. See Chapter 5 "iPlanet Messaging Server Specific Information" for that information.

iPlanet Messaging Server comes bundled with sample ENS C publisher and subscriber code. See "iPlanet Messaging Server Sample Code" for more information.

Sample iPlanet Messaging Server code is provided with the product in the following directory:

server-root/bin/msg/enssdk/examples

Event References

Event references identify an event handled by ENS. Event references use the following URI syntax (as specified by RFC 2396):

scheme://authority resource/[?param1=value1&param2=value2&param3=value3]

where:

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

  For iPlanet Calendar Server and iPlanet Messaging Server, the ENS scheme is enp.

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

• resource is the path leading to the resource in the context of the authority. It can be composed of several path components separated by a slash ("/").

• 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.

In general, all iPlanet Calendar Server events start with the following:

enp:///ics

The iPlanet Messaging Server notification plug-in iBiff uses the following scheme and resource by default:

enp://127.0.0.1/store

---

Note	Although the event reference has a URI syntax, the scheme, authority, and resource have no special significance. They are merely used as strings with no further interpretation in ENS.

---

iPlanet Calendar Server Event Reference Example

The following is an example event reference URI to subscribe to all event alarms with a calendar ID of jac:

enp:///ics/alarm?calid=jac

---

Note	This is not meant to be used by end users.

---

iPlanet Messaging Server Event Reference Example

The following is an example event reference that requests a subscription to all NewMsg events for a user whose user ID is blim:

enp://127.0.0.1/store?evtType=NewMsg&mailboxName=blim

When using ENS with iPlanet Messaging Server, the user id you specify is case sensitive.

---

Note	This is not meant to be used by end users.

---

ENS Connection Pooling

The connection pooling feature of ENS enables a pool of subscribers to receive notifications from a single event reference. For every event, ENS chooses one subscriber from the pool to send the notification to. Thus, only one subscriber in the pool receives the notification. The ENS server balances sending of notifications among the subscribers. This enables the client to have a pool of subscribers that work together to receive all notifications from a single event reference.

For example, if notifications are being published to the event reference enp://127.0.0.1/store, a subscriber will normally subscribe to this event reference to receive notifications. To have a pool of subscribers receive all the notifications to this event reference, each subscriber in the pool only needs to subscribe to the event reference enp+pool://127.0.0.1/store instead. The ENS server chooses one subscriber from the pool to send the notification to.

---

Note	The publisher still sends notifications to the simple event reference, in the example above enp://127.0.0.1/store, that is, the publisher has no knowledge of the subscriber pool.

---

Multiple Pool Extension

Connection pooling can support multiple pools of subscribers. That is, you can have two pools of subscribers, each pool receiving all the notifications from the event reference. The syntax of the event reference for the subscriber is:

enp+pool[.poolid]://domain/event

where poolid is a string using only base64 alphabet. (See RFC1521, Table 1, for what the base64 alphabet contains.) So, for example, to have two pools of subscribers to the event reference enp://127.0.0.1/store, each pool could subscribe to the following event references:

enp+pool.1://127.0.0.1/store --> for first pool of subscribers enp+pool.2://127.0.0.1/store --> for second pool of subscribers

Event Notification Service Architecture

---

On the Solaris platform, ENS runs as a daemon, enpd, along with other iPlanet daemons in various calendar or messaging server configurations, to collect and dispatch events that occur to properties of resources. On the Windows NT platform, 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.

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 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 iPlanet Calendar Server Interacts with ENS

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

Figure 1-1    ENS in iPlanet Calendar Server Overview

iPlanet 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 iPlanet Calendar Server installation. These three daemons interacting together implement event notification for iPlanet Calendar Server.

iPlanet Calendar Server Daemons

iPlanet 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 iPlanet 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.

iPlanet Calendar Server Example

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

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 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 iPlanet Calendar Server

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

Action	ENS Response
The csnotifyd daemon sends a subscription request to ENS.	ENS stores the subscription in the subscriptions database.
The csadmind daemon sends a notification request to ENS.	ENS queries the subscriptions database for subscriptions matching the notification.
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.
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 iPlanet Messaging Server Interacts with ENS

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

The iPlanet ENS server delivers notifications from the iPlanet 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, iPlanet Messaging Server publishes the notifications with the iBiff plug-in, but no iPlanet 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, iPlanet 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 iPlanet Messaging Server.

The iPlanet 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.

iPlanet 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.

Figure 1-3    ENS in iPlanet Messaging Server Overview

Event Notification Service API Overview

---

This section provides an overview of the two APIs for ENS, a C API and a Java API, which is a subset of the Java Messaging Service (JMS) API. Starting with iPlanet Messaging Server 5.2 and iPlanet Calendar Server 5.1, a Java API to ENS has been added. The Java API conforms to the Java Message Service specification (JMS). Two sample Java subscribers are provided using the JMS API.

For detailed information on the ENS C API, see Chapter 2 "Event Notification Service C API Reference." For detailed information on the Java (JMS) API, see Chapter 3 "Event Notification Service Java (JMS) API Reference." For JMS documentation, use the following URL:

http://java.sun.com/products/jms/docs.html

ENS C API Overview

ENS implements the following three APIs:

• Publisher API

  A publisher sends notification of a subscribed-to event to ENS, which then distributes it to the subscribers. Optionally, in iPlanet Calendar Server, the application can request acknowledgment of receipt of the notification. To do this, a Reliable Event Notification Link (RENL) is necessary. An RENL has a publisher, a subscriber, and a unique ID, which identify notifications that are subject to acknowledgment. The publisher informs the application of the receipt of an acknowledgment by invoking the end2end_ack callback passed to publish_a. Currently, only iPlanet Calendar Server supports RENL.

• Subscriber API

  A subscriber is a client to the notification service which expresses interest in particular events. When the notification service receives a notification about one of these events from a publisher, it relays the notification to the subscriber.

  A subscriber may also unsubscribe, which cancels an active subscription.

  In iPlanet Calendar Server, to enable an RENL, the subscriber declares its existence to ENS, which then transparently generates notification acknowledgment on behalf of the subscriber application. The subscriber can revoke the RENL at any time.

• Publish and Subscribe Dispatcher API

  When an asynchronous publisher is used, ENS needs to borrow threads from a thread pool in order to invoke callbacks. The application can either choose to create its own thread pool and pass it to ENS, or it can let ENS create and manage its own thread pool. In either case, ENS creates and uses a dispatcher object to instantiate the dispatcher used (pas_dispatcher_t).

  GDisp (libasync) is the dispatcher supported.

ENS Java API Overview

The Java API for ENS uses a subset of the standard JMS API, with the addition of two new proprietary methods:

• com.iplanet.ens.jms.EnsTopicConnFactory

• com.iplanet.ens.jms.EnsTopic

The following list of JMS object classes is used in the Java API for ENS:

• javax.jms.TopicSubscriber

• javax.jms.TopicSession

• javax.jms.TopicPublisher

• javax.jms.TopicConnection

• javax.jms.TextMessage

• javax.jms.Session

• javax.jms.MessageProducer

• javax.jms.MessageConsumer

• javax.jms.Message

• javax.jms.ConnectionMetaData

• javax.jms.Connection

  
  

  ---

  Note	The Java API for ENS does not implement all the JMS object classes. When customizing, use only the object classes found on this list.

  ---

  
  

Building and Running Custom Applications

To assist you in building your own custom publisher and subscriber applications, iPlanet Messaging Server and iPlanet Calendar Server include sample code. This section tells you where to find the sample code, where the APIs' include (header) files are located, and where the libraries are that you need to build and run your custom programs.

---

Note	This section applies to the C API only.

---

Location of Sample Code

iPlanet Calendar Server
iPlanet Calendar Server includes four simple sample programs to help you get started. The code for these samples resides in the following directory:

/opt/SUNWics5/cal/csapi/samples/ens

iPlanet Messaging Server
iPlanet Messaging Server 5.1 and higher contains sample programs to help you learn how to receive notifications. These sample programs are located in the server-root/bin/msg/enssdk/examples directory.

Location of Include Files

iPlanet Calendar Server
The include (header) files for the publisher and subscriber APIs are: publisher.h, suscriber.h, and pasdisp.h (publish and subscribe dispatcher). They are located in the CSAPI include directory. The default include path is:

/opt/SUNWics5/cal/csapi/include

iPlanet Messaging Server
The default include path for iPlanet Messaging Server is:

server-root/bin/msg/enssdk/include

Dynamically Linked/Shared Libraries

iPlanet Calendar Server
Your custom code must be linked with the dynamically linked library libens, which implements the publisher and subscriber APIs. On some platforms all the dependencies of libens must be provided as part of the link directive. These dependencies, in order, are:

1. libgap

2. libcyrus

3. libyasr

4. libasync

5. libnspr3

6. libplsd4

7. libplc3

iPlanet Calendar Server uses these libraries; therefore, they are located in the server's bin directory. The default libens path is:

/opt/SUNWics5/cal/bin

---

Note	For NT, in order to build publisher and subscriber applications, you also need the archive files (.lib files) corresponding to all the earlier mentioned libraries. These are located in the CSAPI library directory, lib. The default lib path is: drive:\Program Files\iPlanet\cal\csapi\lib

---

iPlanet Messaging Server
The libraries for iPlanet Messaging Server are located in the following directory:

server-root/bin/msg/lib

Refer to server-root/bin/msg/enssdk/examples/Makefile.sample to help determine what libraries are needed.This makefile contains instructions on how to compile and run the apub and asub programs. This file also describes what libraries are needed, and what the LD_LIBRARY_PATH should be.

Figure 1-4    Makefile.sample File

# # Sample makefile # # your C compiler CC = gcc # LIBS # Your library path should include <server-root>/bin/msg/lib LIBS = -lens -lgap -lxenp -lcyrus -lchartable -lyasr -lasync all: apub asub apub: apub.c $(CC) -o apub -I ../include apub.c $(LIBS) asub: asub.c $(CC) -o asub -I ../include asub.c $(LIBS) run: @echo 'run <server-root>/msg-<instance>/start-ens' @echo run asub localhost 7997 @echo run apub localhost 7997

---

Note

The Windows NT distribution includes the following additional files: server-root\bin\msg\enssdk\examples bin\msg\enssdk\examples\libens.lib bin\msg\enssdk\examples\libgap.lib bin\msg\enssdk\examples\libxenp.lib bin\msg\enssdk\examples\libcyrus.lib bin/msg\enssdk\examples\libchartable.lib bin\msg\enssdk\examples\libyasr.lib bin\msg\enssdk\examples\libasync.lib bin\msg\enssdk\examples\asub.dsw bin\msg\enssdk\examples\apub.dsp bin\msg\enssdk\examples\asub.dsp To build on Windows NT: A sample VC++ workspace is provided in asub.dsw. It has two projects in it: asub.dsp and apub.dsp. The required .lib files to link is in the same directory as asub.c and apub.c. To run, it requires that the following DLLs are in your path. libens.dll libgap.dll libxenp.dll libcyrus.dll libchartable.dll libyasr.dll libasync.dll The simplest way to accomplish this is to include server-root in\msg\lib in your PATH.

---

Runtime Library Path Variable

iPlanet Calendar Server
In order for your custom programs to find the necessary runtime libraries, which are located in the /opt/SUNWics5/cal/bin directory, make sure your environment's runtime library path variable includes this directory. The name of the variable is platform dependent:

• SunOS and Linux: LD_LIBRARY_PATH

• NT: PATH

• HPUX: SHLIB_PATH

iPlanet Messaging Server
For iPlanet Messaging Server, you need to set your LD_LIBRARY_PATH to server-root/bin/msg/lib.