| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia Site Renderer 1.3 at May 4, 2013 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Sandesha2 - |
| |
| Sandesha2 User Guide</title> |
| <style type="text/css" media="all"> |
| @import url("./css/maven-base.css"); |
| @import url("./css/maven-theme.css"); |
| @import url("./css/site.css"); |
| </style> |
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> |
| <meta name="Date-Revision-yyyymmdd" content="20130504" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /><meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="http://www.apache.org/" id="bannerLeft"> |
| <img src="http://www.apache.org/images/asf-logo.gif" alt="Apache Software Foundation" /> |
| </a> |
| <a href="index.html" id="bannerRight"> |
| <img src="images/Sandesha.jpg" alt="Sandesha" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| <div class="xleft"> |
| <span id="publishDate">Last Published: 2013-05-04</span> |
| | <span id="projectVersion">Version: 1.6.3-SNAPSHOT</span> |
| </div> |
| <div class="xright"> <a href="../core/" title="Axis2">Axis2</a> |
| | |
| <a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a> |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| <h5>Apache Sandesha2</h5> |
| <ul> |
| <li class="none"> |
| <a href="index.html" title="Home">Home</a> |
| </li> |
| <li class="expanded"> |
| <a href="javascript:void(0)" title="Downloads">Downloads</a> |
| <ul> |
| <li class="none"> |
| <a href="download.cgi" title="Releases">Releases</a> |
| </li> |
| <li class="none"> |
| <a href="http://svn.apache.org/repos/asf/axis/axis2/java/sandesha/trunk" class="externalLink" title="Source Code">Source Code</a> |
| </li> |
| </ul> |
| </li> |
| <li class="expanded"> |
| <a href="javascript:void(0)" title="Documentation">Documentation</a> |
| <ul> |
| <li class="none"> |
| <strong>User Guide</strong> |
| </li> |
| <li class="none"> |
| <a href="architectureGuide.html" title="Architecture Guide">Architecture Guide</a> |
| </li> |
| <li class="none"> |
| <a href="apidocs/index.html" title="Java Docs">Java Docs</a> |
| </li> |
| </ul> |
| </li> |
| <li class="expanded"> |
| <a href="javascript:void(0)" title="Project Information">Project Information</a> |
| <ul> |
| <li class="none"> |
| <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| </ul> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/licenses/" class="externalLink" title="License">License</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a> |
| </li> |
| <li class="none"> |
| <a href="http://www.apache.org/security/" class="externalLink" title="Security">Security</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> |
| </a> |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| <!-- Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. --><html> |
| |
| <h1>Apache Sandesha2 User's Guide</h1> |
| |
| <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="section"><h2>Contents<a name="Contents"></a></h2> |
| <ul> |
| <li><a href="#introduction">Introduction</a></li> |
| <li><a href="#install">Installing the Sandesa2 module</a></li> |
| <li><a href="#your_first_service">Creating and deploying a RM enabled Web |
| service - SimpleService</a></li> |
| <li><a href="#writing_clients">Writing clients for the SimpleService</a> |
| <ul> |
| <li><a href="#client_repo">Configuring the client repository</a></li> |
| <li><a href="#one_way">Doing One-Way invocation</a></li> |
| <li><a href="#request_reply">Doing a Request-Reply invocation</a></li> |
| </ul> |
| </li> |
| <li><a href="#client_api">Sandesha2 Client API</a> |
| <ul> |
| <li><a href="#version">Selecting your RM version</a></li> |
| <li><a href="#acks">Getting Acknowledgements and Faults to a given |
| Endpoint</a></li> |
| <li><a href="#managing">Managing Sequences</a></li> |
| <li><a href="#offering">Offering a Sequence ID for the Response |
| Sequence</a></li> |
| <li><a href="#creating">Creating a Sequence Without Sending any |
| Messages</a></li> |
| <li><a href="#ack_requests">Sending Acknowledgement Requests from the |
| Client Code</a></li> |
| <li><a href="#terminating">Terminating a Sequence from the Client |
| Code</a></li> |
| <li><a href="#closing">Closing a Sequence from the Client Code</a></li> |
| <li><a href="#blocking">Blocking the Client Code until a Sequence is |
| complete</a></li> |
| <li><a href="#reports">Working with Sandesha Reports</a> |
| <ul> |
| <li><a href="#sandesha_reports">SandeshaReports</a></li> |
| <li><a href="#sequence_reports">SequenceReports</a></li> |
| </ul> |
| </li> |
| <li><a href="#listners">Sandesha Listener Feature</a> |
| <ul> |
| <li><a href="#on_error">onError</a></li> |
| <li><a href="#on_timeout">onTimeOut</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#sequences">More about sequences</a> |
| <ul> |
| <li><a href="#creation">Creation of sequences</a></li> |
| <li><a href="#termination">Termination of sequences</a></li> |
| <li><a href="#closing1">Closing of sequences</a></li> |
| <li><a href="#timing_out">Timing out of sequences</a></li> |
| </ul> |
| </li> |
| <li><a href="#delivary_assurances">Delivery Assurances of Sandesha2</a></li> |
| <li><a href="#configuring">Configuring Sandesha2</a> |
| <ul> |
| <li><a href="#acknowledgementinterval">AcknowledgementInterval</a></li> |
| <li><a href="#retransmissioninterval">RetransmissionInterval</a></li> |
| <li><a href="#exponentialbackoff">ExponentialBackoff</a></li> |
| <li><a href="#maximumretransmissioncount">MaximumRetransmissionCount</a></li> |
| <li><a href="#inactivitytimeout">InactivityTimeout</a></li> |
| <li><a href="#inactivitytimeoutmeasure">InactivityTimeoutMeasure</a></li> |
| <li><a href="#invokeinorder">InvokeInOrder</a></li> |
| <li><a href="#storagemanagers">StorageManagers</a></li> |
| <li><a href="#messagetypestodrop">MessageTypesToDrop</a></li> |
| <li><a href="#securitymanager">SecurityManager</a></li> |
| </ul> |
| </li> |
| </ul> |
| <a name="introduction" id="introduction"></a> |
| |
| <div class="section"><h2>Introduction<a name="Introduction"></a></h2> |
| |
| <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 class="externalLink" href="http://axis.apache.org/axis2/java/core/docs/userguide.html">Apache Axis2 User |
| Guide</a> and <a class="externalLink" href="http://axis.apache.org/axis2/java/core/docs/Axis2ArchitectureGuide.html">Apache |
| Axis2 Architecture Guide</a>.</p> |
| |
| <p>Architecure guide for Sandesha2 is accessible at <a href="architectureGuide.html">Sandesha2 Architecture Guide</a>.</p> |
| |
| <p>Sandesha2 supports the WS-ReliableMessaging specification. It fully |
| supports the WS-ReliableMessaging 1.0 specification (February 2005) (<a class="externalLink" href="http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf"> |
| http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf </a>).</p> |
| |
| <p>This specification has been submitted to OASIS and currently being |
| standardized under the OASIS WS-RX Technical Committee as WSRM 1.1 (see <a class="externalLink" href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ws-rx"> |
| http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ws-rx </a> ). |
| Sandesha2 currently supports Committee Draft 4 of the specification being |
| developed under this technical committee ( <a class="externalLink" href="http://docs.oasis-open.org/ws-rx/wsrm/200602/wsrm-1.1-spec-cd-04.pdf"> |
| http://docs.oasis-open.org/ws-rx/wsrm/200602/wsrm-1.1-spec-cd-04.pdf |
| </a>).</p> |
| <a name="install" id="install"></a> |
| |
| <div class="section"><h2>Installing the Sandesa2 module<a name="Installing_the_Sandesa2_module"></a></h2> |
| |
| <p>In this section you will be tought how to install the Sandesha2 module in |
| a Axis2 environment. Simply follow the given instructions step by step.</p> |
| <ol style="list-style-type: decimal"> |
| <li>Download a compatible Axis2 binary distribution.</li> |
| <li>Extract the distribution file to a temporary folder (from now on |
| referred as AXIS2_HOME)</li> |
| <li><p>Add a user phase named 'RMPhase' to all four flows of the axis2.xml |
| file which is in the AXIS2_HOME/conf directory. Note the positioning of |
| 'RMPhase' within different phaseOrders.</p> |
| <div><pre> |
| |
| <axisconfig name="AxisJava2.0"> |
| |
| <!-- REST OF THE CONFIGURATION--> |
| |
| <phaseOrder type="InFlow"> |
| <phase name="Transport"/> |
| <phase name="Security"/> |
| <phase name="PreDispatch"/> |
| <phase name="Dispatch" /> |
| <phase name="OperationInPhase"/> |
| <phase name="soapmonitorPhase"/> |
| <b><phase name="RMPhase"/></b> |
| </phaseOrder> |
| |
| <phaseOrder type="OutFlow"> |
| <b><phase name="RMPhase"/></b> |
| <phase name="soapmonitorPhase"/> |
| <phase name="OperationOutPhase"/> |
| <phase name="PolicyDetermination"/> |
| <phase name="MessageOut"/> |
| <phase name="Security"/> |
| </phaseOrder> |
| |
| <phaseOrder type="InFaultFlow"> |
| <phase name="PreDispatch"/> |
| <phase name="Dispatch" /> |
| <phase name="OperationInFaultPhase"/> |
| <phase name="soapmonitorPhase"/> |
| <b><phase name="RMPhase"/></b> |
| </phaseOrder> |
| |
| <phaseOrder type="OutFaultFlow"> |
| <b><phase name="RMPhase"/></b> |
| <phase name="soapmonitorPhase"/> |
| <phase name="OperationOutFaultPhase"/> |
| <phase name="PolicyDetermination"/> |
| <phase name="MessageOut"/> |
| </phaseOrder> |
| |
| </axisconfig> |
| |
| </pre></div> |
| </li> |
| <li><p>Download the Sandesha2 binary distribution and extract it to a |
| temporary folder (from now on referred as SANDESHA2_HOME).</p> |
| </li> |
| <li><p>Get the Sandesha2 module file (sandesha2-<VERSION>.mar) from |
| SANDESHA2_HOME directory and put it to the AXIS2_HOME/repository/modules |
| directory.</p> |
| </li> |
| <li><p>Get the Sandesha2-policy-<VERSION>.jar file from the |
| SANDESHA2_HOME directory and put it to the AXIS2_HOME/lib directory.</p> |
| </li> |
| <li><p>Build the Axis2 web application by moving to the AXIS2_HOME/webapp |
| directory and running the ant target 'create.war'. Deploy the generated |
| axis2.war.</p> |
| <p></p> |
| </li> |
| </ol> |
| <a name="your_first_service" id="your_first_service"></a> |
| |
| <div class="section"><h2>Creating and deploying a RM enabled Web service - SimpleService<a name="Creating_and_deploying_a_RM_enabled_Web_service_-_SimpleService"></a></h2> |
| |
| <p>This section will give you step by step guidelines on creating a Web |
| service with Reliable Messaging support 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). We assume that you have |
| followed the previous steps to install Sandesha2 and you have installed and |
| configured JDK 1.4 or later in your system. We also assume you have the |
| ability to compile & run a simple java class.</p> |
| <ol style="list-style-type: decimal"> |
| <li><p>Add all the files that come under the AXIS2_HOME/lib to your |
| CLASSPATH.</p> |
| </li> |
| <li><p>Add the Sandesha2 jar file (sandesha2-<VERSION>.jar) from your |
| SANDESHA2_HOME to your CLASSPATH.</p> |
| </li> |
| <li><p>Create the service implementation java file as given below and |
| compile it.</p> |
| <div><pre> |
| package sandesha2.samples.userguide; |
| |
| import java.util.HashMap; |
| import java.util.Map; |
| import javax.xml.namespace.QName; |
| import org.apache.axiom.om.OMAbstractFactory; |
| import org.apache.axiom.om.OMElement; |
| import org.apache.axiom.om.OMFactory; |
| import org.apache.axiom.om.OMNamespace; |
| |
| public class RMSampleService { |
| |
| private static Map sequenceStrings = new HashMap(); |
| private final String applicationNamespaceName = "http://tempuri.org/"; |
| private final String Text = "Text"; |
| private final String Sequence = "Sequence"; |
| private final String echoStringResponse = "echoStringResponse"; |
| private final String EchoStringReturn = "EchoStringReturn"; |
| |
| public OMElement echoString(OMElement in) throws Exception { |
| |
| OMElement textElem = in.getFirstChildWithName(new QName (applicationNamespaceName,Text)); |
| OMElement sequenceElem = in.getFirstChildWithName(new QName (applicationNamespaceName,Sequence)); |
| |
| if (textElem==null) |
| throw new Exception ("'Text' element is not present as a child of the 'echoString' element"); |
| if (sequenceElem==null) |
| throw new Exception ("'Sequence' element is not present as a child of the 'echoString' element"); |
| |
| String textStr = textElem.getText(); |
| String sequenceStr = sequenceElem.getText(); |
| |
| System.out.println("'EchoString' service got text '" + textStr + "' for the sequence '" + sequenceStr + "'"); |
| |
| String previousText = (String) sequenceStrings.get(sequenceStr); |
| String resultText = (previousText==null)?textStr:previousText+textStr; |
| sequenceStrings.put(sequenceStr,resultText); |
| |
| OMFactory fac = OMAbstractFactory.getOMFactory(); |
| OMNamespace applicationNamespace = fac.createOMNamespace(applicationNamespaceName,"ns1"); |
| OMElement echoStringResponseElem = fac.createOMElement(echoStringResponse, applicationNamespace); |
| OMElement echoStringReturnElem = fac.createOMElement(EchoStringReturn, applicationNamespace); |
| |
| echoStringReturnElem.setText(resultText); |
| echoStringResponseElem.addChild(echoStringReturnElem); |
| |
| return echoStringResponseElem; |
| } |
| |
| public void ping(OMElement in) throws Exception { |
| OMElement textElem = in.getFirstChildWithName(new QName (applicationNamespaceName,Text)); |
| if (textElem==null) |
| throw new Exception ("'Text' element is not present as a child of the 'Ping' element"); |
| |
| String textValue = textElem.getText(); |
| |
| System.out.println("ping service got text:" + textValue); |
| } |
| |
| } |
| </pre></div> |
| </li> |
| <li><p>Create your services.xml file as following.</p> |
| <div><pre> |
| <service name="RMSampleService"> |
| |
| <parameter name="ServiceClass" locked="xsd:false">sandesha2.samples.userguide.RMSampleService</parameter> |
| |
| <description> |
| The userguide Sample service. |
| </description> |
| |
| <module ref="sandesha2" /> |
| <module ref="addressing" /> |
| |
| <operation name="ping" mep="http://www.w3.org/2004/08/wsdl/in-only"> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver" /> |
| </operation> |
| <operation name="echoString"> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver" /> |
| </operation> |
| |
| </service> |
| |
| </pre></div> |
| </li> |
| <li><p>Set RMSampleService.class and the services.xml files obtained from |
| the previous steps in the folder structure below. Create a |
| RMSampleService.aar file by compressing it using the jar or a zip |
| tool.</p> |
| <div><pre> RMSampleService.aar |
| | |
| |--META-INF |
| | |--services.xml |
| |-sandesha2 |
| |--samples |
| |--userguide |
| |--RMSampleService.class |
| </pre></div> |
| </li> |
| <li><p>To deploy the web service simply drop it to the |
| WEB-INF/repository/services direcory of your Axis2 web application. |
| Please read the Axis2 userguide for more information on deploying Web |
| service archieves.</p> |
| </li> |
| <li><p>List the Axis2 services to see whether the SimpleService has been |
| correctly deployed.</p> |
| </li> |
| <li><p>Congradulations. You just deployed your first Web Service with |
| Reliable Messaging support from Sandesha2.</p> |
| </li> |
| </ol> |
| <a name="writing_clients" id="writing_clients"></a> |
| |
| <div class="section"><h2>Writing Clients for Reliable Services<a name="Writing_Clients_for_Reliable_Services"></a></h2> |
| <a name="client_repo" id="client_repo"></a> |
| |
| <div class="section"><h3>Configuring the client repository<a name="Configuring_the_client_repository"></a></h3> |
| <ol style="list-style-type: decimal"> |
| <li>Create a repository directory in your system to be used as the Axis2 |
| client repository (from now on referred as CLIENT_REPO).</li> |
| <li>Put the configured the axis2.xml file from the previous section to the |
| CLIENT_REPO directory & rename it as client_axis2.xml.</li> |
| <li>Create a directory named 'modules' under the CLIENT_REPO.</li> |
| <li>Put the Sandesha mar (sandesha2-<VERSION>.mar) file from the |
| Sandesha2 binary distribution and the addressing mar file from the Axis2 |
| binary distribution (addressing-<VERSION>.mar) to the |
| CLIENT_REPO/modules directory.</li> |
| <li>Now you should have the following folder structure in the CLIENT_REPO. |
| <p></p> |
| <div><pre> Client_Repo |
| |-- client_axis2.xml |
| |--modules |
| |--sandesha2.mar |
| |--addressing.mar |
| </pre></div> |
| </li> |
| </ol> |
| <a name="one_way" id="one_way"></a> |
| |
| </div><div class="section"><h3>Doing One-Way invocation<a name="Doing_One-Way_invocation"></a></h3> |
| <ol style="list-style-type: decimal"> |
| <li>Add all the jar files fromAXIS2_HOME/lib directory to your |
| CLASSPATH.</li> |
| <li>Put the Sandesha2 jar file (sandesha2-<VERSION>.jar) to your |
| CLASSPATH.</li> |
| <li><p>Create a 'UserguidePingClient.java' file with following content.</p> |
| <div><pre> |
| package sandesha2.samples.userguide; |
| |
| import java.io.File; |
| import org.apache.axiom.om.OMAbstractFactory; |
| import org.apache.axiom.om.OMElement; |
| import org.apache.axiom.om.OMFactory; |
| import org.apache.axiom.om.OMNamespace; |
| import org.apache.axis2.AxisFault; |
| import org.apache.axis2.addressing.EndpointReference; |
| import org.apache.axis2.client.Options; |
| import org.apache.axis2.client.ServiceClient; |
| import org.apache.axis2.context.ConfigurationContext; |
| import org.apache.axis2.context.ConfigurationContextFactory; |
| import org.apache.sandesha2.client.SandeshaClientConstants; |
| import javax.xml.namespace.QName; |
| |
| |
| public class UserguidePingClient { |
| |
| private static final String applicationNamespaceName = "http://tempuri.org/"; |
| private static final String ping = "ping"; |
| private static final String Text = "Text"; |
| private static String toEPR = "http://127.0.0.1:8070/axis2/services/RMSampleService"; |
| |
| private static String CLIENT_REPO_PATH = "CLIENT_REPO"; |
| |
| public static void main(String[] args) throws AxisFault { |
| |
| String axis2_xml = CLIENT_REPO_PATH + File.separator + "client_axis2.xml"; |
| ConfigurationContext configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(CLIENT_REPO_PATH,axis2_xml); |
| |
| Options clientOptions = new Options (); |
| clientOptions.setTo(new EndpointReference (toEPR)); |
| |
| ServiceClient serviceClient = new ServiceClient (configContext,null); |
| 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")); |
| |
| clientOptions.setProperty(SandeshaClientConstants.LAST_MESSAGE, "true"); |
| serviceClient.fireAndForget(getPingOMBlock("ping3")); |
| |
| serviceClient.cleanup(); |
| } |
| |
| private static OMElement getPingOMBlock(String text) { |
| OMFactory fac = OMAbstractFactory.getOMFactory(); |
| OMNamespace namespace = fac.createOMNamespace(applicationNamespaceName,"ns1"); |
| OMElement pingElem = fac.createOMElement(ping, namespace); |
| OMElement textElem = fac.createOMElement(Text, namespace); |
| |
| textElem.setText(text); |
| pingElem.addChild(textElem); |
| |
| return pingElem; |
| } |
| } |
| </pre></div> |
| </li> |
| <li><p>In the above file replace the value of the CLIENT_REPO_PATH variable |
| with the full path to the CLIENT_REPO folder. This should be in a JAVA |
| compatible manner. e.g.: c:\\sandesha2\\repository</p> |
| </li> |
| <li>Compile the class</li> |
| <li>Run it.</li> |
| <li><p>Observe the following differences between the RM client code and a |
| normal Axis2 one-way client invocation.</p> |
| <ul> |
| <li>Engaging Sandesha2 module. |
| <p>serviceClient.engageModule(new QName ("sandesha2"));</p> |
| </li> |
| <li>Engaging Addressing module |
| <p>serviceClient.engageModule(new QName ("addressing"));</p> |
| </li> |
| <li>Setting the LAST_MESSAGE property before doing the last invocation. |
| <p>clientOptions.setProperty(SandeshaClientConstants.LAST_MESSAGE, |
| "true");</p> |
| </li> |
| </ul> |
| </li> |
| </ol> |
| <a name="request_reply" id="request_reply"></a> |
| |
| </div><div class="section"><h3>Doing Request-Reply invocation<a name="Doing_Request-Reply_invocation"></a></h3> |
| <ol style="list-style-type: decimal"> |
| <li>Add all the jar files from the AXIS2_HOME/lib directory to your |
| CLASSPATH.</li> |
| <li>Put the Sandesha2 jar file (sandesha2-<VERSION>.jar) to your |
| CLASSPATH.</li> |
| <li>Create a 'UserguideEchoClient.java' file with following content. |
| <div><pre> |
| package sandesha2.samples.userguide; |
| |
| import java.io.File; |
| import javax.xml.namespace.QName; |
| import org.apache.axiom.om.OMAbstractFactory; |
| import org.apache.axiom.om.OMElement; |
| import org.apache.axiom.om.OMFactory; |
| import org.apache.axiom.om.OMNamespace; |
| import org.apache.axiom.soap.SOAPBody; |
| import org.apache.axis2.addressing.EndpointReference; |
| import org.apache.axis2.client.Options; |
| import org.apache.axis2.client.ServiceClient; |
| import org.apache.axis2.client.async.AsyncResult; |
| import org.apache.axis2.client.async.Callback; |
| import org.apache.axis2.context.ConfigurationContext; |
| import org.apache.axis2.context.ConfigurationContextFactory; |
| import org.apache.sandesha2.client.SandeshaClientConstants; |
| |
| public class UserguideEchoClient { |
| |
| private final static String applicationNamespaceName = "http://tempuri.org/"; |
| private final static String echoString = "echoString"; |
| private final static String Text = "Text"; |
| private final static String Sequence = "Sequence"; |
| private final static String echoStringResponse = "echoStringResponse"; |
| private final static String EchoStringReturn = "EchoStringReturn"; |
| private static String toEPR = "http://127.0.0.1:8070/axis2/services/RMSampleService"; |
| |
| private static String CLIENT_REPO_PATH = "Full path to the Client Repo folder"; |
| |
| public static void main(String[] args) throws Exception { |
| |
| String axis2_xml = CLIENT_REPO_PATH + File.separator +"client_axis2.xml"; |
| ConfigurationContext configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(CLIENT_REPO_PATH,axis2_xml); |
| ServiceClient serviceClient = new ServiceClient (configContext,null); |
| |
| Options clientOptions = new Options (); |
| clientOptions.setTo(new EndpointReference (toEPR)); |
| 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"); |
| serviceClient.sendReceiveNonBlocking(getEchoOMBlock("echo2","sequence1"),callback2); |
| |
| clientOptions.setProperty(SandeshaClientConstants.LAST_MESSAGE, "true"); |
| Callback callback3 = new TestCallback ("Callback 3"); |
| serviceClient.sendReceiveNonBlocking(getEchoOMBlock("echo3","sequence1"),callback3); |
| |
| while (!callback3.isComplete()) { |
| Thread.sleep(1000); |
| } |
| |
| Thread.sleep(4000); |
| } |
| |
| private static OMElement getEchoOMBlock(String text, String sequenceKey) { |
| OMFactory fac = OMAbstractFactory.getOMFactory(); |
| OMNamespace applicationNamespace = fac.createOMNamespace(applicationNamespaceName,"ns1"); |
| OMElement echoStringElement = fac.createOMElement(echoString, applicationNamespace); |
| OMElement textElem = fac.createOMElement(Text,applicationNamespace); |
| OMElement sequenceElem = fac.createOMElement(Sequence,applicationNamespace); |
| |
| textElem.setText(text); |
| sequenceElem.setText(sequenceKey); |
| echoStringElement.addChild(textElem); |
| echoStringElement.addChild(sequenceElem); |
| |
| return echoStringElement; |
| } |
| |
| static class TestCallback extends Callback { |
| |
| String name = null; |
| public TestCallback (String name) { |
| this.name = name; |
| } |
| |
| public void onComplete(AsyncResult result) { |
| SOAPBody body = result.getResponseEnvelope().getBody(); |
| |
| OMElement echoStringResponseElem = body.getFirstChildWithName(new QName (applicationNamespaceName,echoStringResponse)); |
| OMElement echoStringReturnElem = echoStringResponseElem.getFirstChildWithName(new QName (applicationNamespaceName,EchoStringReturn)); |
| |
| String resultStr = echoStringReturnElem.getText(); |
| System.out.println("Callback '" + name + "' got result:" + resultStr); |
| } |
| |
| public void onError (Exception e) { |
| System.out.println("Error reported for test call back"); |
| e.printStackTrace(); |
| } |
| } |
| } |
| </pre></div> |
| </li> |
| <li><p>In the above file replace the value of the CLIENT_REPO_PATH variable |
| with the full path to the CLIENT_REPO folder. This should be in a JAVA |
| compatible manner. e.g.: c:\\sandesha2\\repository</p> |
| </li> |
| <li>Compile the above class.</li> |
| <li>Run the above class.</li> |
| <li>Observer the following differences between the RM client code and a |
| normal Axis2 one-way client invocation. |
| <ul> |
| <li>Engaging Sandesha2 module.</li> |
| <li>Engaging Addressing module</li> |
| <li>Setting the LAST_MESSAGE property before doing the last |
| invocation.</li> |
| </ul> |
| </li> |
| </ol> |
| <a name="client_api" id="client_api"></a> |
| |
| </div><div class="section"><h2>Sandesha2 Client API<a name="Sandesha2_Client_API"></a></h2> |
| |
| <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 |
| requirements. Some of these have to be done by simply setting a property in |
| the 'Options' object which you set to your ServiceClient. For these you have |
| 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> |
| <a name="version" id="version"></a> |
| |
| <div class="section"><h3>Selecting your RM version<a name="Selecting_your_RM_version"></a></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><pre>clientOptions.setProperty(SandeshaClientConstants.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><pre>clientOptions.setProperty(SandeshaClientConstants.RM_SPEC_VERSION,Sandesha2Constants.SPEC_VERSIONS.v1_0);</pre></div> |
| <a name="acks" id="acks"></a> |
| |
| </div><div class="section"><h3><b>Getting Acknowledgements and Faults to a Given Endpoint</b><a name="Getting_Acknowledgements_and_Faults_to_a_Given_Endpoint"></a></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 |
| acknowledgements and faults to a different endpoint, add following part to |
| the client code before doing any invocation. Note that this does not effect |
| the path of your application level faults. Only RM faults which occur within |
| the Sandesha2 will be sent to this endpoint.</p> |
| <div><pre> |
| clientOptions.setTransportInProtocol(org.apache.axis2.Constants.TRANSPORT_HTTP); |
| clientOptions.setProperty(SandeshaClientConstants.AcksTo,<endpoint>); //example endpoint - http://tempuri.org/acks. |
| </pre></div> |
| <a name="managing" id="managing"></a> |
| |
| </div><div class="section"><h3><b>Managing Sequences</b><a name="Managing_Sequences"></a></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 send messages that have the |
| same WS-Addressing To address in two or more sequences. To do this you have |
| to set a property called Sequence Key.</p> |
| <div><pre>clientOptions.setProperty(SandeshaClientConstants.SEQUENCE_KEY,<a string to identify the sequence>);</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> |
| <a name="offering" id="offering"></a> |
| |
| </div><div class="section"><h3>Offering a Sequence ID for the Response Sequence<a name="Offering_a_Sequence_ID_for_the_Response_Sequence"></a></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 |
| server accepts the offered sequence ID it can refrain from doing the Create |
| Sequence message exchange in the response path. To do this, add the following |
| to the client code.</p> |
| <div><pre>clientOptions.setProperty(SandeshaClientConstants.OFFERED_SEQUENCE_ID,<new uuid>);</pre></div> |
| <a name="creating" id="creating"></a> |
| |
| </div><div class="section"><h3>Creating a Sequence Without Sending any Messages<a name="Creating_a_Sequence_Without_Sending_any_Messages"></a></h3> |
| |
| <p>Sometimes you may need Sandesha2 client to start a sequence with a server |
| without sending any application messages. When you ask for this, Sandesha2 |
| will do a Create Sequence message exchange and obtain a new sequence ID from |
| the server. The sequenceKey value of the newly created sequence will be |
| returned from this method which could be used do message invocations with it. |
| This method also has a boolean parameter which tells whether to offer a |
| sequence for the response side. (read the part on <a href="#oas">offering |
| sequence IDs</a> to learn more about offering sequences) . The line you have |
| to add to your client code for creating a sequence is as follows.</p> |
| <div><pre>String sequenceKey = SandeshaClient.createSequence (ServiceClient serviceClient, booleanoffer);</pre></div> |
| |
| <p>There is an overloaded method of this which takes the sequenceKey from the |
| user.</p> |
| <div><pre>SandeshaClient.createSequnce (ServiceClient serviceClient, boolean offer,String sequenceKey);</pre></div> |
| <a name="ack_requests" id="ack_requests"></a> |
| |
| </div><div class="section"><h3>Sending Acknowledgement Requests from the Client Code<a name="Sending_Acknowledgement_Requests_from_the_Client_Code"></a></h3> |
| |
| <p>You can ask 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 following line to the client code.</p> |
| <div><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><pre>SandeshaClient.sendAckRequest (ServiceClient serviceClient, String sequenceKey);</pre></div> |
| <a name="terminating" id="terminating"></a> |
| |
| </div><div class="section"><h3>Terminating a Sequence from the Client Code<a name="Terminating_a_Sequence_from_the_Client_Code"></a></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.</p> |
| <div><pre>SandeshaClient.terminateSequence (ServiceClient serviceClient);</pre></div> |
| |
| <p>To terminate a specific sequence identified by a sequenceKey use |
| following.</p> |
| <div><pre>SandeshaClient.terminateSequence (ServiceClient serviceClient, String sequenceKey);</pre></div> |
| <a name="closing" id="closing"></a> |
| |
| </div><div class="section"><h3>Closing a Sequence from the Client Code<a name="Closing_a_Sequence_from_the_Client_Code"></a></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 |
| service. Again, see the section on <a href="#sequences">More about |
| sequences</a> for more details. You can issue following command from your |
| client code to close a sequence.</p> |
| <div><pre>SandeshaClient.closeSequence (ServiceClient serviceClient);</pre></div> |
| |
| <p>To close a specific sequence identified by a sequence key use the |
| following</p> |
| <div><pre>SandeshaClient.closeSequence (ServiceClient serviceClient, String sequenceKey);</pre></div> |
| <a name="blocking" id="blocking"></a> |
| |
| </div><div class="section"><h3>Blocking the Client Code until a Sequence is Complete<a name="Blocking_the_Client_Code_until_a_Sequence_is_Complete"></a></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 |
| one of the following commands in your client code.</p> |
| <div><pre>SandeshaClient.waitUntilSequenceCompleted (ServiceClient serviceClient); |
| |
| SandeshaClient.waitUntilSequenceCompleted (ServiceClient serviceClient, String sequenceKey);</pre></div> |
| |
| <p>You can also give the maximum number of seconds the RM Layer should block. |
| The blocking will stop at the end of this maximum time even if the sequence |
| is not terminated or not timed out. But note that internally RM is still |
| working. So even though the blocking stops, RM layer will continue its work |
| until you exit the program.</p> |
| <div><pre>SandeshaClient.waitUntilSequenceCompleted (ServiceClient serviceClient, long maxWaitingTime); |
| |
| SandeshaClient.waitUntilSequenceCompleted (ServiceClient serviceClient, long maxWaitingTime, String sequenceKey);</pre></div> |
| <a name="reports" id="reports"></a> |
| |
| </div><div class="section"><h3>Working with Sandesha Reports<a name="Working_with_Sandesha_Reports"></a></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> |
| <a name="sandesha_reports" id="sandesha_reports"></a> |
| |
| <div class="section"><h4>SandeshaReport<a name="SandeshaReport"></a></h4> |
| |
| <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 |
| endpoint works as a RM-Source (RMS).</p> |
| |
| <p>A SandeshaReport include following information:</p> |
| <ul> |
| <li>Sequence IDs of all the outgoing sequences.</li> |
| <li>Number of completed messages of each outgoing sequences.</li> |
| <li>Sequence IDs of all the incoming sequences.</li> |
| <li>No of completed messages of each incoming sequence.</li> |
| </ul> |
| |
| <p>To get a SandeshaReport at any time, invoke following method from your |
| client code.</p> |
| <div><pre>SandeshaClient.getSandeshaReport (ConfigurationContext c);</pre></div> |
| <a name="sequence_reports" id="sequence_reports"></a> |
| |
| </div><div class="section"><h4>SequenceReport<a name="SequenceReport"></a></h4> |
| |
| <p>A SequenceReport gives information on a specific sequences that a Sandesha |
| system is working on. This can be an incoming sequence or an outgoing |
| sequence.</p> |
| |
| <p>A SequenceReport will give following information:</p> |
| <ol style="list-style-type: decimal"> |
| <li>Status of the sequence which can be one of the following. |
| <ul> |
| <li>INITIAL - The sequence has not been established yet.</li> |
| <li>ESTABLISHED - Create Sequence / Create Sequence Response message |
| exchange has been done.</li> |
| <li>TERMINATED - The sequence has been terminated.</li> |
| <li>TIMEDOUT - The sequence has timed out.</li> |
| <li>UNKNOWN - The status cannot be determined.</li> |
| </ul> |
| </li> |
| <li>Sequence Direction |
| <ul> |
| <li>OUT - Outgoing sequence</li> |
| <li>IN - Incoming sequence</li> |
| </ul> |
| </li> |
| <li>Sequence ID of the sequence</li> |
| <li>Internal sequence ID of the sequence.</li> |
| <li>Number of completed messages of the sequence.</li> |
| </ol> |
| |
| <p>A messages is considered as <b>completed</b> when a RMS has |
| successfully sent the message to the RMD and received an acknowledgement.</p> |
| |
| <p>To get an incoming sequence report, you have to issue following command |
| from your client code.</p> |
| <div><pre>SandeshaClient.getIncomingSequenceReports (ConfigurationContext configCtx);</pre></div> |
| |
| <p>To get an outgoing Sequence Report you can invoke any of the following |
| functions.</p> |
| <div><pre>SandeshaClient.getOutgoingSequenceReport (ServiceClient serviceClient); |
| SandeshaClient.getOutgoingSequenceReport (String to,String sequenceKey,ConfigurationContext configurationContext); |
| SandeshaClient.getOutgoingSequenceReport (String internalSequenceID,ConfigurationContext configurationContext);</pre></div> |
| <a name="listners" id="listners"></a> |
| |
| </div></div><div class="section"><h3>Sandesha Listener Feature<a name="Sandesha_Listener_Feature"></a></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><pre>public interface SandeshaListener { |
| public void onError(AxisFault fault); |
| public void onTimeOut(SequenceReport report); |
| }</pre></div> |
| |
| <p>You can implement this class and set an object of that type as a property |
| in the Options object in your client code. An example is given below.</p> |
| <div><pre>options.setProperty (SandeshaClientConstants.SANDESHA_LISTENER, new SandeshaListnerImpl ());</pre></div> |
| |
| <p>Currently SandeshaListener defines the following two methods- onError |
| & onTimedOut.</p> |
| <a name="on_error" id="on_error"></a> |
| |
| </div><div class="section"><h3>onError<a name="onError"></a></h3> |
| |
| <p>This will be invoked if Sandesha2 receives a fault SOAP message. The parameter will be an AxisFault |
| representing that fault message. this will be specially useful for capturing the faults that get returned |
| due to RM protocol messages, since they do not get returned to the client code.</p> |
| <a name="on_timeout" id="on_timeout"></a> |
| |
| </div><div class="section"><h3>onTimeOut<a name="onTimeOut"></a></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> |
| <a name="sequences" id="sequences"></a> |
| |
| </div><div class="section"><h2>More about sequences<a name="More_about_sequences"></a></h2> |
| |
| <p>This section will explain you about the sequence management method of |
| Sandesha2. This is basically about four things, each explained in following |
| sub topics.</p> |
| <a name="creation" id="creation"></a> |
| |
| <div class="section"><h3>Creation of sequences<a name="Creation_of_sequences"></a></h3> |
| |
| <p>Sandesha client uses two properties given by the client to decide the |
| sequence in which it should send a particular application message. First one |
| is the address of the WS-Addressing To endpoint address. The second is a |
| special constant given by the client called Sequence Key which is set as a |
| property in the Options object as it was explained before. Sandesha2 client |
| generates a value called Internal Sequence ID by combining these two values. |
| All messages having the same Internal Sequence ID will be sent in a single |
| 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> |
| <a name="termination" id="termination"></a> |
| |
| </div><div class="section"><h3>Termination of sequences<a name="Termination_of_sequences"></a></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 an 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><pre>SandeshaClient.terminateSequence (ServiceClient);</pre></div> |
| |
| <p>You can use the function below to terminate a sequence identified by a |
| particular Sequence Key.</p> |
| <div><pre>SandeshaClient.terminateSequence (ServiceClient, SequenceKey);</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> |
| <a name="closing1" id="closing1"></a> |
| |
| </div><div class="section"><h3>Closing of sequences<a name="Closing_of_sequences"></a></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 RM version |
| you can use following functions to close the current sequence.</p> |
| <div><pre>SandeshaClient.closeSequence (ServiceClient);</pre></div> |
| |
| <p>You can use the function below to close a sequence identified by a |
| particular Sequence Key.</p> |
| <div><pre>SandeshaClient.terminateSequence (ServiceClient,, SequenceKey);</pre></div> |
| <a name="timing_out" id="timing_out"></a> |
| |
| </div><div class="section"><h3>Timing Out a Sequence<a name="Timing_Out_a_Sequence"></a></h3> |
| |
| <p>Depending on its policy configurations Sandesha2 may time out certain |
| sequences. After a sequence get 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> |
| <a name="wws" id="wws"></a> <a name="delivary_assurances" id="delivary_assurances"></a> |
| |
| </div><div class="section"><h2>Delivery Assurances of Sandesha2<a name="Delivery_Assurances_of_Sandesha2"></a></h2> |
| |
| <p>As it was mentioned in the <a href="architectureGuide.html">Architecture |
| Guide</a>, Sandesha2 provide an in-order exactly-once delivery assurance. |
| <b>In-order</b> 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 |
| methods of your service client. <b>Exactly-once</b> delivery |
| assurance means that Sandesha2 will make sure that the service will be |
| invoked only once for each message. As it was mentioned earlier Sandesha2 |
| retransmits messages to obtain reliability. Due to the exactly-once delivery |
| 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> |
| <a name="configuring" id="configuring"></a> |
| |
| <div class="section"><h2>Configuring Sandesha2<a name="Configuring_Sandesha2"></a></h2> |
| |
| <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 |
| engaged. Most of the policies in the module.xml can be overridden by setting |
| different values in a services.xml. But some policies cannot be overridden |
| and must be set correctly in the module.xml file.</p> |
| |
| <p>You will find each Sandesha2 policy and the way an alteration of it can |
| effect Sandesha2. Make sure that you set these values carefully. Setting |
| 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> |
| <a name="acknowledgementinterval" id="acknowledgementinterval"></a> |
| |
| <div class="section"><h3>AcknowledgementInterval<a name="AcknowledgementInterval"></a></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) |
| going towards the destination of the acknowledgement message. If it finds |
| any, the acknowledgement message is piggybacked in this second message and |
| both are sent together. If the RMD does not find any messages that go towards |
| 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 <b>acknowledgement interval</b> and can be configured in |
| Sandesha2 policies. The measurement unit is in milliseconds.</p> |
| <a name="retransmissioninterval" id="retransmissioninterval"></a> |
| |
| </div><div class="section"><h3>RetransmissionInterval<a name="RetransmissionInterval"></a></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> |
| <a name="exponentialbackoff" id="exponentialbackoff"></a> |
| |
| </div><div class="section"><h3>ExponentialBackoff<a name="ExponentialBackoff"></a></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 |
| retransmissions. For example, if the time gap between the fourth and fifth |
| 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> |
| <a name="maximumretransmissioncount" id="maximumretransmissioncount"></a> |
| |
| </div><div class="section"><h3>MaximumRetransmissionCount<a name="MaximumRetransmissionCount"></a></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> |
| <a name="inactivitytimeout" id="inactivitytimeout"></a> |
| |
| </div><div class="section"><h3>InactivityTimeout<a name="InactivityTimeout"></a></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> |
| <a name="inactivitytimeoutmeasure" id="inactivitytimeoutmeasure"></a> |
| |
| </div><div class="section"><h3>InactivityTimeoutMeasure<a name="InactivityTimeoutMeasure"></a></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> |
| <a name="invokeinorder" id="invokeinorder"></a> |
| |
| </div><div class="section"><h3>InvokeInOrder<a name="InvokeInOrder"></a></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 |
| particular service by setting a different value there.</p> |
| <a name="storagemanagers" id="storagemanagers"></a> |
| |
| </div><div class="section"><h3>StorageManagers<a name="StorageManagers"></a></h3> |
| |
| <p>This gives the storage manager implementation classes used by Sandesha2. |
| You have to mention the full qualified class name here.</p> |
| |
| <p>You can basically define two StorageManagers</p> |
| |
| <p>InMemoryStorageManager - Expected to store data in memory. Supposed to be |
| faster.</p> |
| |
| <p>PermanentStorageManager - Will be storing data in a database. So will be |
| little slower but real business applications will most probably prefer this |
| could provide additional features like recovery from failures.</p> |
| |
| <p>Only one of these StorageManagers will be active in a given Sandesha2 |
| instance. By default it will be the InMemorystoragemanager. If you want to |
| make the PermanentStoragemanager active add the following property to the |
| axis2.xml.</p> |
| |
| <p><parameter name="Sandesha2StorageManager" |
| locked="false">persistent</parameter></p> |
| |
| <p>StorageManager property is not overridable, 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> |
| You can easily create your own Storage Manager. Please read the Sandesha2 <a href="architectureGuide.html">Architecture Guide</a> for more details on |
| this. <a name="messagetypestodrop" id="messagetypestodrop"></a> |
| |
| </div><div class="section"><h3>MessageTypesToDrop<a name="MessageTypesToDrop"></a></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 |
| can add a comma separated list of integers in the property telling Sandesha2 |
| not to send messages of those types.</p> |
| <a name="securitymanager" id="securitymanager"></a> |
| |
| </div><div class="section"><h3>SecurityManager<a name="SecurityManager"></a></h3> |
| |
| <p>The security manager allows you to plug a certain Secure Conversation |
| implemenation into axis2. The default is a DummySecurityManager which does |
| not do any real work. We have also implemented a RamaprtBasedSecurityManager |
| which allows you to use Rampart as your secure conversation |
| implementation.</p> |
| |
| <p>To use the rampart follow the below steps.</p> |
| <ol style="list-style-type: decimal"> |
| <li><p>Add the wss4j jar file (wss4j-VERSION.jar) to your to your |
| CLASSPATH. (If your are in the server side add this to the WEB-INF/lib |
| folder of the Axis2 webapp).</p> |
| </li> |
| <li><p>Add the Rampart and Rahas modules to the Axis2 modules directory.</p> |
| </li> |
| <li><p>Change the SecurityManager policy of the Sandesha2 module.xml to the |
| following</p> |
| <p>org.apache.sandesha2.security.rampart.RampartBasedSecurityManager</p> |
| </li> |
| </ol> |
| </div> |
| </html> |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright"> |
| Copyright © 2005-2013 |
| <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |