14 Event Notification Service API Reference

Client API ens_sopen

The client API, ens_sopen, can connect to the ENS broker with authentication.

Customers who want to connect to the ENS broker use the API ens_open declared in ens.h to create a new client connection to the ENS broker. The API, ens_open, does not support authentication and TLS/SSL.

So we added a new API, ens_sopen, to create a secure connection to the ENS broker that supports authentication and TLS/SSL. The arguments to the API, ens_sopen, include all the arguments to the API, ens_open, and also includes arguments to accept an username and a password for authentication. It also includes an argument to specify whether to use TLS/SSL while making an connection to the ENS Broker specified.

The new API declared in lib/ens/ens.h is:

ensclient_t* ens_sopen (const char* host, int port, int use_ssl, const char* auth_user, const char* auth_secret, lost_cnx_cb_t lost_cnx_cb, void* lost_cnx_arg);

In order to connect to the ENS brokers that support TLS/SSL and authentication, you must use the new API, ens_sopen. The API accepts the arguments auth_user and auth_secret, but it may or may not use them depending on whether or not the ENS broker it is connecting to requires authentication.

If the connection is made to the SSL port, then the value for the argument, use_ssl, must be 1. If the connection is made to the non-SSL port, then the value for the argument, use_ssl, must be 0.

Sample ENS-JMS Consumer Program

To use Sample ENS-JMS consumer program, the messaging server should be configured for ENS. See "Administering Event Notification Service" and "Messaging Server Specific Event Notification Service Information" for more information on ENS.

Below is the sample JMS consumer of ENS messages which consumes the messages from the default topic and prints the messages.

/**
* A consumer that can connect to a ENS Server and printMessages as JMS messages.
*/
public class JMSConsumer {
 
String hostname = "localhost";
int port = 7997;
boolean printMessages = true;
private String topicName = "store";
 
/**
* Constructor for creating a JMS consumer.
*/
JMSConsumer() {
}
 
/**
* start - starts the JMS consumer which waits to receive a event from the
* messaging server. This waits for the event and prints the message got.
*
* @throws JMSException
*/
public void start() throws JMSException {
/**
* Create a EnsTopicConnFactory which creates a connection to the ENS
* Broker. If you want to use the Same code for a different JMS
* provider, all you have to do is to change the ConnectionFactory to
* that of the corresponding broker.
* eg. TopicConnectionFactory connFactory = new newcom.sun.messaging.ConnectionFactory();
* can be replaced by
* TopicConnectionFactory connFactory = new EnsTopicConnectionFactory("ens-conn-factory", hostname, port);
* to use the OpenMQ as a broker to receive JMS Messages. 
*/
TopicConnectionFactory connFactory = new EnsTopicConnectionFactory("ens-conn-factory", hostname, port);
TopicConnection topicConn = connFactory.createTopicConnection();
TopicSession topicSession = topicConn.createTopicSession(false,
Session.AUTO_ACKNOWLEDGE);
Topic topic = topicSession.createTopic(topicName);
TopicSubscriber topicSubscriber = topicSession.createSubscriber(topic);
topicConn.start();
TextMessage message = (TextMessage) topicSubscriber.receive();
if (printMessages) {
printMessage(message);
}
topicSession.close();
topicConn.close();
}
 
public static void main(String[] args) throws JMSException {
JMSConsumer cons = new JMSConsumer();
cons.start();
}
 
/**
* printMessage - prints the Contents of the JMS messages received.
*
* @param message
* @throws JMSException
*/
private void printMessage(TextMessage message) throws JMSException {
system.out.println("----Start of Message------ \n");
System.out.println("JMSCorrelationID:+" + message.getJMSCorrelationID() + "\n");
System.out.println("JMSMessageID:+" + message.getJMSMessageID() + "\n");
System.out.println("JMSType:+" + message.getJMSType() + "\n");
System.out.println("JMSDeliveryMode:+" + message.getJMSDeliveryMode() + "\n");
System.out.println("JMSDestination:+" + message.getJMSDestination() + "\n");
System.out.println("JMSExpiration:+" + message.getJMSExpiration() + "\n");
System.out.println("JMSPriority:+" + message.getJMSPriority() + "\n");
System.out.println("JMSRedelivered:+" + message.getJMSRedelivered() + "\n");
System.out.println("JMSReplyTo:+" + message.getJMSReplyTo() + "\n");
System.out.println("JMSTimestamp:+" + message.getJMSTimestamp() + "\n");
System.out.println("Properties:\n");
// Print the Properties
Enumeration keys = message.getPropertyNames();
while (keys.hasMoreElements()) {
String key = (String) keys.nextElement();
System.out.println(key + "  -> " + message.getStringProperty(key) + "\n");
}
System.out.println("----End of Properties----\n");
System.out.println("Body:+" + message.getBody(String.class) + "\n");
System.out.println("----End of Message------ \n");
System.out.println("received: " + message.getText());
}

Sample ENS-JMS Consumer Using Automatic Failover and Properties File

Below is the file that has the mapping from the logical hostname to a list of physical hostnames:

bash-3.2$ cat /local/harokias/hostmap.properties
 
# The mapping from logical mailhost name to a list of physical hostnames
# mailhost1 mapping
mailhost1.hostlist = host1 host2 host3
 
# mailhost2 mapping
mailhost2.hostlist = host4 host5 host6

If automatic failover and properties file are to be used then you should made following change in the sample ENS-JMS consumer program:

TopicConnectionFactory connFactory = new EnsTopicConnectionFactory("ens-conn-factory", <"mailhost1">,<"local/harokias/hostmap.properties">, port);