Sandesha + Axis2
If you’re familiar with WSO2 WSAS, you might know about its SOAP implementation. It uses Apache Axis2 to implement the SOAP specification. This leads to a natural choice for its WSRM implementation: Apache Sandesha2. Sandesha was built to work with Axis2. It’s implemented as an Axis2 module.

Axis2 provides a great pluggable architecture that lets you add modules that implement extra behavior on top of SOAP. In the case of Sandesha, extra metadata and processing is done at the exit of outbound messages and at the entrance of inbound messages. This lets Sandesha implement the WSRM specification transparently to the rest of the Axis2 stack and thus transparently to the clients and servers that rely on the Axis2 stack to send or receive SOAP messages.

Besides being a full implementation of WSRM and specifically designed for Axis2, Sandesha has an impressive feature list. It has a pluggable persistence mechanism (see the section on Persistence). It provides a listener mechanism to allow customized logic to handle events such as when a sequence times out. It has a powerful reporting feature that gives you instant information on the Sandesha subsystem and any ongoing deliver sequences. Its configuration from both the server and client perspective is a snap. Let’s take a look at how you’d configure both Web Services and Web Service clients to use WSRM with WSO2 WSAS.

Configuring a Service for WSRM
Let’s take a Web Service and enable WSRM for it. This will let clients send it messages that take advantage of WSRM. Now one of the key aspects of WSRM is that this has to be transparent to your service. You don’t have to change any of the code for your service to enable WSRM. As it turns out, there are a couple of ways to do this.

The first way to enable WSRM uses Axis2’s Web Service descriptor. This is the services.xml for your Web Service. An example of a WSRM-enabled Web Service descriptor is shown in Listing 2.

Most of this is just normal Axis2 elements and configuration options. The only thing we did to enable WSRM was to add the sandesha2 module. We didn’t have to do anything else.

That’s pretty easy, but WSO2 WSAS makes it even easier. WSAS’s Management Console is a powerful graphical interface for managing Web Services. You can use it to enable WSRM for any Web Service. Just log in and go to Services -> <Your Service> -> Manage Module Engagements. You can then select sandesha2 as shown in Figure 3.

After you select sandesha2 and click the Engage button, the UI will be refreshed to show that sandesha2 has been engaged and so WSRM has been enabled, as shown in Figure 4.

With just a few clicks we enabled WSRM on any Web Service deployed on WSO2 WSAS. Now let’s take a look at creating a Web Service client that will use WSRM to send reliable messages to a WSRM-enabled Web Service.

Configuring a Client for WSRM
Enabling WSRM for a Web Service running on WSO2 WSAS was very easy. It’s not much harder to enable it on the client as well. Let’s take a look at the code for doing this in Listing 3.

This code is just like any other Axis2 client code you would write, but with a couple of notable exceptions. The class org.apache.axis2.client.Options let’s us set Axis2 options on our org.apache.axis2.client.ServiceClient instance that we use to send SOAP messages to the WSRM-enabled Web Service. We use this class to enable WSRM by using the engageModule API. That’s all it takes on the client to enable WSRM.

There’s one other thing you might notice in Listing 3. In the code, two messages are sent. After the first one is sent, we add another option. This is the “last message” option that tells Sandesha to add this metadata to the SOAP header on our message, as seen in Listing 1.

WSAS Extensions to WSRM: Persistence
The WSRM specification is what is known as a wire-only specification. This means that it only specifies the behavior of messages being sent. It doesn’t specify how clients and servers should deal with messages before they’re sent or after they’re received. The network itself is a major cause of unreliable messaging, but the clients and servers can also be the cause.

WSAS contains an extension to WSRM, adding persistence to messages. There are two kinds of persistence or storage. The default is in-memory storage. This is just what it sounds like. A WSAS service will keep track of which messages have been received, along with acknowledgments, etc., in memory. This is very fast, but obviously there could be problems in case of a crash. An acknowledgment might not be sent out, for instance. An alternative is permanent storage, which is typically storage in a database. This allows for the recovery of state after a crash.

How do you configure storage? Luckily the WS-Policy standard is made for extensibility, so it can be leveraged to add things like storage. Listing 4 shows a policy specifying the in-memory and permanent StorageManagers.

Of course you can use different StorageManager implementations rather than the default ones shown here. To enable permanent storage on your Web Service, simply add a line of XML to your service.xml descriptor, as shown here:

<parameter name=”Sandesha2StorageManager”>persistent</parameter>

That’s all you need to do to enable persistence on top of reliable messaging with WSAS.

Summary
In this article we’ve taken a look at the unreliability of the Internet. We’ve seen how WSRM addresses this problem with a standardized and powerful solution. We’ve looked at how WSRM works with SOAP. Finally, we took a look at WSO2 WSAS’s implementation of WSRM using Axis2 and Sandesha. We saw how easy it is to enable WSRM on both clients and services using WSAS. WSO2 WSAS provides an easy turnkey solution to enable a modern SOAP stack with various WS-* technologies, including WSRM.

Resources

• “WSRM and WS-R: Can SOAP be reliably delivered from confusion?”
• WSRM specification from the developerWorks library
• How WSRM and WS-Polling can be used together:
  
• “Use Apache Sandesha to support Web services implementation”
  
• Download WSO2 WSAS
• The latest features in WSO2 WSAS 2.1
• The WSO2 community on the WSAS Wiki
• Web services and Axis2
• “SOA with Axis2”
• TSS Interoperability blog