Event Notification Service Java (JMS) API Implementation

The ENS Java API is included with Messaging Server and Calendar Server. The Java API conforms to the Java Message Service specification (JMS).

ENS acts as a provider to Java Message Service. Thus, it provides a Java API to ENS. The software consists of the base library plus a demo program.

Prerequisites to Use the Java API

To use the Java API, you need to load the ENS plug-in. For instructions on loading the ENS plug-in, see Appendix C in the Messaging Server Administration Guide. By default, ENS is already enabled.

In addition, you need to install the following software, which is not provided with either Messaging Server or Calendar Server:

• Java Development Kit (JDK) 1.2 or later

• Java Message Service 1.0.2a or later (tested with 1.0.2a)

You can download this software from:

http://java.sun.com.

Sample Java Programs

The Messaging Server sample programs, JmsSample and JBiff, are stored in the following directory:

msg_server_base/bin/msg/enssdk/java/com/iplanet/ens/samples

JmsSample is a generic ENS sample program. JBiff is Messaging Server specific.

For JBiff, you will need the following additional items:

• Java Mail jar file (tested with JavaMail 1.2)

• Java Activation Framework (required by JavaMail, tested with JAF1.0.1)

You can download these items from:

http://java.sun.com.

Instructions for Sample Programs

This section contains instructions for compiling and running the two sample programs:

• JmsSample Program

• JBiff Sample Program

JmsSample Program

To compile the JmsSample program

Steps

1. Set your CLASSPATH to include the following:

   ens.jar file - ens.jar

   (For Messaging Server, the ens.jar is located in the msg_server_base/java/jars/ directory.)

   Java Message Service - full-path/jms1.0.2/jms.jar

2. Change to the msg_server_base/bin/msg/enssdk/java directory.

3. Run the following command:

   javac com/iplanet/ens/samples/JmsSample.java

To run the JmsSample program:

Steps

1. Change to the msg_server_base/bin/msg/enssdk/java directory.

2. Run the following command:

   java com.iplanet.ens.samples.JmsSample

3. You are prompted for three items:

   • ENS event reference (for example, for Messaging Server: enp://127.0.0.1/store)

   • ENS hostname

   • ENS port (typically 7997)

4. Publish events.

   For Messaging Server, the two ways to publish events are:

   • You can use the apub C sample program for ENS. See Sample Code

   • If you have enabled ENS, configure iBiff to publish Messaging Server related events.

   For Calendar Server, events are published by the Calendar Server.

JBiff Sample Program

To compile the JBiff program

Steps

1. Set your CLASSPATH to include the following:

   ens.jar file - ens.jar

   (For Messaging Server, the ens.jar is located in the msg_server_base/java/jars/ directory.)

   Java Message Service - full-path/jms1.0.2/jms.jar

   JavaMail - full-path/javamail-1.2/mail.jar

   Java Activation Framework - full-path/jaf-1.0.1/activation.jar

2. Change to the msg_server_base/bin/msg/enssdk/java directory.

3. Run the following command:

   javac com/iplanet/ens/samples/JBiff.java

To run the JBiff sample program:

Before You Begin

To run the JBiff sample program, you need to load the ENS (iBiff) plug-in. See Appendix C in the Messaging Server Administrator’s Guide for instructions.

The demo is currently hardcoded to use the ENS event reference enp://127.0.0.1/store. This is the default event reference used by the iBiff notification plug-in.

Steps

1. Change to the msg_server_base/bin/msg/enssdk/java directory.

2. Run the following:

   java com.iplanet.ens.samples.JBiff

3. The program prompts for your userid, hostname, and password.

   The code assumes that the ENS server and the IMAP server are running on hostname. The userid and password are the IMAP username and password to access the IMAP account.

   The two test programs are ENS subscribers. You receive events from iBiff when email messages flow through Messaging Server. Alternately you can use the apub C sample program to generate events. See Sample Code for more information.