Sandesha2 User Guide

This document introduces you to Apache Sandesha2. Sandesha2 is the WS-ReliableMessaging implementation for Axis2. With Sandesha2 you can host some reliable web services or interact with reliable web services hosted by others.

Using Sandesha2 in the server side

First lets look at how to use Sandesha2 in the server side.

You can set up Sandesha2 for the server side with following steps.

Download and deploy axis2(please see Axis2 user guide for more details).
Add a user phase called RMPhase to all four flows of axis2.xml.
Download latest Sandesha2 distribution and add Sandesha2 mar file to <AXIS2_WEBAPP>\WEB_INF\modules directory.
Add sandesha2.properties file to the <AXIS2_WEBAPP>\WEB_INF\classes directory.

Now your Sandesha2 module is setup and deployed.

To host reliable web service you have to create a service archive (aar) file with the given details (please see Axis2 user guide for more details on creating aar files).

Add a module reference for Sandesha2 to the services.xml (within the aar file) as given below.

<service name="TestService">
<module ref="Sandesha2-0.9"/>
.......................
<!-- Your operation definitions and other stuff
........................
</service>

Create the service archieve file.

Deploy it by dropping it to <AXIS2_WEBAPP>/WEB-INF/services directory.

Now your service is deployed with reliable messaging support.

Using Sandesha2 in the client side

Add Sandesha2 module in the way you normally add a module to the Axis2 client side (see Axis2 user guide for more details). Following scenarios will explain you how to write the client code.

Basic scenarios

Sample RM enabled client code for a one way service call.

MessageSender sender = new MessageSender (AXIS2_CLIENT_REPO_PATH);
sender.engageModule(new QName ("Sandesha2-0.9"));
Options clientOptions = new Options ();
sender.setClientOptions(clientOptions);
clientOptions.setProperty(Options.COPY_PROPERTIES,new Boolean (true));
clientOptions.setTo(new EndpointReference(toEPR));
sender.send("ping",getPingOMBlock("ping1"));
sender.send("ping",getPingOMBlock("ping2"));
clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE, "true");
sender.send("ping",getPingOMBlock("ping3"));

There are only three difference here from your normal client code.

First you have to engage the sandesha module as given in the line 2.

Make sure you set the copy properties property of the options object to true as given in line 5.

Before the last message you must set the last message property, which is given in the line 9.

Simple RM enabled client code for a request reply service call.

First thing to remember is that you are not able to get synchronous (single channel) responses with Sandesha2. Because of this if you expect response message, you must have a return endpoint accessible from the server side. But making two channel blocking invocations is perfectly valid. But please make sure tht you have set a suitable time out interval within your call object.

Here is a code sample for this scenario.

Call call = new Call(AXIS2_CLIENT_REPO_PATH);
call.engageModule(new QName("Sandesha2-0.9"));
Options clientOptions = new Options ();
clientOptions.setProperty(Options.COPY_PROPERTIES,new Boolean (true));
call.setClientOptions(clientOptions);
//Make sure set the following two properties in the request-reply case.
clientOptions.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);
clientOptions.setUseSeparateListener(true);
clientOptions.setTo(ne EndpointReference(toEPR));
Callback callback1 = new TestCallback ("Callbck 1");
call.invokeNonBlocking("echoString", getEchoOMBlock("echo1"),callback1);
clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE, "true");
Callback callback3 = new TestCallback ("Callback 3");
call.invokeNonBlocking("echoString", getEchoOMBlock("echo3"),callback3);

Here also let me explaing the differences from a normal request-reply client code.

As in the request only case that was explained before, you have to engage the Sandesha2 module.

You have to tell axis enging to use a seperate channel for the responses as given in the line 8. Also make sure that you set the listner transport as given in line 7.

Also you have to set the last message property.

Advance scenarios

Getting acknowledgements and faults to a given endpoint.

In the dafault configuration response path for acknowledgements and faults related to a sequene is the anonymous endpoint. Because of this for example HTTP transport will send acknowledgements and faults in the HTTP response. If you want to avoid this and if you want to get acknowledgements and faults to a different endpoing add following part to the client code before doing any incovation.

sender.set(Sandesha2ClientAPI.AcksTo,<endpoint>); //example endpoint - http://tempuri.org/acks.

Managing sequences.

I the default behaviour Sandesha 2 assumes that messages going to the same endpoing should go in the same RM sequence. If you invoke two endpoints they will go in two sequences. If you want you can tell sandesha2 to start two sequences for the same endpoint as well. To do this you have to set a property called Sequence Key.

call.set(Sandesha2ClientAPI.SEQUENCE_KEY,<a string to identify the sequence>);

If the sequence key is different Sandesha2 will send messages in two sequences even if they are sent to the same endpoint.

Offering a sequence ID for the response sequence.

This is a concept of reliable messaging which may not be very useful to you as a user. Here what you do is offering a sequene ID for the sequence to be created in the response side withing the first Create Sequence Request message itself. with this you can avoid sending of a extra Create Sequence message from the server to the client. To do this add following to the client code.

call.set(Sandesha2ClientAPI.OFFERED_SEQUENCE_ID,<new uuid>);