User Guide for WS-Messenger (WSMG)

 

Part I: Download and setup

1. Download

The implementation can be downloaded from WS-Messenger home page.

2. Compile

You need JDK5 to compile and run the code.

Unzip the zip file. 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. To create a jar file, use ant jar. This command will create a wsmg.jar file (with version number) in the build/lib directory. You can also use "ant clean" to clean the compiled files.

Note: if you get "java.util.zip.ZipException: error in opening zip file" exception in the compilation, you need to clean up the CLASSPATH in your shell environment. Use

export CLASSPATH=""

to clean the CLASSPTH. This is caused by a bug in JDK5 (See here). JDK version later than 1.5.0_07-b03 should fixed this problem.

3. setup database

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 skip the step of setting up database if you don't want to save the subscriptions. However, you will get exceptions about database connection when you run the server. You can ignore these exceptions. )

You can download MySQL database from here (I am currently using version 5, but at least version 4.1 should be fine since we have been using that until 9/2006).

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 commands in mysqlCreationScript.txt to create the required tables. (The file is available at db/mysqlCreationScript.txt in the package)

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

3. Setup CLASSPATH

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.

Part 2: Start WS-Messeneger broker (server)

1. start the WS-Messenger broker (server)

Our implementation can support various underlying messaging systems. Currently, NaradaBrokering messaging system (version 0.98rc1) and openJMS (version 0.7.6.1) are supported. You may experience problem if you use other versions.

In the following command, "12345" is the port number of the services, you can choose different port number.

(1) Not use any underlying messaging system (Recommended).

If you don't want to use any underlying messaging system, run the following command from bin directory
java wsmg.Server -port 12345

This is the easiest way to start the broker.

(2) To use other underlying messaging systems (optional)

Our implementation can support various underlying messaging systems. Currently, NaradaBrokering messaging system (version 0.98rc1), openJMS (version 0.7.6.1) and activeMQ (verions 3) are supported. You may experience problem if you use other versions. See the information guide here.

Please also note, since we are currently using our own message filtering for simple topic filtering and XPath filtering. These underlying messaging systems may experience problem since they are not tested with each latest release.

(3) running server at background

You can use "nohup" command to run the server at background, for example:

nohup startServer.sh

Note: startServer.sh is a shell script in the bin directory. You need to modify it to fit your need. It runs the command above.

(4) show debug information on the server

You can show the debug information about the server when you add "-Dlog=:ALL" (all debug information) or "-Dlog=wsmg:ALL" (only wsmg debug information) to your java command. For example:

java -Dlog=:ALL wsmg.Server -port 12345

(5) Running the broker in a Tomcat server.

After everything works fine in the command line. You can also deploy the broker server in a Tomcat server to get better scalability. Tomcat installation document can be found here.

2. Test Your WS-Messenger Server.

You can test if your server working correctly by using the following command in another console: (available in run_TestController.sh for Unix )

java wsmg.demo.leadCallBack.TestController -broker localhost: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 publishes 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"

Part 3: Command line test client.

Steps 1-4 will show you the commands to accomplish the above testing steps separately.

WS-Messenger guide is available here to help you integrate WS-Messenger with your application so that your application can publish and receive WS-Eventing or WS-Notification messages. You should be able to see how to do the following steps (subscribing, publishing, listening, unsubscribing) in the source code. It is very simple. You can see the sample code in the wsmg.demo package.

The major interface class is wsmg.WseClientAPI (For WS-Eventing) and wsmg.WsntClientAPI (for WS-Notification). You are welcome to contact me if you have any questions when you integrate WS-Messeneger into your system.

1. start NotificationConsumer client

To receive notifications, you need to create NotificationConsumer web services. To create a Notification consumer, run:
java wsmg.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.

2. subscribe

3. publish

To publish a message, run the following:
java wsmg.demo.TestWSE_Publisher -consumer localhost: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 1 got your message if you have subscribed them in step 2. This shows the basic scenario of WS-Notification.

4. Show all subscriptions

To show all subscriptions in a broker:
java wsmg.demo.showAllSubscriptions -producer localhost:12345

producer specifies the location of the WS-Notification broker.

Note: this operation is not defined in the specifications. However, we feel it is a convenient method to monitor and debug the notification system.

5. Delete a Subscription

To delete a subscription using destroy message defined in WS-ResourceLifetime.
java wsmg.demo.WSE_DeleteSubscription -subManager localhost:12345 -subId sub3@1105735534908

subManager specifies the location of the subscription Manager. The subId is the subscription ID of the subscription.

 

Part 4: GUI tools

Beside the command line client, WS-Messenger also provides some GUI tools to help you monitoring the broker, debugging and manage the subscription.

1. WS-Eventing Listener GUI

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 executable 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 text area.

You can also change the default values when the event viewer starts up. Possible parameters include broker, topic, listenPort. You can also set the event viewer to start automatically using the "autoStart" flag. Here is a sample command:

java -jar WseViewer -broker tyr11.cs.indiana.edu:12346 -topic myTopic -listenPort 18888 -autoStart

If you are behind a firewall, you can select "MsgBox URL" to specify a message box location. The message viewer will periodically "pull" messages from a message box. The default value "rainier.extreme.indiana.edu:13333/MsgBox" is a message box running at our Extreme lab (It may not be running all the time. Let me know if you need it). You can create your own message box using our WS-MsgBox. It needs to be running in a server that is outside of the firewall or can open a listening port that can receive messages from the notification server.

Please remember to click the "stop" button before you close the event viewer. This will unsubscribe the event viewer client from the broker.

Brief Messages View

Whole message view (click for larger view)

2. Subscription Administration web interface.

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.

 

Document for LEAD project

Document for LEAD project is available here. It has information specific to LEAD project.

Contact

Created: 5/4/2004
Modified: 6/17/2004
Modified: 10/12/04
Modified: 1/14/05, 4/14/2005 9/20/2005, 10/11/2005, 3/3/2006, 10/28/2006, 1/30/2010