test

Sun Java System Communications Services 6 2005Q4 Event Notification Service Guide

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

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:

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:

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

ProcedureTo 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

ProcedureTo 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

ProcedureTo 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

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

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.

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.

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) 

                                throws java.io.IOException

Arguments

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

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

Miscellaneous