You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fx-dev@ws.apache.org by ch...@apache.org on 2006/05/08 08:12:13 UTC
svn commit: r404941 [3/3] - /webservices/sandesha/site/sandesha2/
Modified: webservices/sandesha/site/sandesha2/userGuide.html
URL: http://svn.apache.org/viewcvs/webservices/sandesha/site/sandesha2/userGuide.html?rev=404941&r1=404940&r2=404941&view=diff
==============================================================================
--- webservices/sandesha/site/sandesha2/userGuide.html (original)
+++ webservices/sandesha/site/sandesha2/userGuide.html Sun May 7 23:12:10 2006
@@ -2,17 +2,17 @@
@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/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: 26 April 2006
- | Doc for SNAPSHOT</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="download.cgi">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="Apache_Sandesha2_User_s_Guide"></a><h2>Apache Sandesha2 User's Guide</h2><p>This document introduces you to Apache Sandesha2. This will first take you
-though a step by step guide of developing a Sample application using
-Sandesha2. In the later parts you will be introduced to some advance features
-making you more familier with the application.</p><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
+ Last published: 08 May 2006
+ | Doc for 1.0</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="download.cgi">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="Apache_Sandesha2_User_s_Guide"></a><h2>Apache Sandesha2 User's Guide</h2><p>This document introduces you to Apache Sandesha2. This will first take you
+through a step by step process of developing a sample application using
+Sandesha2. In the latter sections you will be introduced to some advance
+features making you more familiar with the application.</p><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#yfs">Your First Service with Sandesha2</a></li>
<li><a href="#wcfr">Writing Clients for Reliable Services</a>
<ul>
<li><a href="#oneway">Client Code for a One-Way RM Service Call</a></li>
- <li><a href="#reqres">Client code for a Request-Reply RM Service
+ <li><a href="#requestreply">Client code for a Request-Reply RM Service
Call</a></li>
</ul>
</li>
@@ -20,6 +20,7 @@
<ul>
<li><a href="#gaa">Getting Acknowledgements and Faults to a given
Endpoint</a></li>
+ <li><a href="#ms">Managing Sequences</a></li>
<li><a href="#oas">Offering a Sequence ID for the Response
Sequence</a></li>
<li><a href="#cras">Creating a Sequence Without Sending any
@@ -42,7 +43,7 @@
<li><a href="#toa">Timing Out a Sequence</a></li>
</ul>
</li>
- <li><a href="#wwsr">Working with Sandesha Reports</a>
+ <li><a href="#wws">Working with Sandesha Reports</a>
<ul>
<li><a href="#sandeshareport">SandeshaReport</a></li>
<li><a href="#sequencereport">SequenceReport</a></li>
@@ -68,17 +69,17 @@
<li><a href="#messagetypestodrop">MessageTypesToDrop</a></li>
</ul>
</li>
-</ul><p><a name="intro" href=""></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Sandesha2 is a Web Service-ReliableMessaging (WS-RM) implementation for
+</ul><p><a name="intro"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Sandesha2 is a Web Service-ReliableMessaging (WS-RM) implementation for
Apache Axis2. With Sandesha2 you can make your Web services reliable, or you
-can invoke already hosted reliable Web services.</p><p>If you want to learn more about Apache Axis2, refer to <a href="http://ws.apache.org/axis2/0_95/userguide.html" class="externalLink" title="External Link">Apache Axis2 User
-Guide</a> and <a href="http://ws.apache.org/axis2/0_95/Axis2ArchitectureGuide.html" class="externalLink" title="External Link">Apache
-Axis2 Architecture Guide</a>.</p><p>If you want to know about the design of Sandesha2 refer to <a href="architectureGuide.html">Sandesha2 Architecture Guide</a>.</p><p>Sandesha2 supports two reliable messaging specifications. It fully
+can invoke already hosted reliable Web services.</p><p>If you want to learn more about Apache Axis2, refer to <a href="http://ws.apache.org/axis2/0_95/userguide.html" class="newWindow" title="New Window" target="_blank">Apache Axis2 User
+Guide</a> and <a href="http://ws.apache.org/axis2/0_95/Axis2ArchitectureGuide.html" class="newWindow" title="New Window" target="_blank">Apache
+Axis2 Architecture Guide</a>.</p><p>If you want to know about the design of Sandesha2 refer to <a href="architectureGuide.html" class="newWindow" title="New Window" target="_blank">Sandesha2 Architecture Guide</a>.</p><p>Sandesha2 supports two reliable messaging specifications. It fully
supports WS-ReliableMessaging Feabruary 2005 specification which was created
in collaboration with Microsoft, IBM, BEA and TOBCO Software. Later this
specification was submitted to OASIS and is currently being standerdized
under the OASIS WS-RX technical committee. Sandesha2 currently support up to
the revision CD 3 of the specification being developed under this technical
-committee.</p><p><a name="yfs" href=""></a></p></div><div class="subsection"><a name="Your_First_Service_with_Sandesha2"></a><h3>Your First Service with Sandesha2</h3><p>This section will give you step by step guidelines on createting a Web
+committee.</p><p><a name="yfs"></a></p></div><div class="subsection"><a name="Your_First_Service_with_Sandesha2"></a><h3>Your First Service with Sandesha2</h3><p>This section will give you step by step guidelines on creating a Web
service with reliability and making it available within your Axis2 server.
This simple service will have a single one-way operation (ping) and a
request-response operation (echoString).</p><p>The steps are as follows:"</p><p>1. Download the Axis2 Webapp distribution (Axis2.war file) and deploy it
@@ -224,19 +225,18 @@
</pre></div>
<p>6. Deploy the service by dropping it to the webapp/axis2/WEB-INF/services
-directory.</p><p>Now your service is deployed with reliable messaging capability!</p><p><a name="wcfr" href=""></a></p></div><div class="subsection"><a name="Writing_Clients_for_Reliable_Services"></a><h3>Writing Clients for Reliable Services</h3><p>1. Create a repository folder in your file system (let's call it Client
-Repo).</p><p>2.Put the client_axis2.xml file that comes with the Sandesha2
-distributions to the Client Repo.</p><p>2. Create a sub folder named 'modules' in the Client Repo and add the
+directory.</p><p>Now your service is deployed with reliable messaging capability!</p><p><a name="wcfr"></a></p></div><div class="subsection"><a name="Writing_Clients_for_Reliable_Services"></a><h3>Writing Clients for Reliable Services</h3><p>1. Create a repository folder in your file system (let's call it Client_Repo).</p><p>2.Put the client_axis2.xml file that comes with the Sandesha2
+distributions to the Client_Repo.</p><p>3. Create a sub folder named 'modules' in the Client Repo and add the
sandesha and addressing module files to that. Your folder structure should
look like following now.</p>
- <div class="source"><pre>-- Client Repo
+ <div class="source"><pre>-- Client_Repo
------ client_axis2.xml
-------modules
-------------sandesha2.mar
-------------addressing.mar
</pre></div>
- <p>3. Write your client code as given in the following example scenarios. In
+ <p>4. Write your client code as given in the following example scenarios. In
these scenarios the variable CLIENT_REPO_PATH should be given the full path
to the Client Repo folder in a java compatible manner. To compile these you
will have to add all the library files that come with the Axis2 distribution
@@ -244,7 +244,7 @@
<div class="source"><pre>CLIENT_REPO_PATH = c:\\sandesha2\\repository
</pre></div>
- <p></p><p><a name="oneway" href=""></a></p><p><b>Client Code for a One-Way RM Service Call</b></p><p><em><strong>UserguidePingClient.java</strong></em></p>
+ <p><a name="oneway"></a></p><p><b>Client Code for a One-Way RM Service Call</b></p><p><em><strong>UserguidePingClient.java</strong></em></p>
<div class="source"><pre>package sandesha2.samples.userguide;
import java.io.File;
@@ -281,6 +281,9 @@
clientOptions.setAction("urn:wsrm:Ping");
serviceClient.setOptions(clientOptions);
+// serviceClient.engageModule(new QName ("sandesha2"));
+// serviceClient.engageModule(new QName ("addressing"));
+
serviceClient.fireAndForget(getPingOMBlock("ping1"));
serviceClient.fireAndForget(getPingOMBlock("ping2"));
@@ -304,14 +307,14 @@
}
</pre></div>
- <p><em>Lst's find out the differences between this code and a client code
+ <p><em>Let's find out the differences between this code and a client code
without RM:</em></p><p>You have to engage the sandesha and addressing modules. This has to be
done only if your axis2.xml file does not globally add these. For example, if
you are using the axis2_client.xml as in the previous file that comes with
-the Sandesha2 distribution, these two lines have to be omitted. Otherwise
-Axis2 will through the exception "org.apache.axis2.AxisFault: Trying to
-engage a module which is already engaged".</p><p><a name="lastmessage"></a></p><p>Before the last invocation you have to set the LAST_MESSAGE property.
-Otherwise the sequence will not terminate properly.</p><p><a name="reqres" href=""></a></p><p><b>Client Code for a Request-Reply RM Service Call</b></p><p><strong><em>UserguideEchoClient.java</em></strong></p>
+the Sandesha2 distribution, these two lines have to be omitted (as done in the previous
+code example). Otherwise Axis2 will throw the exception "org.apache.axis2.AxisFault:
+Trying to engage a module which is already engaged".</p><p><a name="lastmessage"></a></p><p>Before the last invocation you have to set the LAST_MESSAGE property.
+Otherwise the sequence will not terminate properly.</p><p><a name="requestreply"></a></p><p><b>Client Code for a Request-Reply RM Service Call</b></p><p><strong><em>UserguideEchoClient.java</em></strong></p>
<div class="source"><pre>package sandesha2.samples.userguide;
import java.io.File;
@@ -355,6 +358,9 @@
clientOptions.setUseSeparateListener(true);
serviceClient.setOptions(clientOptions);
+// serviceClient.engageModule(new QName ("sandesha2"));
+// serviceClient.engageModule(new QName ("addressing"));
+
Callback callback1 = new TestCallback ("Callback 1");
serviceClient.sendReceiveNonBlocking (getEchoOMBlock("echo1","sequence1"),callback1);
Callback callback2 = new TestCallback ("Callback 2");
@@ -421,7 +427,7 @@
responses with Sandesha2. Because of this if you expect a response message,
you must have a return endpoint accessible from the server side. But making
two channel blocking invocations is perfectly valid. But make sure that you
-have set a suitable timeout interval in your options object.</p><p></p><p><a name="acs" href=""></a></p></div><div class="subsection"><a name="Advance_Client_Scenarios"></a><h3>Advance Client Scenarios</h3><p>This section will introduce you to some Client API features which you may
+have set a suitable timeout interval in your options object.</p><p><a name="acs"></a></p></div><div class="subsection"><a name="Advance_Client_Scenarios"></a><h3>Advance Client Scenarios</h3><p>This section will introduce you to some Client API features which you may
not use for general cases. These features will be useful if you have some
knowledge in WSRM (Web service Reliable Messaging) and if you want to
customize the default behavior of Sandesha2 to make it work according to your
@@ -430,7 +436,7 @@
to add the sandesha2-client-<VERSION>.jar to your classpath. For
others, you have to use a special class called SandeshaClient, which is
available in the Sandesha-<VERSION>.jar file. Both these comes with
-Sandesha2 distributions.</p><p><a name="gaa" href=""></a></p></div><div class="subsection"><a name="Getting_Acknowledgements_and_Faults_to_a_Given_Endpoint"></a><h3>Getting Acknowledgements and Faults to a Given Endpoint</h3><p>In the default configuration, response path for acknowledgements and
+Sandesha2 distributions.</p><p><a name="gaa"></a></p></div><div class="subsection"><a name="Getting_Acknowledgements_and_Faults_to_a_Given_Endpoint"></a><h3>Getting Acknowledgements and Faults to a Given Endpoint</h3><p>In the default configuration, response path for acknowledgements and
faults related to a sequence is the anonymous endpoint. For example, HTTP
transport will send acknowledgements and faults in the HTTP response of
request messages. If you want to avoid this and if you want to get
@@ -439,9 +445,8 @@
the path of you application level faults. Only RM faults which occur within
the Sandesha2 will be sent to this endpoint.</p>
<div class="source"><pre>clientOptions.setProperty(SandeshaClientConstants.AcksTo,<endpoint>); //example endpoint - http://tempuri.org/acks.
-
</pre></div>
- <p><a name="ms" href=""></a></p></div><div class="subsection"><a name="Managing_Sequences"></a><h3>Managing Sequences</h3><p>In the default behaviour Sandesha2 assumes that messages going to the same
+ <p><a name="ms"></a></p></div><div class="subsection"><a name="Managing_Sequences"></a><h3>Managing Sequences</h3><p>In the default behaviour Sandesha2 assumes that messages going to the same
endpoint should go in the same RM sequence. Messages will be sent in
different RM sequences only if their WS-Addressing To address is different.
But if required you can instruct Sandesha2 to even send messages that have
@@ -451,7 +456,7 @@
</pre></div>
<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><a name="oas" href=""></a></p></div><div class="subsection"><a name="Offering_a_Sequence_ID_for_the_Response_Sequence"></a><h3>Offering a Sequence ID for the Response Sequence</h3><p>This is a concept of reliable messaging which may not be very useful to
+sequences even if they are sent to the same endpoint.</p><p><a name="oas"></a></p></div><div class="subsection"><a name="Offering_a_Sequence_ID_for_the_Response_Sequence"></a><h3>Offering a Sequence ID for the Response Sequence</h3><p>This is a concept of reliable messaging which may not be very useful to
you as a end user. Here what you do is offering a sequence ID for the
sequence to be created in the response side within the Create Sequence
Request message of the request path. If you provide this and if the Sandesha2
@@ -459,16 +464,14 @@
Sequence message exchange in the response path. To do this, add the following
to the client code.</p>
<div class="source"><pre>clientOptions.setProperty(SandeshaClientConstants.OFFERED_SEQUENCE_ID,<new uuid>);
-
</pre></div>
- <p><a name="cras" href=""></a></p></div><div class="subsection"><a name="Creating_a_Sequence_Without_Sending_any_Messages"></a><h3>Creating a Sequence Without Sending any Messages</h3><p>Sometimes you may need Sandesha2 client to start a sequence with a server
+ <p><a name="cras"></a></p></div><div class="subsection"><a name="Creating_a_Sequence_Without_Sending_any_Messages"></a><h3>Creating a Sequence Without Sending any Messages</h3><p>Sometimes you may need Sandesha2 client to start a sequence with a server
without sending any real application messages. When you ask for this,
Sandesha2 will do a Create Sequence message exchange and obtain a new
sequence ID from the server. Later you can send application messages with
this newly created sequence. A boolean parameter in this can also be used to
-tell whether to send an offer (Read the previous part on <a href="#oas">offering sequence IDs</a> to learn more about this) .
-The line you have to add to your client code for doing these is as
-follows.</p>
+tell whether to send an offer (Read the previous part on <a href="#oas">offering sequence IDs</a> to learn more about this) . The line
+you have to add to your client code for doing these is as follows.</p>
<div class="source"><pre>SandeshaClient.createSequence (ServiceClient serviceClient, booleanoffer);
</pre></div>
@@ -478,34 +481,32 @@
identified from different Sequence Keys.</p>
<div class="source"><pre>SandeshaClient.createSequnce (ServiceClient serviceClient, boolean offer,
String sequenceKey);
-
</pre></div>
- <p><a name="sar" href=""></a></p></div><div class="subsection"><a name="Sending_Acknowledgement_Requests_from_the_Client_Code"></a><h3>Sending Acknowledgement Requests from the Client Code</h3><p>You can ask the Sandesha2 to get an acknowledgement from a server with
+ <p><a name="sar"></a></p></div><div class="subsection"><a name="Sending_Acknowledgement_Requests_from_the_Client_Code"></a><h3>Sending Acknowledgement Requests from the Client Code</h3><p>You can ask the Sandesha2 to get an acknowledgement from a server with
which it is maintaining a sequence. This may be useful in a case where your
-<a href="#sequencereport">SequenceReports</a> indicate that some of the messages
-you sent have not been acknowledged and when you want to verify that. You can
-do this by adding one of the following line to the client code.</p>
+<a href="#sequencereport">SequenceReports</a> indicate that some of the
+messages you sent have not been acknowledged and when you want to verify
+that. You can do this by adding one of the following line to the client
+code.</p>
<div class="source"><pre>SandeshaClient.sendAckRequest (ServiceClient serviceClient);
</pre></div>
<p>You can use following method to send an acknowledgement request to a
specific sequence identified by the Sequence Key.</p>
<div class="source"><pre>SandeshaClient.sendAckRequest (ServiceClient serviceClient, String sequenceKey);
-
</pre></div>
- <p><a name="sts" href=""></a></p></div><div class="subsection"><a name="Selecting_the_Specification_Version_Which_you_Want_to_Work_in"></a><h3>Selecting the Specification Version Which you Want to Work in</h3><p>As I explained earlier Sandesha2 supports two WSRM specifications. The
+ <p><a name="sts"></a></p></div><div class="subsection"><a name="Selecting_the_Specification_Version_Which_you_Want_to_Work_in"></a><h3>Selecting the Specification Version Which you Want to Work in</h3><p>As it was explained earlier Sandesha2 supports two WSRM specifications. The
default is the submitted WSRM specification. But if you want to change this
and work in the new OASIS WSRM specification, set the following property in
the Options object.</p>
- <div class="source"><pre>clientOptions.setProperty(SandeshaClient.RM_SPEC_VERSION,Sandesha2Constants.SPEC_VERSIONS.WSRX);
+ <div class="source"><pre>clientOptions.setProperty(SandeshaClient.RM_SPEC_VERSION,Sandesha2Constants.SPEC_VERSIONS.v1_1);
</pre></div>
<p>To go back to the WSRM submitted specification set the property as
follows.</p>
- <div class="source"><pre>clientOptions.setProperty(SandeshaClient.RM_SPEC_VERSION,Sandesha2Constants.SPEC_VERSIONS.WSRM);
-
+ <div class="source"><pre>clientOptions.setProperty(SandeshaClient.RM_SPEC_VERSION,Sandesha2Constants.SPEC_VERSIONS.v1_0);
</pre></div>
- <p><a name="tas" href=""></a></p></div><div class="subsection"><a name="Terminating_a_Sequence_from_the_Client_Code"></a><h3>Terminating a Sequence from the Client Code</h3><p>You can terminate an on going sequence at any time by adding the line
+ <p><a name="tas"></a></p></div><div class="subsection"><a name="Terminating_a_Sequence_from_the_Client_Code"></a><h3>Terminating a Sequence from the Client Code</h3><p>You can terminate an on going sequence at any time by adding the line
given in this section to your client code. Remember that if you terminate a
sequence some of your messages may not get delivered to the service. This is
the recommended way for old WSRM submitted specification (the default). See
@@ -516,9 +517,8 @@
</pre></div>
<p>To terminate a specific sequence use following.</p>
<div class="source"><pre>SandeshaClient.terminateSequence (ServiceClient serviceClient, String sequenceKey);
-
</pre></div>
- <p><a name="clas" href=""></a></p></div><div class="subsection"><a name="Closing_a_Sequence_from_the_Client_Code"></a><h3>Closing a Sequence from the Client Code</h3><p>You can close an ongoing sequence at any time by adding the line given in
+ <p><a name="clas"></a></p></div><div class="subsection"><a name="Closing_a_Sequence_from_the_Client_Code"></a><h3>Closing a Sequence from the Client Code</h3><p>You can close an ongoing sequence at any time by adding the line given in
this section to your client code. Sequence close feature is only available
for new WSRM specification being developed under OASIS. Remember that if you
do not close elegantly, some of your messages may not get delivered to the
@@ -530,9 +530,8 @@
</pre></div>
<p>To close a specific sequence use following.</p>
<div class="source"><pre>SandeshaClient.closeSequence (ServiceClient serviceClient, String sequenceKey);
-
</pre></div>
- <p><a name="btc" href=""></a></p></div><div class="subsection"><a name="Blocking_the_Client_Code_until_a_Sequence_is_Complete"></a><h3>Blocking the Client Code until a Sequence is Complete</h3><p>After your client code delivered some messages to the RM layer, you may
+ <p><a name="btc"></a></p></div><div class="subsection"><a name="Blocking_the_Client_Code_until_a_Sequence_is_Complete"></a><h3>Blocking the Client Code until a Sequence is Complete</h3><p>After your client code delivered some messages to the RM layer, you may
have to wait for some time until the RM layer does its work. The time you
have to block depends on your system performance and network latencies. It
may be easier to ask the RM layer to block until its work is done by issuing
@@ -550,11 +549,10 @@
<div class="source"><pre>SandeshaClient.waitUntilSequenceCompleted (ServiceClient serviceClient, long maxWaitingTime);
SandeshaClient.waitUntilSequenceCompleted (ServiceClient serviceClient, long maxWaitingTime, String sequenceKey);
-
</pre></div>
- <p><a name="smo" href=""></a></p></div><div class="subsection"><a name="Sequence_Management_of_Sandesha2"></a><h3>Sequence Management of Sandesha2</h3><p>This section will explain you about the sequence managing method of
+ <p><a name="smo"></a></p></div><div class="subsection"><a name="Sequence_Management_of_Sandesha2"></a><h3>Sequence Management of Sandesha2</h3><p>This section will explain you about the sequence managing method of
Sandesha2. This is basically about four things, each explained in following
-sub topics.</p><p><a name="san" href=""></a></p></div><div class="subsection"><a name="Starting_a_New_Sequence"></a><h3>Starting a New Sequence</h3><p>Sandesha client gets two properties given by the client to decide the
+sub topics.</p><p><a name="san"></a></p></div><div class="subsection"><a name="Starting_a_New_Sequence"></a><h3>Starting a New Sequence</h3><p>Sandesha client gets two properties given by the client to decide the
sequence in which it should send a particular application messages. First one
is the address of the WS-Addressing To endpoint reference. The second is a
special constant given by the client called Sequence Key which is set as a
@@ -564,17 +562,17 @@
sequence, until that particular sequence is terminated.</p><p>Sequences that carry messages from the client to a server are called
request sequences and ones that carry messages from the server to the client
are called response sequences. Sandesha2 always keep a single response
-sequence corresponding to a particular request sequence.</p><p><a name="tas" href=""></a></p></div><div class="subsection"><a name="Terminating_a_Sequence"></a><h3>Terminating a Sequence</h3><p>There are currently two methods to terminate a particular sequence from
-the Client API. The first method is to set the Last
-Message propertyas it was explained <a href="#lastmessage">earlier</a>. After all the messages up
-to the last message get delivered reliably Sandesha2 will terminate that
+sequence corresponding to a particular request sequence.</p><p><a name="tas"></a></p></div><div class="subsection"><a name="Terminating_a_Sequence"></a><h3>Terminating a Sequence</h3><p>There are currently two methods to terminate a particular sequence from
+the Client API. The first method is to <a href="#lastmessage">set the Last Message property</a> as it was
+explained earlier. After all the messages up to
+the last message get delivered reliably Sandesha2 will terminate that
sequence. Remember that if you are working on the Submitted WSRM
specification (the default), this is the only method you can use.</p><p>If you are working on the new WSRM specification (see previous section on
-<a href="#sts">Selecting the Specification Version</a> if you want
-to know how to set this), these is a alternate method you can use to
-terminate a sequence. You can keep invoking the ServiceClient to send
-messages, without setting a Last Message property. After you finish your work
-call following function to terminate the sequence.</p>
+<a href="#sts">Selecting the Specification Version</a> if you want to know
+how to set this), these is a alternate method you can use to terminate a
+sequence. You can keep invoking the ServiceClient to send messages, without
+setting a Last Message property. After you finish your work call following
+function to terminate the sequence.</p>
<div class="source"><pre>SandeshaClient.terminateSequence (ServiceClient);
</pre></div>
@@ -585,7 +583,7 @@
</pre></div>
<p>When a request sequence is terminated, Sandesha2 will wait till all the
response messages are reliably delivered to the client and after which will
-terminate the response sequence as well.</p><p><a name="cas" href=""></a></p></div><div class="subsection"><a name="Closing_a_Sequence"></a><h3>Closing a Sequence</h3><p>New WSRM specification being developed under OASIS introduces a new
+terminate the response sequence as well.</p><p><a name="cas"></a></p></div><div class="subsection"><a name="Closing_a_Sequence"></a><h3>Closing a Sequence</h3><p>New WSRM specification being developed under OASIS introduces a new
feature called closing a sequence. When a sequence is closed the server will
not except new application messages, but will accept RM control messages like
acknowledgement requests. If you are writing your code for this specification
@@ -597,12 +595,13 @@
particular Sequence Key.</p>
<div class="source"><pre>SandeshaClient.terminateSequence (ServiceClient,, SequenceKey);
</pre></div>
- <p><a></a><a name="toa" href=""></a></p></div><div class="subsection"><a name="Timing_Out_a_Sequence"></a><h3>Timing Out a Sequence</h3><p>Depending on its policy configurations Sandesha2 may time out certain
+ <p><a name="toa"></a></p></div><div class="subsection"><a name="Timing_Out_a_Sequence"></a><h3>Timing Out a Sequence</h3><p>Depending on its policy configurations Sandesha2 may time out certain
sequences. When a sequence is timed out, it is considered finalized and
cannot be used any more. There are basically two ways a sequence can time
-out, and both can be configured using policies. See '<a href="#inactivitytimeout">InactivityTimeout</a>' and '<a href="#maximumretransmissioncount">MaximumRetransmissionCount</a>' parts of the '<a href="#cs">Configuring Sandesha2</a>' sub topic for more details.</p><p><a name="wwsr" href=""></a></p></div><div class="subsection"><a name="Working_with_Sandesha_Reports"></a><h3>Working with Sandesha Reports</h3><p>Sandesha introduces a feature called Sandesha Reports with which you can
+out, and both can be configured using policies. See '<a href="#inactivitytimeout">InactivityTimeout</a>' and '<a href="#maximumretransmissioncount">MaximumRetransmissionCount</a>' parts of
+the '<a href="#cs">Configuring Sandesha2</a>' sub topic for more details.</p><p><a name="wws"></a></p></div><div class="subsection"><a name="Working_with_Sandesha_Reports"></a><h3>Working with Sandesha Reports</h3><p>Sandesha introduces a feature called Sandesha Reports with which you can
get status information about the sequences managed by Sandesha2. There are
-basically two kinds of reports, each explained in following subtopics.</p><p><a></a><a name="sandeshareport" href=""></a></p></div><div class="subsection"><a name="SandeshaReport"></a><h3>SandeshaReport</h3><p>This gives information on all the incoming and outgoing sequences
+basically two kinds of reports, each explained in following subtopics.</p><p><a name="sandeshareport"></a></p></div><div class="subsection"><a name="SandeshaReport"></a><h3>SandeshaReport</h3><p>This gives information on all the incoming and outgoing sequences
Sandesha2 system is managing. When we consider a particular endpoint, an
incoming sequence is a sequence to which that endpoint is working as a
RM-Destination (RMD). An outgoing sequence is a sequence to which this
@@ -615,9 +614,8 @@
</ul><p>To get a SandeshaReport at any time, invoke following method from your
client code.</p>
<div class="source"><pre>SandeshaClient.getSandeshaReport (ConfigurationContext c);
-
</pre></div>
- <p><a name="sequencereport" href=""></a></p></div><div class="subsection"><a name="SequenceReport"></a><h3>SequenceReport</h3><p>A SequnceReport gives information on a specific sequences that a Sandesha
+ <p><a name="sequencereport"></a></p></div><div class="subsection"><a name="SequenceReport"></a><h3>SequenceReport</h3><p>A SequnceReport gives information on a specific sequences that a Sandesha
system is working on. This can be an incoming sequence or a outgoing
sequence.</p><p><em><strong>A SequenceReport will give following
information:</strong></em></p><ol>
@@ -651,9 +649,8 @@
<div class="source"><pre>SandeshaClient.getOutgoingSequenceReport (ServiceClient serviceClient);
SandeshaClient.getOutgoingSequenceReport (String to,String sequenceKey,ConfigurationContext configurationContext);
SandeshaClient.getOutgoingSequenceReport (String internalSequenceID,ConfigurationContext configurationContext);
-
</pre></div>
- <p><a name="slf" href=""></a></p></div><div class="subsection"><a name="Sandesha_Listener_Feature"></a><h3>Sandesha Listener Feature</h3><p>You can use this new feature to register a listener class in Sandesha2 and
+ <p><a name="slf"></a></p></div><div class="subsection"><a name="Sandesha_Listener_Feature"></a><h3>Sandesha Listener Feature</h3><p>You can use this new feature to register a listener class in Sandesha2 and
get notified when specific event happens in the system. The basic interface
is given below.</p>
<div class="source"><pre>public interface SandeshaListener {
@@ -668,16 +665,16 @@
</pre></div>
<p>Currently SandeshaListener defines the following two methods- onError
-& onTimedOut.</p><p><a name="onerror" href=""></a></p></div><div class="subsection"><a name="onError"></a><h3>onError</h3><p>This will be invoked if Sandesha2 receives a fault SOAP message for one of
+& onTimedOut.</p><p><a name="onerror"></a></p></div><div class="subsection"><a name="onError"></a><h3>onError</h3><p>This will be invoked if Sandesha2 receives a fault SOAP message for one of
the protocol messages it sent. The parameter will be an AxisFault
representing that fault message. Remember that this will not be invoked for
faults that occur due to application messages or any other messages that do
not get originated from Sandesha2. They will not be considered by the
-Sandesha2 system as valid application messages.</p><p><a name="ontimeout" href=""></a></p></div><div class="subsection"><a name="onTimeOut"></a><h3>onTimeOut</h3><p>As mentioned in the earlier section <a href="#smo">Sequence Management of
+Sandesha2 system as valid application messages.</p><p><a name="ontimeout"></a></p></div><div class="subsection"><a name="onTimeOut"></a><h3>onTimeOut</h3><p>As mentioned in the earlier section <a href="#smo">Sequence Management of
Sanesha2</a>, there is a possibility of an inactive sequence timing out. When
a specific sequence times out, this method of the SandeshaListener will be
-invoked giving a report of that sequence as a parameter.</p><p><a name="dao" href=""></a></p></div><div class="subsection"><a name="Delivery_Assurances_of_Sandesha2"></a><h3>Delivery Assurances of Sandesha2</h3><p>As it was mentioned in the <a href="architectureGuide.html">Architecture Guide</a>, Sandesha2
-provide an in-order exactly-once delivery assurance.
+invoked giving a report of that sequence as a parameter.</p><p><a name="dao"></a></p></div><div class="subsection"><a name="Delivery_Assurances_of_Sandesha2"></a><h3>Delivery Assurances of Sandesha2</h3><p>As it was mentioned in the <a href="architectureGuide.html" class="newWindow" title="New Window" target="_blank">Architecture
+Guide</a>, Sandesha2 provide an in-order exactly-once delivery assurance.
<strong>In-order</strong> means that Sandesha2 will guarantee delivering of
the messages to the Web service in the order of their message numbers. If you
use a Sandesha2 client this will be the order you called the invocation
@@ -688,7 +685,7 @@
assurance you can be sure that your service gets invoked only once.</p><p>If you require the performance to be maximized and if you do not want
ordering, you can configure Sandesha2 to invoke messages in the order they
arrive. Read 'Configuring Sandesha2' section below to learn how to do
-this.</p><p><a name="cs" href=""></a></p></div><div class="subsection"><a name="Configuring_Sandesha2"></a><h3>Configuring Sandesha2</h3><p>Sandesha2 provides a set of configurations which you can use to customize
+this.</p><p><a name="cs"></a></p></div><div class="subsection"><a name="Configuring_Sandesha2"></a><h3>Configuring Sandesha2</h3><p>Sandesha2 provides a set of configurations which you can use to customize
its execution behavior. All these configurations are available in a WS-Policy
format. These policies can be in the module.xml file of the Sandesha module
or in the services.xml file of a service on which Sandesha2 module has been
@@ -699,7 +696,7 @@
incompatible types or values may cause Sandesha system to malfunction.
Normally if Sandesha2 can detect that the value you have set is incompatible,
it will set a default value which is mentioned in the SandeshaConstants
-class.</p><p><a name="acknowledgementinterval" href=""></a></p></div><div class="subsection"><a name="AcknowledgementInterval"></a><h3>AcknowledgementInterval</h3><p>When a RMD receives an application message and when it has to send
+class.</p><p><a name="acknowledgementinterval"></a></p></div><div class="subsection"><a name="AcknowledgementInterval"></a><h3>AcknowledgementInterval</h3><p>When a RMD receives an application message and when it has to send
acknowledgements to an endpoint (other than the anonymous URL), it will not
send this message immediately but will wait for some time to see whether
there are any other messages (for example application response messages)
@@ -709,14 +706,14 @@
the destination of the acknowledgement within a specific time interval, the
acknowledgement is sent as a stand alone message. This time interval is
called the <strong>acknowledgement interval</strong> and can be configured in
-Sandesha2 policies. The measurement unit is in milliseconds.</p><p><a name="retransmissioninterval" href=""></a></p></div><div class="subsection"><a name="RetransmissionInterval"></a><h3>RetransmissionInterval</h3><p>As it was mentioned earlier some messages in RM should be retransmitted
+Sandesha2 policies. The measurement unit is in milliseconds.</p><p><a name="retransmissioninterval"></a></p></div><div class="subsection"><a name="RetransmissionInterval"></a><h3>RetransmissionInterval</h3><p>As it was mentioned earlier some messages in RM should be retransmitted
until a proper response or acknowledgement is returned. After sending a
message once, the RMS will wait for some time before sending it for the
second time. This waiting time between the first and second retransmission
attempts is given by this policy. If the policy given later called the
ExponentialBackoff is set to false the time gap between all the
retransmissions attempts will have the same value, which is the
-RetransmissionInterval. Measurement unit is in milliseconds.</p><p><a name="exponentialbackoff" href=""></a></p></div><div class="subsection"><a name="ExponentialBackoff"></a><h3>ExponentialBackoff</h3><p>Value of this can either be 'true' or 'false'. This measure is used to
+RetransmissionInterval. Measurement unit is in milliseconds.</p><p><a name="exponentialbackoff"></a></p></div><div class="subsection"><a name="ExponentialBackoff"></a><h3>ExponentialBackoff</h3><p>Value of this can either be 'true' or 'false'. This measure is used to
adjust the retransmission attempts so that an RMD does not get flooded with a
large number of retransmitted messages. If this is 'true', a time gap between
two retransmissions will be twice as the time gap between previous two
@@ -724,32 +721,32 @@
retransmission attempts is twenty seconds the time gap between the fifth and
sixth attempts will be forty seconds. If this property is set to 'false', all
retransmissions will have the same value, which is given by the
-'RetransmissionInterval' property.</p><p><a name="maximumretransmissioncount" href=""></a></p></div><div class="subsection"><a name="MaximumRetransmissionCount"></a><h3>MaximumRetransmissionCount</h3><p>This gives the maximum number of times a message has to be retransmitted.
+'RetransmissionInterval' property.</p><p><a name="maximumretransmissioncount"></a></p></div><div class="subsection"><a name="MaximumRetransmissionCount"></a><h3>MaximumRetransmissionCount</h3><p>This gives the maximum number of times a message has to be retransmitted.
When a specific message gets retransmitted a maximum number of times, and is
still not sent correctly to the RMD, it will not be sent again and the
request will be marked as Timed Out. When a sequence is timed out, it cannot
be used any more. If the value of this property is '-1' there is no limit in
-the number of retransmission attempts.</p><p><a name="inactivitytimeout" href=""></a></p></div><div class="subsection"><a name="InactivityTimeout"></a><h3>InactivityTimeout</h3><p>A Sandesha2 RMS always keeps track of the last time a particular RMD
+the number of retransmission attempts.</p><p><a name="inactivitytimeout"></a></p></div><div class="subsection"><a name="InactivityTimeout"></a><h3>InactivityTimeout</h3><p>A Sandesha2 RMS always keeps track of the last time a particular RMD
responded to a request by it. If the RMD does not response within the time
limit given by the time interval given by this measure, the RMS will give up
attempting and will mark the sequence as Timed Out. After timing out the
particular sequence, it cannot be used any more. If the value of this is -1,
there is not inactivity timeout limit The measure of this is given by the
-property 'InactivityTimeoutMeasure'.</p><p><a name="inactivitytimeoutmeasure" href=""></a></p></div><div class="subsection"><a name="InactivityTimeoutMeasure"></a><h3>InactivityTimeoutMeasure</h3><p>This gives the measure of the property 'InactivityTimeout'. The value of
+property 'InactivityTimeoutMeasure'.</p><p><a name="inactivitytimeoutmeasure"></a></p></div><div class="subsection"><a name="InactivityTimeoutMeasure"></a><h3>InactivityTimeoutMeasure</h3><p>This gives the measure of the property 'InactivityTimeout'. The value of
this can be seconds, minutes, hours or days. If you give a value that cannot
-be interpreted the default will be used.</p><p><a name="invokeinorder" href=""></a></p></div><div class="subsection"><a name="InvokeInOrder"></a><h3>InvokeInOrder</h3><p>As it was mentioned earlier, Sandesha2 implement the in-order invoking
+be interpreted the default will be used.</p><p><a name="invokeinorder"></a></p></div><div class="subsection"><a name="InvokeInOrder"></a><h3>InvokeInOrder</h3><p>As it was mentioned earlier, Sandesha2 implement the in-order invoking
delivery assurance. This property can be used to turn this on or off. The
value of this has to be 'true' if in-order invoking has to be enabled. It has
to be false if in-order invoking has to be disabled. Please remember that
this is a non-overridable property. I.e. value you set in the module.xml is
the one that is used for all the services and will not be overridden for a
-perticular service by setting a different value there.</p><p><a name="storagemanager" href=""></a></p></div><div class="subsection"><a name="StorageManager"></a><h3>StorageManager</h3><p>This gives the storage manager implementation class used by Sandesha2. You
+perticular service by setting a different value there.</p><p><a name="storagemanager"></a></p></div><div class="subsection"><a name="StorageManager"></a><h3>StorageManager</h3><p>This gives the storage manager implementation class used by Sandesha2. You
have to mention the full qualified class name here. Please read the Sandesha2
<a href="architectureGuide.html">Architecture Guide</a> for more details on
creating your own storage manager. This is also a property that cannot be
overridden, i.e., value you set in the module.xml is the one that is used for
all the services and will not be overridden for a particular service by
-setting a different value there.</p><p><a name="messagetypestodrop" href=""></a></p></div><div class="subsection"><a name="MessageTypesToDrop"></a><h3>MessageTypesToDrop</h3><p>This is a property that may not be very useful to an end user, but may be
+setting a different value there.</p><p><a name="messagetypestodrop"></a></p></div><div class="subsection"><a name="MessageTypesToDrop"></a><h3>MessageTypesToDrop</h3><p>This is a property that may not be very useful to an end user, but may be
useful for some debug purposes. As it was mentioned earlier Sandesha2 gives a
Message Type to each message it sends. For example, Create Sequence messages
will have the type 1 and Acknowledgement messages will have the type 4. You
---------------------------------------------------------------------
To unsubscribe, e-mail: sandesha-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: sandesha-dev-help@ws.apache.org