Sun Java System Communications Services 6 2004Q2 Event Notification Service Guide |
Chapter 3
Event Notification Service Java (JMS) API ReferenceThis 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 ImplementationThe 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:
You can download this software from:
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
directory. JmsSample is a generic ENS sample program. JBiff is Messaging Server specific.
For JBiff, you will need the following additional items:
You can download these items from:
Instructions for Sample Programs
This section contains instructions for compiling and running the two sample programs:
JmsSample Program
To compile the JmsSample program:
- 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
- Change to the msg_server_base/bin/msg/enssdk/java directory.
- Run the following command:
javac com/iplanet/ens/samples/JmsSample.java
To run the JmsSample program:
- Change to the msg_server_base/bin/msg/enssdk/java directory.
- Run the following command:
java com.iplanet.ens.samples.JmsSample
- You are prompted for three items:
- 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 for more information.
- 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:
- 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
- Change to the msg_server_base/bin/msg/enssdk/java directory.
- Run the following command:
javac com/iplanet/ens/samples/JBiff.java
To run the JBiff sample program:
Prerequisite: 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.
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.
- Change to the msg_server_base/bin/msg/enssdk/java directory.
- Run the following:
java com.iplanet.ens.samples.JBiff
- 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.
Java (JMS) API OverviewThe Java API for ENS uses a subset of the standard Java Messaging Service (JMS) API, with the addition of two new proprietary methods:
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
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
Implementation NotesThis 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 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.
- JMSType - The type of notification.
- Additional properties:
- 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.