Part I: Download and setup

1. Download

2. Compile

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)

3. Setup CLASSPATH

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 "sourcesetenv.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

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 )

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.

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

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

Depending on whether a topic String or an XPath expression is available
in a "subscribe" request, there are three possible types subscriptions
in WS-Messenger, topic only, XPath content only
and both topic and content. This is shown in the following
table.

Topic available

Topic unavailable

XPath available

filtering XML contents within a topic

XPath only

XPath unavailable

Topic only

not allowed

A modified version of YFilter
is used in WS-Messenger as XPath filtering engine. The major modification
of YFilter is to enable it processing XML messages with namespaces. The
supported XPath is available in YFilter's manual at here.
Currently namespaces are ignored in message filtering when messages have
namespaces. You can not filter by namespaces. Sample subscribe messages
for each case are available here.

(3) Filtering XPath content within a topic

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.

"epr" specifies the Endpoint Reference of the
notification Consumer. This is an optional argument.

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

xpath specify interested XML content. The supported XPath is available
in YFilter's manual at here.
Please note, you need to escape quote marks ("") using "\"
in XPath following java String's rule.

5. Delete a Subscription

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:

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

Please contact Yi
Huang (yihuan AT cs.indiana.edu) for any problems or questions.