Event Notification Service Overview

The Event Notification Service (ENS) is the underlying publish-and-subscribe service available in the following Sun Java^TM System communications products:

• Calendar Server

• Messaging Server

See Appendix B, Administering Event Notification Service in Messaging Server, in Sun Java System Messaging Server 6.3 Administration Guide for instructions on enabling and administering ENS in Messaging Server.

ENS acts as a dispatcher used by Sun Java System 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.

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

By default, ENS is enabled in Calendar Server. For 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 Calendar Server needs to write a subscriber.

Sample ENS C publisher and subscriber code is bundled with Calendar Server. (See ENS Sample Code for Calendar Server.) Once Calendar Server is installed, the code can be found in the following directory:

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

ENS in Messaging Server

ENS and iBiff (the ENS publisher for Messaging Server, also referred to as the notification plug-in to Messaging Server) are bundled in Messaging Server and ENS is enabled. However, the iBiff plug-in file, libibiff, is not automatically loaded at installation.

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

• Load the iBiff notification plug-in

• Stop and restart the messaging server

See Appendix B, Administering Event Notification Service in Messaging Server, in Sun Java System Messaging Server 6.3 Administration Guide for further instructions.

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

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

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

msg-server-base/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 Calendar Server and Messaging Server, the ENS scheme is enp.

• authority is the DNS domain or host name 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 Calendar Server events start with the following:

enp:///ics

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

enp://127.0.0.1/store

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.

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

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

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 Messaging Server, the user ID you specify is case sensitive.

This URI 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.

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