Chapter 3   Event Notification Service Java (JMS) API Reference


This chapter describes the implementation of the Java (JMS) API in ENS and the Java API itself.

This chapter contains these sections:

• Event Notification Service Java (JMS) API Implementation

• Java (JMS) API Overview

• Implementation Notes

Event Notification Service Java (JMS) API Implementation

---

The ENS Java API is included with iPlanet Messaging Server 5.2 and Sun ONE Calendar Server 5.1. 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 ENS enabled. For instructions on enabling ENS in iPlanet Messaging Server, see Appendix C in the iPlanet Messaging Server 5.2 Administrator's Guide. By default, ENS is already enabled in Sun ONE Calendar Server.

In addition, you need to install the following software, which is not provided with either iPlanet Messaging Server or Sun ONE 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 iPlanet Messaging Server 5.2 sample programs, JmsSample and JBiff, are stored in the server-root/bin/msg/enssdk/java/com/iplanet/ens/samples directory. JmsSample is a generic ENS sample program. JBiff is iPlanet 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.

Setting Up Your Environment

This section describes what to do to be able to compile and run the sample programs.

To Compile the JmsSample Program

1. Set your CLASSPATH to include the following:

   ens.jar file - ens.jar

   (For iPlanet Messaging Server, the ens.jar is located in the server-root/java/jars/ directory.)

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

2. Change to the server-root/bin/msg/enssdk/java directory.

3. Run the following command:

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

To Compile the JBiff Program

1. Set your CLASSPATH to include the following:

   ens.jar file - ens.jar

   (For iPlanet Messaging Server, the ens.jar is located in the server-root/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 server-root/bin/msg/enssdk/java directory.

3. Run the following command:

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

To Run the JmsSample Program

1. Change to the server-root/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 iPlanet Messaging Server: enp://127.0.0.1/store)

   • ENS hostname

   • ENS port (typically 7997)

4. Publish events.

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

   • You can use the apub C sample program for ENS. See "iPlanet Messaging Server Sample Code" for more information.

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

   For Sun ONE Calendar Server, events are published by the calendar server.

To Run the JBiff Demo Program

Prerequisite: To run the JBiff demo program, you need to enable ENS in iPlanet Messaging Server. See Appendix C in the iPlanet Messaging Server 5.2 Administrator's Guide for instructions on enabling ENS.

---

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

---

1. Change to the server-root/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 iPlanet Messaging Server. Alternately you can use the apub C sample program to generate events. See "iPlanet Messaging Server Sample Code" for more information.

Java (JMS) API Overview

---

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

• com.iplanet.ens.jms.EnsTopicConnFactory

• com.iplanet.ens.jms.EnsTopic

JMS requires the creation of a TopicConnectionFactory and a Topic, which is provided by the two ENS proprietary classes.

For more information on the standard JMS classes and methods, see the JMS documentation at:

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

New Proprietary Methods

The two proprietary method classes are EnsTopicConnFactory and EnsTopic.

com.iplanet.ens.jms.EnsTopicConnFactory

About the method
The method is a constructor that returns a javax.jms.TopicConnectionFactory. Instead of using a JNDI-style lookup to obtain the TopicConnectionFactory object, this method is provided.

Syntax
public EnsTopicConnFactory (String name,
                              String hostname,
                              int port,
                              OutputStream logStream)

                  throws java.io.IOException

Arguments

Table 3-1    Arguments for EnsTopicConnFactory

Arguments	Type	Explanation
name	String	The client ID for the javax.jms.Connection
hostname	String	The hostname for the ENS server.
port	int	The TCP port for the ENS server.
logStream	OutputStream	Where messages are logged (cannot be null).

com.iplanet.ens.jms.EnsTopic

About this method
The method is a constructor that returns a javax.jms.Topic. Instead of using a JNDI-style lookup to obtain the javax.jms.Topic, this method is provided.

Syntax
public EnsTopic (String eventRef)

Arguments

Table 3-2    Arguments for EnsTopic

Arguments	Type	Explanation
eventRef	String	The ENS event reference.

Implementation Notes

---

This section describes items to be aware of when implementing the ENS Java API.

Shortcomings of the Current Implementation

The current implementation of the Java API does not supply an initial provider interface.

JMS Topic Connection Factory and ENS Destination are called out explicitly. These are com.iplanet.ens.jms.EnsTopicConnFactory and com.iplanet.ens.jms.EnsTopic. ENS does not use JNDI to get the TopicConnectionFactory and Topic objects.

Notification Delivery

The notification is delivered as a javax.jms.TextMessage. The parameter/values of the ENS event reference are provided as property names to the TextMessage. The payload is provided as the data of the TextMessage.

JMS Headers

• JMSDeliveryMode is always set to NON_PERSISTENT (that is, no storing of message for future delivery).

• JMSRedelivered is always set to false.

• JMSMessageID is set to an internal id. Specifically it is not set to the SMTP MessageID in the header of the email message for iPlanet Messaging Server.

• The payload is always a javax.jms.TextMessage. It corresponds to the ENS payload.

• JMSDestination is set to the full event reference (that is, it includes the parameter/values specific to this notification).

• JMSCorrelationID - Set to an internal sequence number.

• JMSTimestamp - Set to the time the message was sent.
  • For iPlanet Messaging Server and iBiff, this corresponds to the timestamp parameter.

  • This is unused in Sun ONE Calendar Server.

• JMSType - The type of notification.
  • For iPlanet Messaging Server and iBiff, this corresponds to the evtType parameter.

  • This is unused in Sun ONE Calendar Server.

• Additional properties:
  • Each parameter/value in the even reference becomes a property in the header. All property values are of type String.

• Unused headers are: JMSExpiration, JMSpriority, JMSReplyTo.

Miscellaneous

• MessageSelectors are not implemented.

• JMS uses the concept of durable and non-durable subscribers. A durable subscriber is a feature where notifications are guaranteed to be sent to subscribers even when they are offline, or if something catastrophic occurs, such as the ENS server going down after receiving the notification from the publisher but before delivering it to the subscriber.
  • Non-durable subscribers are implemented.

  • You can also use durable subscribers, however, the full functionality of being a durable subscriber is not implemented.

  • This aspect of being a durable subscriber is implemented: the publisher is acknowledged only after the subscriber receives a message.

  • This aspect of being a durable subscriber is not implemented: the message is not persistent, and delivery is not made to offline subscribers (after they come back online). In particular, JMSRedelivered is always set to false.