Previous Contents Index Next |
iPlanet Messaging and Collaboration Event Notification Service Manual |
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
Event Notification Service Java (JMS) API Implementation
The ENS Java API is included with iPlanet Messaging Server 5.2 and iPlanet 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 iPlanet Calendar Server.In addition, you need to install the following software, which is not provided with either iPlanet Messaging Server or iPlanet Calendar Server:
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)
You can download these items from http://java.sun.com.Java Activation Framework (required by JavaMail, tested with JAF1.0.1)
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
Set your CLASSPATH to include the following:
Change to the server-root/bin/msg/enssdk/java directory.
- 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
- javac com/iplanet/ens/samples/JmsSample.java
Set your CLASSPATH to include the following:
Change to the server-root/bin/msg/enssdk/java directory.
- 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
- javac com/iplanet/ens/samples/JBiff.java
Change to the server-root/bin/msg/enssdk/java directory.
You are prompted for three items:
- java com.iplanet.ens.samples.JmsSample
ENS event reference (for example, for iPlanet Messaging Server: enp://127.0.0.1/store)
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 iPlanet 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.
Change to the server-root/bin/msg/enssdk/java directory.
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.The program prompts for your userid, hostname, and password.
- java com.iplanet.ens.samples.JBiff
- 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.
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: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)
Arguments
Table 3-1    Arguments for EnsTopicConnFactory
Arguments
Type
Explanation
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
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.
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.
JMSType - The type of notification.This is unused in iPlanet Calendar Server.
For iPlanet Messaging Server and iBiff, this corresponds to the evtType parameter.
Additional properties:This is unused in iPlanet Calendar Server.
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.
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.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated January 31, 2002