xdocs/userGuide.html - sandesha - Git at Google

 <?xml version="1.0" encoding="iso-8859-1"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
   <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
   <title>Sandesha2 User Guide</title>
   <meta name="generator" content="amaya 9.2.2, see http://www.w3.org/Amaya/"
   />
 </head>

 <body>
 <h1>Sandesha2 User Guide</h1>

 <p>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.</p>

 <p></p>

 <h2>Using Sandesha2 in the server side</h2>

 <p>First lets look at how to use Sandesha2 in the server side.</p>

 <p>You can set up Sandesha2 for the server side with following steps.</p>
 <ol>
   <li>Download and deploy axis2(please see Axis2 user guide for more
   details).</li>
   <li>Add a user phase called RMPhase to all four flows of axis2.xml.</li>
   <li>Download latest Sandesha2 distribution and add Sandesha2 mar file to
     &lt;AXIS2_WEBAPP&gt;\WEB_INF\modules directory.</li>
   <li>Add sandesha2.properties file to the
     &lt;AXIS2_WEBAPP&gt;\WEB_INF\classes directory.</li>
 </ol>

 <p>Now your Sandesha2 module is setup and deployed.</p>

 <p></p>

 <p>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).</p>

 <p>Add a module reference for Sandesha2 to the services.xml (within the aar
 file) as given below.</p>
 <pre>&lt;service name="TestService"&gt;
 &lt;module ref="Sandesha2-0.9"/&gt;
 .......................
 &lt;!-- Your operation definitions and other stuff
 ........................
 &lt;/service&gt;</pre>

 <p>Create the service archieve file.</p>

 <p>Deploy it by dropping it to &lt;AXIS2_WEBAPP&gt;/WEB-INF/services
 directory.</p>

 <p>Now your service is deployed with reliable messaging support.</p>

 <p></p>

 <h2>Using Sandesha2 in the client side</h2>

 <p>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.</p>

 <p></p>

 <h3>Basic scenarios</h3>
 <source>
 <p><b>Sample RM enabled client code for a one way service call.</b></p>
 <pre>MessageSender sender = new MessageSender (AXIS2_CLIENT_REPO_PATH);
 <span style="background-color: #CCCCCC">sender.engageModule(new QName ("Sandesha2-0.9"));</span>
 Options clientOptions = new Options ();
 sender.setClientOptions(clientOptions);
 <span style="background-color: #CCCCCC">clientOptions.setProperty(Options.COPY_PROPERTIES,new Boolean (true));</span>
 clientOptions.setTo(new EndpointReference(toEPR));
 sender.send("ping",getPingOMBlock("ping1"));
 sender.send("ping",getPingOMBlock("ping2"));
 <span style="background-color: #CCCCCC">clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE, "true");</span>
 sender.send("ping",getPingOMBlock("ping3"));</pre>
 </source>
 <p>There are only three difference here from your normal client code.</p>

 <p>First you have to engage the sandesha module as given in the line 2.</p>

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

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

 <p></p>

 <p><b>Simple RM enabled client code for a request reply service call.</b></p>

 <p>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.</p>

 <p></p>

 <p>Here is a code sample for this scenario.</p>
 <source><pre>Call call = new Call(AXIS2_CLIENT_REPO_PATH);
 <span style="background-color: #CCCCCC">call.engageModule(new QName("Sandesha2-0.9"));</span>
 Options clientOptions = new Options ();
 <span style="background-color: #CCCCCC">clientOptions.setProperty(Options.COPY_PROPERTIES,new Boolean (true));</span>
 call.setClientOptions(clientOptions);
 //Make sure set the following two properties in the request-reply case.
 <span style="background-color: #CCCCCC">clientOptions.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);</span>
 <span style="background-color: #CCCCCC">clientOptions.setUseSeparateListener(true);</span>
 clientOptions.setTo(ne EndpointReference(toEPR));
 Callback callback1 = new TestCallback ("Callbck 1");
 call.invokeNonBlocking("echoString", getEchoOMBlock("echo1"),callback1);
 <span style="background-color: #CCCCCC">clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE, "true");</span>
 Callback callback3 = new TestCallback ("Callback 3");
 call.invokeNonBlocking("echoString", getEchoOMBlock("echo3"),callback3);</pre>
 </source>
 <p></p>

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

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

 <p>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.</p>

 <p>Also you have to set the last message property.</p>

 <p></p>

 <h3>Advance scenarios</h3>

 <p><b>Getting acknowledgements and faults to a given endpoint.</b></p>

 <p>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.</p>
 <pre>sender.set(Sandesha2ClientAPI.AcksTo,&lt;endpoint&gt;); //example endpoint - http://tempuri.org/acks.</pre>

 <p></p>

 <p><b>Managing sequences.</b></p>

 <p>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.</p>
 <pre>call.set(Sandesha2ClientAPI.SEQUENCE_KEY,&lt;a string to identify the sequence&gt;);</pre>

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

 <p></p>

 <p><b>Offering a sequence ID for the response sequence.</b></p>

 <p>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.</p>
 <pre>call.set(Sandesha2ClientAPI.OFFERED_SEQUENCE_ID,&lt;new uuid&gt;);</pre>

 <p></p>

 <p></p>
 </body>
 </html>
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
	<title>Sandesha2 User Guide</title>
	<meta name="generator" content="amaya 9.2.2, see http://www.w3.org/Amaya/"
	/>
	</head>

	<body>
	<h1>Sandesha2 User Guide</h1>

	<p>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.</p>

	<p></p>

	<h2>Using Sandesha2 in the server side</h2>

	<p>First lets look at how to use Sandesha2 in the server side.</p>

	<p>You can set up Sandesha2 for the server side with following steps.</p>
	<ol>
	<li>Download and deploy axis2(please see Axis2 user guide for more
	details).</li>
	<li>Add a user phase called RMPhase to all four flows of axis2.xml.</li>
	<li>Download latest Sandesha2 distribution and add Sandesha2 mar file to
	<AXIS2_WEBAPP>\WEB_INF\modules directory.</li>
	<li>Add sandesha2.properties file to the
	<AXIS2_WEBAPP>\WEB_INF\classes directory.</li>
	</ol>

	<p>Now your Sandesha2 module is setup and deployed.</p>

	<p></p>

	<p>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).</p>

	<p>Add a module reference for Sandesha2 to the services.xml (within the aar
	file) as given below.</p>
	<pre><service name="TestService">
	<module ref="Sandesha2-0.9"/>
	.......................
	<!-- Your operation definitions and other stuff
	........................
	</service></pre>

	<p>Create the service archieve file.</p>

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

	<p>Now your service is deployed with reliable messaging support.</p>

	<p></p>

	<h2>Using Sandesha2 in the client side</h2>

	<p>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.</p>

	<p></p>

	<h3>Basic scenarios</h3>
	<source>
	<p><b>Sample RM enabled client code for a one way service call.</b></p>
	<pre>MessageSender sender = new MessageSender (AXIS2_CLIENT_REPO_PATH);
	<span style="background-color: #CCCCCC">sender.engageModule(new QName ("Sandesha2-0.9"));</span>
	Options clientOptions = new Options ();
	sender.setClientOptions(clientOptions);
	<span style="background-color: #CCCCCC">clientOptions.setProperty(Options.COPY_PROPERTIES,new Boolean (true));</span>
	clientOptions.setTo(new EndpointReference(toEPR));
	sender.send("ping",getPingOMBlock("ping1"));
	sender.send("ping",getPingOMBlock("ping2"));
	<span style="background-color: #CCCCCC">clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE, "true");</span>
	sender.send("ping",getPingOMBlock("ping3"));</pre>
	</source>
	<p>There are only three difference here from your normal client code.</p>

	<p>First you have to engage the sandesha module as given in the line 2.</p>

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

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

	<p></p>

	<p><b>Simple RM enabled client code for a request reply service call.</b></p>

	<p>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.</p>

	<p></p>

	<p>Here is a code sample for this scenario.</p>
	<source><pre>Call call = new Call(AXIS2_CLIENT_REPO_PATH);
	<span style="background-color: #CCCCCC">call.engageModule(new QName("Sandesha2-0.9"));</span>
	Options clientOptions = new Options ();
	<span style="background-color: #CCCCCC">clientOptions.setProperty(Options.COPY_PROPERTIES,new Boolean (true));</span>
	call.setClientOptions(clientOptions);
	//Make sure set the following two properties in the request-reply case.
	<span style="background-color: #CCCCCC">clientOptions.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);</span>
	<span style="background-color: #CCCCCC">clientOptions.setUseSeparateListener(true);</span>
	clientOptions.setTo(ne EndpointReference(toEPR));
	Callback callback1 = new TestCallback ("Callbck 1");
	call.invokeNonBlocking("echoString", getEchoOMBlock("echo1"),callback1);
	<span style="background-color: #CCCCCC">clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE, "true");</span>
	Callback callback3 = new TestCallback ("Callback 3");
	call.invokeNonBlocking("echoString", getEchoOMBlock("echo3"),callback3);</pre>
	</source>
	<p></p>

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

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

	<p>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.</p>

	<p>Also you have to set the last message property.</p>

	<p></p>

	<h3>Advance scenarios</h3>

	<p><b>Getting acknowledgements and faults to a given endpoint.</b></p>

	<p>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.</p>
	<pre>sender.set(Sandesha2ClientAPI.AcksTo,<endpoint>); //example endpoint - http://tempuri.org/acks.</pre>

	<p></p>

	<p><b>Managing sequences.</b></p>

	<p>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.</p>
	<pre>call.set(Sandesha2ClientAPI.SEQUENCE_KEY,<a string to identify the sequence>);</pre>

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

	<p></p>

	<p><b>Offering a sequence ID for the response sequence.</b></p>

	<p>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.</p>
	<pre>call.set(Sandesha2ClientAPI.OFFERED_SEQUENCE_ID,<new uuid>);</pre>

	<p></p>

	<p></p>
	</body>
	</html>