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. Two sample Java subscribers are provided using the JMS API.
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
For detailed information on the ENS C API, see Chapter 2, Event Notification Service C API Reference.
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 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 Calendar Server supports RENL.
Unreliable Publisher API
A publisher sends notification of an event to ENS, which distributes it to the subscribers. The term “unreliable” means that the API does not indicate whether a published event was successfully sent or received by a subscriber.
This communication model is suitable for some applications, but not for others. If you are concerned about transfer reliability, use the full-blown publisher API (publisher.h) instead. However, the Unreliable Publisher API has the merit of being easier to use if transfer reliability is not a concern.
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 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.
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
The Java API for ENS does not implement all the JMS object classes. When customizing, use only the object classes found on this list.
To assist you in building your own custom publisher and subscriber applications, Messaging Server and 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.
This section applies to the C API only.
Calendar Server includes four simple sample programs to help you get started. The code for these samples resides in the following directory:
cal-server-base/cal/csapi/samples/ens
Messaging Server 5.1 and higher contains sample programs to help you learn how to receive notifications. These sample programs are located in the following directory:
msg-server-base/examples
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:
cal-server-base/cal/csapi/include
The default include path for Messaging Server is:
msg-server-base/include
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:
libgap
libcyrus
libyasr
libasync
libnspr3
libplsd4
libplc3
Calendar Server uses these libraries; therefore, they are located in the server’s bin directory. The default libens path is:
/opt/cal-server-base/cal/bin |
For Windows, 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:\ProgramFiles\iPlanet\CalendarServer5\cal\ csapi\lib |
The libraries for Messaging Server are located in the following directory:
msg-server-base/lib
Refer to msg-server-base/examples/enssdk/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. The following listing shows a sample makefile.sample file.
# # Sample makefile # # your C compiler CC = gcc # LIBS # Your library path should include <msg-server-base>/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 <msg-server-base>/start-ens’ @echo run asub localhost 7997 @echo run apub localhost 7997 |
The Windows distribution includes the following additional files:
msg-server-base\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 platforms:
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 msg-server-base in\msg\lib in your PATH.
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
Windows: PATH
HPUX: SHLIB_PATH
For Messaging Server, you need to set your LD_LIBRARY_PATH to msg-server-base/lib.