WS-Messenger API Guide
This API guide will help you in integrating WS-Messenger with your java applications so that your applictaions can publish and receive WS-Eventing or WS-Notification messages. More information about using WS-Messenger is available at the user's Guide.
The client class that needs to use WS-Messenger is WseClientAPI or WsntClientAPI. In LEAD project, we use WseClientAPI.
There are many jar files in the downloaded package. However, you only need wsmg-XXX.jar, xpp-XXX.jar and xsul-XXX.jar in the package if you just need to publish and receive notification messages. XXX is different version. xpp-XXX.jar and xsul-XXX.jar are in the lib directory of the WS-Messenger package. wsmg-XXX.jar need to run "ant jar" to create or you can download it from here. Put these jar files in your CLASSPATH.
Add the following import in your java program.
import wsmg.WseClientAPI;
To use WS-Notification, use
import wsmg.WsntClientAPI;
The preferred interface is WseClientAPI since we are using it for our projects and it is most up-to-date.
The WSEClientAPI provides provides two modes of operations.
Stateless API requires all the relavent information to be available at the time of the publishing of the message. Once a message is published user is not suppose to assume that the client remembers the broker location, infact it does not. Following code segment illustrates the usage of the API.
//Create the client
WseClientAPI client = new WseClientAPI();
String brokerLocation = "rainier.extreme.indiana.edu:12346";
String topic = "tutorialTopic";
String message ="<words>Tutorial test message</words>";
//publish specifing the broker location , topic and the message
client.publish(brokerLocation, topic, message);
//publishing again: again have to specify the broker location, topic and the
message
client.publish(brokerLocation, topic, "<words>second message</words>");
You can use MessageViewer to verify that you publish message successfully to the broker. See "GUI tools" in the userGuide on how to get it and how to use it.
The stateful API allows the user to create an stateful client that remembers the location of the broker and it allows the user to publish multiple messages to that particular broker, without having to re-specify the broker location again and again. The programmin gmodel is illustrated in the following code segment.
WsaEndpointReference epr = WseClientAPI.createEndpointReference("http://rainier.extreme.indiana.edu:12346",
"TutorialTopic");
//instantiate a client with that given epr
WseClientAPI client = new WseClientAPI(epr);
//now you can publish
client.publish("publishing test msg using stateful client");
//Convenience is you could reuse the client
int repetitions =10;
for(int i=0; i<repetitions ; i++){
client.publish("<messageNumber>"+i+"</messageNumber>");
}
See TestWSE_Subscriber.java in wsmg.demo package for the simple example to publish.
WseClientAPI client = new WseClientAPI();
String subscriptionId=client.subscribe(producer, consumer, topic);
Here are some sample code:
//Create the client
WseClientAPI client = new WseClientAPI();
//Where you will be subscribing to now
String brokerLocation = "rainier.extreme.indiana.edu:12346";
//The location where you will be expecting the events to come. Most probably
your local machine.
// A public IP is required.
String consumerLocation = "brick.extreme.indiana.edu:1111";
String topic = "tutorialTopic";
String subscriptionid = client.subscribe(brokerLocation, consumerLocation, topic
);
//now at a later time you want to unsubscribe
//client.unSubscribe(brokerLocation, subscriptionid);
You can just add an XPath String parameter to the current subscribe() method to use the XPath filtering capability. For example,
WseClientAPI client = new WseClientAPI();
client.subscribe(producer, consumer, topic, xpath);
If topic is null, it will create XPath only subscriptions.
Sample XPath string I used in my test is "//properties/value[text()=\"FINISHED_SUCCESS\"]". This selects message with "FINISHED_SUCCESS" as the text of the "value" element. I use YFilter as XPath filtering engine. The supported XPath is available in YFilter's manual at here
To create a notification consumer, a class that implements a NotificationHandler interface is needed. The interface has only one method: handleNotification(String soapMessage). The user can put the business logic to handle the received messages in this method. Then the user needs to call startConsumerService(port, handler) to start a listener at the specified port and use the specified handler to handle received notification messages.
See TestNotificationConsumer.java in wsmg.demo package for the simple example to publish.
// Create the client
WseClientAPI client = new WseClientAPI();
int port = 1111;
NotificationHandler handler = new DefaultNotificationHandler();
//start listening
int listenPort = client.startConsumerService(port, handler );
The DefaultNotificationHandler class is a class the implements NotificationHandler.
To simplify the API, we don't throw checked exceptions in the API. Most exceptions are not expected to be handled by WS-Messenger users. The WS-Messenger throws WsmgRuntimeException when exception happens.
If you don't want a WsmgRuntimeException to stop your program, you need to catch the WsmgRuntimeException. For example, you can use this method to prevent a publish failure that bring the whole application to a halt. If you want to handle a specific kind of exception, you can use rethrow() method in the WsmgRuntimeException to rethrow the original exception and handle the exception.See here for more information about this.
This is a example from TestWSE_Subscriber.java in wsmg.demo package.
try{
String subscriptionId=client.subscribe(producer, consumer, topic);
System.out.println("SubscriptionId="+subscriptionId);
} catch(WsmgRuntimeException wre) {
// thrown only if some Exception was thrown
try {
wre.rethrow();
} catch(URISyntaxException e) {
System.out.println("Caught URI Exception");
// thrown when someObject isn't a valid URI
}
catch(Exception e) {
// other checked exceptions, which we
// could throw as checked or unchecked
// as needed
throw wre;
}
}
You can use MessageViewer to verify that you publish message successfully to the broker. See "GUI tools" in the userGuide on how to get it and how to use it.
Created: 12/8/2005
Updated: 10/27/2006