User Guide for WS-Messenger (WSMG)
The implementation can be downloaded at here.
To compile the package, run "ant" in the root directory (Needs to use ant version 1.6.1 or later). This command will compile the package and create a wsnt.jar file. You can also use "ant clean" to clean the compiled files.
WS-Messenger uses an MySQL database to keep all the information of the subscriptions. If the server crashes, the subscription information can be loaded automatically from the database when the WS-Messenger server restarts.
You can download MySQL database from here (I am using version 4.1).
1, You need to create a database in MySQL database, e.g. wsmg. (See MySQL document for how to create a database in MySQL) .
2, Then run the following command to create the "subscription" table: (The command is also available at db/mysqlCreationScript.txt in the package)
CREATE TABLE `subscription` (
`SubscriptionId` varchar(200) NOT NULL default '',
`xml` blob,
`ConsumerAddress` varchar(100) default '',
`ReferenceProperties` blob,
`Topics` varchar(255) default '',
`CreationTime` datetime NOT NULL default '0000-00-00 00:00:00'
);
3, Create an account for the WS-Messeneger server to access your database.
4, modify config/db.config file according to your database setup. You just need to setup the jdbcUrl string for accessing the database. Following is an example: (I created wsmg database in linbox3.extreme.indiana.edu machine. The username and password to access the database are both wsmg)
jdbcUrl=jdbc:mysql://linbox3.extreme.indiana.edu:3306/wsmg?user=wsmg&password=wsmg
Before running the examples, CLASSPATH needs to be set correctly.
In Windows, run "setenv.bat" to setup environment. (Since I am mostly using unix environment, this script may need to updated.)
In unix or linux, run "source setenv.sh" to setup environment.
IMPORTANT: You need to run this command on each terminal windows you started when you run the following commands.
Our implementaion can support various underlying messaging systems. Curently, NaradaBrokering messaging system (version 0.98rc1) and openJMS (version 0.7.6.1) are supported.
In the following command, "12345" is the port number of the services, you can choose different port number.
(1) To use openjms as underlying messaging system
First, start openJMS. You MUST start openjms BEFORE runing the command. See user guide for openjms on how to start openjms.
Then, run the following command from WSMG_Home/bin directory:
java wsnt.Server -port 12345 -carrier openJms -carrierLocation "rmi://rainier.extreme.indiana.edu:1099"
Note: "openjms" is specified as carrier.You need to run from bin directory since I use "../config/db.config" to specify the config file location. You can also modify startServer.sh in the bin directory if you are running in UNIX.
(2)To use NaradaBrokering as underlying messaging system.
First, start NaradaBrokering. You MUST start NaradaBrokering BEFORE runing the command. See user guide for NaradaBrokering on how to start NaradaBrokering.
Then, run:
java wsnt.Server -port 12345 -carrier narada -carrierLocation "rainier.extreme.indiana.edu:3045"
Note: "narada" is specified as carrier. The carrierLocation specifies the location of the NaradaBrokering. port is the port that the broker is listening for requests. .(3) Not use any underlying messaging system.
If you don't want to use any underlying messaging system, run
java wsnt.Server -port 12345Note: This feature currently has some bugs. It is not recommended. It will be fixed in future release.
You can test if your server working correctly by using the following command: (available in run_TestController.sh for Unix )
java wsnt.demo.leadCallBack.TestController -broker linbox1.extreme.indiana.edu:12345 -topic topic1 -listenPort 18888
Note: You need to change the broker to the URL of your broker. The topic can be any string. The listenPort specify the listening port that is going to receive the messages.
This command create a notification consumer that is listening at port 18888. Then create a subscription to the broker for this notification consumer. Then it publishs 15 test messages. When the notification consumer receives the last "FINISHED" message, it will stop the listener and send an unsubscribe message to the notification broker.
If you get some lines like the following, your server is running correctly.
".............
Got lock
Finished shuting down XC
Deleted Subscription.
Finished"
Steps 1-4 will show you the commands to accomplish the above testing steps seperately.
Currently, there is no tutorial on how to use the APIs of WS-Messeneger. You should be able to see how to do the following steps (subscribing, publishing, listening, unsubscibing) in the source code. It is very simple. You can see the sample code in the wsnt.demo package.
The major interface class is wsnt.WseClientAPI (For WS-Eventing) and wsnt.WsntClientAPI (for WS-Notification). You are welcome to contact me if you have any questions when you integrate WS-Messeneger into your system.
To receive notifications, you need to create NotificationConsumer web services. To create a Notification consumer, run:
java wsnt.demo.TestNotificationConsumer -port 19999
Note: The parameter "19999" is the port number that the notification consumer is listening.
You can create more than one notification consumers by using different port numbers.
To subscribe, run the following command:
java wsnt.demo.TestWSE_Subscriber -consumer linbox1.extreme.indiana.edu:19999 -producer linbox1.extreme.indiana.edu:12345 -topic TestTopic -epr yihuan
The consumer parameter specifies the URI of the notification consumer client.
The producer parameter specifies the URI of the notification producer (or broker). This is URI that the subscription request will be sent.
"TestTopic" is the topic of the subscription. You can subscribe different topics. Currently, the only topic dialect supported is "SimpleTopic Expression" specified in WS-Topics specification, which is a topic string without any wildcard or path.
"epr" specifies the Endpoint Reference of the notification Consumer. This is an optional argument.
To publish a message, run the following:
java wsnt.demo.TestWSE_Publisher -consumer linbox1.extreme.indiana.edu:12345 -topic TestTopic -message "<words>Hello World</words>"
The consumer parameter specifies the URI of the notification consumer (or broker) client.
"TestTopic" is the topic of the publishing. You can publish to different topics.
The message parameter specifies the content of the message.
After you publish a message, you can see the notification consumers you set up in step 5 got your message if you have subscribed them in step 6. This shows the basic senario of WS-Notification.
To delete a subscription using destroy message defined in WS_ResourceLifetime.
java wsnt.demo.WSE_DeleteSubscription -subManager linbox1.extreme.indiana.edu:12345 -subId sub3@1105735534908
subManager specifies the location of the subscription Manager. The subId is the subscription ID of the subscription.
To show all subscriptions in a broker:
java wsnt.demo.showAllSubscriptions -producer linbox1.extreme.indiana.edu:12345
producer specifies the location of the WS-Notification broker.
Beside the commandline client, WS-Messenger also provides some GUI tools to help you monitoring the broker, debugging and manage the subsccription.
WS-Eventing Listener GUI is useful for monitoring the event traffic and debugging in the distributed systems. This GUI can listen to the events sent by the broker.
You can download the excutable jar file from here. Then double click it to run it. You can also run it using this command:
java -jar WseViewer.jar
The notification listener GUI is a notification consumer. It waits for notifications to arrive at the port specified by the "port" you set in the GUI. When you click the "Start" button, it subscribes to the broker and starts the listener. When you click the "Stop" button, it will stop the listener and unsubscribe. You can click "Clear Messages" button to clear the messages in the textarea.
Brief Messages View
Whole message view
You can manage your subscription through the Administration web page (http://rainier.extreme.indiana.edu:16666/nmi/wsnt/subscriptionmanager). You can view all subscriptions and delete subscriptions. You just need to enter your broker URL and click "Check Subscription" button.
11. Contact
Created: 5/4/2004
Modified: 6/17/2004
Modified: 10/12/04
Modified: 1/14/05