Author: chamikara
Date: Sun Dec 4 11:32:46 2005
New Revision: 353898
URL: http://svn.apache.org/viewcvs?rev=353898&view=rev
Log:
Updated the userGuide
Modified:
webservices/site/trunk/targets/sandesha/sandesha2/userGuide.html
Modified: webservices/site/trunk/targets/sandesha/sandesha2/userGuide.html
URL:
http://svn.apache.org/viewcvs/webservices/site/trunk/targets/sandesha/sandesha2/userGuide.html?rev=353898&r1=353897&r2=353898&view=diff
==============================================================================
--- webservices/site/trunk/targets/sandesha/sandesha2/userGuide.html (original)
+++ webservices/site/trunk/targets/sandesha/sandesha2/userGuide.html Sun Dec 4
11:32:46 2005
@@ -1,12 +1,12 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html><head><title>Sandesha2
- Sandesha2 User Guide</title><style type="text/css" media="all">
@import url("./style/maven-base.css");
- @import
url("./style/maven-theme.css");</style><link rel="stylesheet"
href="./style/print.css" type="text/css" media="print"></link><meta
http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a
href="http://ws.apache.org/"; id="organizationLogo"><img alt="Apache Web
Services" src="http://www.apache.org/images/asf-logo.gif";></img></a><a
href="http://ws.apache.org/ws-fx/sandesha/"; id="projectLogo"><img alt="Apache
Sandesha2"
src="http://ws.apache.org/ws-fx/sandesha/images/Sandesha.jpg";></img></a><div
class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 30 November 2005
+ @import
url("./style/maven-theme.css");</style><link rel="stylesheet"
href="./style/print.css" type="text/css" media="print"></link><meta
http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a
href="http://ws.apache.org/"; id="organizationLogo"><img alt="Apache Web
Services" src="http://www.apache.org/images/asf-logo.gif";></img></a><a
href="http://ws.apache.org/ws-fx/sandesha/sandesha2"; id="projectLogo"><img
alt="Apache Sandesha2"
src="http://ws.apache.org/ws-fx/sandesha/images/Sandesha.jpg";></img></a><div
class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 05 December 2005
| Doc for 0.9</div><div class="xright"></div><div
class="clear"><hr></hr></div></div><div id="leftColumn"><div
id="navcolumn"><div id="menuApache_Sandesha2"><h5>Apache Sandesha2</h5><ul><li
class="none"><a href="index.html">Home</a></li><li class="expanded"><a
href="">Downloads</a><ul><li class="none"><a
href="releases.html">Releases</a></li><li class="none"><a
href="http://svn.apache.org/repos/asf/webservices/sandesha/trunk";
class="externalLink" title="External Link">Source Code</a></li></ul></li><li
class="expanded"><a href="">Documentation</a><ul><li class="none"><a
href="userGuide.html">User Guide</a></li><li class="none"><a
href="architectureGuide.html">Architecture Guide</a></li><li class="none"><a
href="apidocs/index.html">Java Docs</a></li></ul></li><li class="expanded"><a
href="">Project Information</a><ul><li class="none"><a
href="mail-lists.html">Mailing Lists</a></li><li class="none"><a
href="team-list.html">Project Team</a></li></ul></li></ul><
/div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li
class="none"><a href="index.html">About Apache Sandesha2</a></li><li
class="collapsed"><a href="project-info.html">Project Info</a></li><li
class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li
class="none"><a href="http://maven.apache.org/development-process.html";
class="externalLink" title="External Link">Development
Process</a></li></ul></div><a href="http://maven.apache.org/"; title="Built by
Maven" id="poweredBy"><img alt="Built by Maven"
src="./images/logos/maven-button-1.png"></img></a></div></div><div
id="bodyColumn"><div class="contentBox"><div class="section"><a
name="Sandesha2_User_Guide"></a><h2>Sandesha2 User Guide</h2><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></div><div class="section"><a
name="Using_Sandesha2_in_the_server_side"></a><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 in three steps.</p><ol>
+others.</p><p></p><div class="subsection"><a
name="Using_Sandesha2_in_the_server_side"></a><h3>Using Sandesha2 in the server
side</h3><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>
@@ -18,8 +18,8 @@
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>
- <div class="source"><pre><service name="OneWayService">
-<module ref="<Sandesha2 module name>"/>
+ <div class="source"><pre><service name="TestService">
+<module ref="Sandesha2-0.9"/>
.......................
<!-- Your operation definitions and other stuff
........................
@@ -27,51 +27,64 @@
</pre></div>
<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></div><div class="section"><a
name="Using_Sandesha2_in_the_client_side"></a><h2>Using Sandesha2 in the client
side</h2><p>Add Sandesha2 module in the way you normally add a module to the
Axis2
+directory.</p><p>Now your service is deployed with reliable messaging
support.</p><p></p></div><div class="subsection"><a
name="Using_Sandesha2_in_the_client_side"></a><h3>Using Sandesha2 in the client
side</h3><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><div class="subsection"><a
name="Basic_scenarios"></a><h3>Basic scenarios</h3><p><b>Sample RM enabled
client code for a one way service call.</b></p>
- <div class="source"><pre><pre>MessageSender sender = new MessageSender
(AXIS2_CLIENT_PATH);
-<span style="background-color: #CCCCCC">sender.engageModule(new QName
("<Sandesha2 module name>"));</span>
-sender.setTo(new EndpointReference(toEPR));
-sender.set(MessageContextConstants.TRANSPORT_URL,toEPR);
+explain you how to write the client code.</p><p></p></div><div
class="subsection"><a name="Basic_scenarios"></a><h3>Basic scenarios</h3>
+ <div class="source"><pre>
+<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">sender.set(org.apache.sandesha2.Constants.LAST_MESSAGE, "true");</span>
-sender.send("ping",getPingOMBlock("ping3"));</pre></pre></div>
- <p></p><p>There are only two 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>Before the last message you must set the last message property, which
is
-given in the line 7.</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
+<span style="background-color:
#CCCCCC">clientOptions.setProperty(Sandesha2ClientAPI.LAST_MESSAGE,
"true");</span>
+sender.send("ping",getPingOMBlock("ping3"));</pre>
+</pre></div>
+ <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>
- <div class="source"><pre><pre>Call call = new Call(AXIS2_CLIENT_PATH);
-<span style="background-color: #CCCCCC">call.engageModule(new
QName("<Sandesha2 module name>"));</span>
-call.setTo(new EndpointReference(toEPR));
-call.setTransportInfo(org.apache.axis2.Constants.TRANSPORT_HTTP,org.apache.axis2.Constants.TRANSPORT_HTTP,true);
-Callback callback1 = new TestCallback ("Callback 1");
-call.invokeNonBlocking("echoString",getEchoOMBlock("echo1"),callback1);
-Callback callback2 = new TestCallback ("Callback 2");
-call.invokeNonBlocking("echoString",getEchoOMBlock("echo2"),callback2);
-<span style="background-color: #CCCCCC">call.set(Constants.LAST_MESSAGE,
"true");</span>
+ <div class="source"><pre><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></pre></div>
- <p></p><p>Here also the only difference from a normal client code is
addition of the
-Sandesha2 module reference and setting the last message
property.</p><p></p></div><div class="subsection"><a
name="Advance_scenarios"></a><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
+call.invokeNonBlocking("echoString", getEchoOMBlock("echo3"),callback3);</pre>
+</pre></div>
+ <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></div><div class="subsection"><a
name="Advance_scenarios"></a><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 avaoid this and if you want to get acknowledgements and faults to
+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>
- <div class="source"><pre>sender.set(Constants.AcksTo,<endpoint>);
//example endpoint - http://tempuri.org/acks.
+ <div
class="source"><pre>sender.set(Sandesha2ClientAPI.AcksTo,<endpoint>);
//example endpoint - http://tempuri.org/acks.
</pre></div>
- <p></p><p><b>Managing sequences.</b></p><p>I the default behavious Sandesha
2 assumes that messages going to the same
+ <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>
- <div class="source"><pre>call.set(Constants.SEQUENCE_KEY,<a string to
identify the sequence>);
+ <div class="source"><pre>call.set(Sandesha2ClientAPI.SEQUENCE_KEY,<a
string to identify the sequence>);
</pre></div>
<p>If the sequence key is different Sandesha2 will send messages in two
@@ -81,7 +94,7 @@
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>
- <div class="source"><pre>call.set(Constants.OFFERED_SEQUENCE_ID,<new
uuid>);
+ <div
class="source"><pre>call.set(Sandesha2ClientAPI.OFFERED_SEQUENCE_ID,<new
uuid>);
</pre></div>
<p></p><p></p></div></div></div></div><div class="clear"><hr></hr></div><div
id="footer"><div class="xright">© 2005, Apache Web Services</div><div
class="clear"><hr></hr></div></div></body></html>
![http://www.apache.org/images/asf-logo.gif"](http://www.apache.org/images/asf-logo.gif"){kind=link}
![http://ws.apache.org/ws-fx/sandesha/images/Sandesha.jpg"](http://ws.apache.org/ws-fx/sandesha/images/Sandesha.jpg"){kind=link}