WS-Reliability is a SOAP-based specification that fulfills reliable messaging requirements critical to web service applications.
The objective of this post is not to discuss the features and architectural details of WS-Reliable Messaging (WS-RM). You can find the WS-RM specification from here and a lot of useful materials are available on the web. I'm going to demonstrate the simplest RM scenario, one-way single channel invocation using WSO2 mercury, which is an implementation of WS-RM using Apache Axis2.
WSO2 mercury is shipped as a module with WSO2 web services application server version 2.3 (WSO2 WSAS-2.3) as well as a separate piece of product. I'm going to describe the scenario using WSO2 WSAS, however you may also follow the given steps with Axis2-1.4 .
We are going to send a set of ping messages (one-way messages) to a web service in reliable manner. In other words, we send a set of requests to a service and block the channel at the middle of message transmission. Then we restart the transport channel. If WS-RM is not enabled, the message transmission will be lost when the transport channel goes down. You have to re-send messages. However, if our service and client are configured to use Wso2 mercury (WS-RM implementation), it will take care of guaranteed delivery of the rest of the messages when the transport channel is back again.
Lets see how reliable messaging can be used with WSO2 WSAS and Mercury.
Pre-requisites:
Install WSO2 WSAS-2.3
Step 1 - Service configuration
Create a simple web service implementation class as follows.
package org.wso2.wsas.service;
public class MercuryService{
//Oneway messaging
public void Ping(String s){
System.out.println("*****Received the ping request*****");
}
}
Compile and save the class.
Next, create a service descriptor (services.xml) as given below and save it in a META-INF directory.
<service name="MercuryService">
<Description>
Mercury test service
</Description>
<messageReceivers>
<messageReceiver mep="http://www.w3.org/2006/01/wsdl/in-only"
class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
<messageReceiver mep="http://www.w3.org/2006/01/wsdl/in-out"
class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
</messageReceivers>
<module ref="Mercury" />
<parameter name="ServiceClass" locked="false">
org.wso2.wsas.service.MercuryService
</parameter>
</service>
Note that <module> element is used to engage the Mercury module, which provides reliable messaging at the server side.
Now, create a deployable Axis2 service archive (*.aar) using the above service implementation class and META-INF/services.xml file. (Please have a look at Axis2 user guide if you are not familiar with service archive structure)
Copy the created service archive (Lets say it is "MercuryService.aar") to WSAS_HOME/repository/services directory. It will be deployed on WSAS. Start WSO2 WSAS using wso2wsas.bat{sh} and login in to admin console (https://localhost:9443)
Go to the services and service group management page and you should see the "MercuryService" there. Click on the service name. You will be directed to MercuryService's service management page. Click on "Manage Module Engagements" link. You will notice that the mercury module is listed under "Modules engaged at service level".
That's all for configuring RM at the web service level. Let's take a look at the client side configuration.
Step 2 - Generate stubs
First, we need to generate client side stubs through WSO2 WSAS management console. In the MercuryService's service management page, select "Generate Client". "Stub Generation" page will be displayed. Click on "Generate" with the code gen options as specified in the following image.
Save the generated jar file in your file system.
Step 3 - Write Client
Now write the client to invoke service in reliable manner. Make sure to add jars in WSAS_HOME/lib and the generated client stub jar in the previous step to your class path in order to compile the client.
package org.wso2.wsas.client;
public class OnewayAnnonSOAP11Client{
public static void main(String args[])throws AxisFault{
ConfigurationContext cc = ConfigurationContextFactory.createConfigurationContextFromFileSystem
("C:\\RM\\client-repo",C:\\RM\\client-repo\\conf\\axis2.xml");
MercuryServiceStub stub = new MercuryServiceStub(cc, "http://localhost:9080/services/MercuryService");
MercuryServiceStub.Ping request = new MercuryServiceStub.Ping();
request.setS("ping");
stub._getServiceClient().engageModule("Mercury");
for (int i = 0; i < 100; i++) {
try {
stub.Ping(request);
} catch (RemoteException e) {
e.printStackTrace();
} try
{ Thread.sleep(1000);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
// Setting the last message stub._getServiceClient().getOptions().setProperty("MercuryLastMessage", Constants.VALUE_TRUE);
try { stub.Ping(request);
} catch (RemoteException e) {
e.printStackTrace(); }
try { Thread.sleep(1000);
} catch (InterruptedException e) {
e.printStackTrace(); } } }
In order to get the reliable messaging support at the client, we need to engage Mercury module with "stub._getServiceClient().engageModule("Mercury")". We need to have ConfigurationContext to define the client repository where the Mercury.mar and axis2 configuration file (axis2.xml) is placed. Create a directory, client-repo and copy WSAS_HOME/repository/modules/mercury.mar to client-repo/modules directory. Also, create a sub-directory conf under client-repo and copy an axis2.xml file ( I have used axis2.xml copied from Axis2-1.4) in to that folder. You can call ping method of your webservice inside a loop so that multiple requests will be submitted. stub.Ping(request); In reliable messaging, a Sequence is created using a CreateSequence interaction, and terminated when finished with a TerminateSequence interaction. Therefore, a CreateSequence message is generated by client as the first step. If the CreateSequenceResponse message is received, then the actual application message delivery is started. Each message in a sequence has a message number, which starts at one and increments by one for each message. These message numbers are used to acknowledge the messages. In order to complete the sequence, the last message should be stated explicitly with stub._getServiceClient().getOptions().setProperty("MercuryLastMessage", Constants.VALUE_TRUE); Lets try to understand this scenario by sending messages via tcpmon. Start tcpmon and configure listen port as 9080 and target port as 9762.
Step 4 - Run client and monitor with TCPmon
Now run the client and check the messages delivered through tcpmon. You will notice that the first message is "CreateSequence". You will see that <wsrm:MessageNumber>1</wsrm:MessageNumber> soap header element in the next message where the actual ping request payload is transmitted.
Finally, check whether the messages are delivered reliably when your transport medium is interrupted. While the request soap messages are being sent, stop the incoming transport channel through tcpmon. You may do so by just stopping the port 9080. Wait a few seconds. Restart port 9080. You should see that the message transmission is resumed.
Thats all for now! will post more on WSO2 WSAS/Axis2 and RM soon.
