Getting started with WSRM and Axis2

This is a short HOWTO on getting your first WS-ReliableMessaging interaction going with Axis2 and Sandesha2. [Sandesha2 is an Open Source implementation of both the WSRM 1.0 and WSRM 1.1 specifications].

First, download the prereqs.

I'm proposing you do this with Axis2 1.2 - the latest release at the time of writing (May 2007).

Here is the download. You can use the standalone ZIP or the WAR file. I'm assuming you've already used Axis2 enough to know deploying services and creating clients.

The Sandesha2 1.2 release isn't yet available, so I'm posting a snapshot that you can use. As soon as it becomes available I'll point to the real thing.

Make the Version service Reliable
1) Take the version.aar file from the Axis2 distribution and edit the services.xml

Underneath the <services> tag add
<module ref="sandesha2">


You can either do it by hand, and update the AAR file (which is just a JAR file) or by go edit the build in <axis2_home>\samples\version.

I use 7-Zip file manager, which updates MAR and AAR files with any edits I make in-place which is great. I can just browse the AAR file, edit the XML, save it, and 7-Zip updates the AAR with my edits.

If you are too lazy to do either of those, I've posted the version.aar file with the updates here.

Add the right phases to Axis2
2) Edit your /conf/axis2.xml to add

<phase name="RMPhase"/>


Just between OperationIn/Out/InFault/OutFaultPhases and SoapMonitorPhase (4 places in all):

e.g.
<phase name="OperationInFaultPhase"/>
<phase name="RMPhase"/>
<phase name="soapmonitorPhase"/>

Deploy Sandesha2
3) Deploy sandesha2.mar into <AXIS2_HOME>/repository/modules

Check if its working
4) Start Axis2 and verify that the RM operations are listed when you
look at the version service via the browser
http://localhost:8080/axis2/services/

You should see extra operations listed under Version such as

• Sandesha2OperationInOut
• Sandesha2OperationOutIn
• getVersion
• Sandesha2OperationOutOnly
• Sandesha2OperationInOnly
• Sandesha2OperationDuplicate

Create a client
5) Build a client for the service using WSDL2Java:
\bin\wsdl2java.bat -uw -uri http://localhost:8080/axis2/services/Version?wsdl -o client

This will put the client code in .\client\ directory from where you ran the command.

WSDL2Java automatically creates an Ant build script, so you can test the build works using:
> ant

If you use Eclipse you can create a new project for this based on the Ant build.xml and you will get all the right libraries, etc. Just select File->New->Project, Java Project From Existing Ant Buildfile

6) Now go to .\client\src and add this Java class TestRM.java

import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import org.apache.axis2.transport.http.HTTPConstants;
import org.apache.axis2.transport.http.HttpTransportPropertie.ProxyProperties;

import sample.axisversion.VersionVersionSOAP12Port_httpStub;

public class TestRM {
public static void main(String[] args) throws Exception {

// use a config context to ensure I have
// the right Axis2.xml and Sandesha2 module
// Change the paths to fit your filesystem of course
ConfigurationContext cc = ConfigurationContextFactory.createConfigurationContextFrmFileSystem("c:/axis2-1.2/repository","c:/axis2-1.2/conf/axis2.xml");
// Use the generated Stub with the config Context
VersionVersionSOAP12Port_httpStub stub = new VersionVersionSOAP12Port_httpStub(cc,"http://localhost:8080/axis2/services/Version");

// WSRM prereqs Addressing
stub._getServiceClient().engageModule("addressing");

// Sandesha2 provides WSRM support
stub._getServiceClient().engageModule("sandesha2");

// go through a proxy so I can see what is happening
// dont forget to startup TCPMON - tcpmon 8001
ProxyProperties pp = new ProxyProperties();
pp.setProxyName("localhost"); pp.setProxyPort(8001);
stub._getServiceClient().getOptions().setProperty(HTTPConstants.PROXY,pp);

// This is the first message, so it will automatically kick off a CreateSequence
System.out.println(stub.getVersion());

// now mark the second message as the last
stub._getServiceClient().getOptions().setProperty("Sandesha2LastMessage","true");

// after the last message is sent, we should send a Terminate Sequence automatically
System.out.println(stub.getVersion());

// give enough time for it to work
Thread.sleep(1000);

// System exit because there will be Sandesha threads otherwise running
System.exit(0);
}
}

Let's just look at this code
Firstly, what is the overall flow? Simple! New up a stub, call stub.getVersion() twice and then exit. I've bolded the changes we make to be reliable.
So what have we added to make it work with RM?

• Instead of using the default config, we explicitly want Axis2 to read the modified axis2.xml and also to use the repository containing Sandesha2.mar. So we use a custom ConfigurationContext.
• Secondly, we want to see RM happening, so we set up a Proxy. For this we are going to use TCPMON.
• Thirdly, we need to engage Addressing and Sandesha to ensure the modules do their thing.
  
• We need to let Sandesha know when we are complete. There are a couple of ways to do this, but the very simplest is to mark the LastMessage. (This is based on WSRM1.0), so just before the second call to getVersion() we do this.
• Finally, Apache Sandesha spawns threads, so we do a Thread sleep and then a System.exit(0) which ensures that the code exits.
  

7) Build everything (Running ant in client\ should work).

8) Remember to start TCPMON up. It needs to be running in PROXY mode on port 8001.
You can do this by typing
> tcpmon 8001

9) If you used Ant to build the file then you can call the class like this:
> java -Djava.ext.dirs=\axis2-1.2\lib;\code\client\build\lib\ TestRM

Obviously this only works if your Axis2 is in \axis2-1.2 and you built the client in the \code directory, but you get the idea and can switch it to work.

10) You should see something like:
May 21, 2007 5:45:21 PM org.apache.axis2.deployment.ModuleDeployer deploy
INFO: Deploying module: addressing-1.2
May 21, 2007 5:45:22 PM org.apache.axis2.deployment.ModuleDeployer deploy
INFO: Deploying module: sandesha2
May 21, 2007 5:45:22 PM org.apache.axis2.deployment.ModuleDeployer deploy
INFO: Deploying module: soapmonitor-1.2
May 21, 2007 5:45:22 PM org.apache.sandesha2.SandeshaModule init
WARNING: Could not load module policies. Using default values.
May 21, 2007 5:45:22 PM org.apache.axis2.deployment.ServiceDeployer deploy
INFO: Deploying Web service: version.aar
Hello I am Axis2 version service , My version is 1.2
Hello I am Axis2 version service , My version is 1.2

11) If you look at the TCPMON Trace you should see 4 message interactions:
1. CreateSequence/CSR
2. Request 1
3. Request 2/LastMessage
4. TerminateSequence.

Congratulations - you have just got RM working (I hope!!!).