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 2005/11/29 06:02:58 UTC
svn commit: r349649 - in /webservices/sandesha/trunk/xdocs:
architectureGuide.html images/ images/RMModel.jpg
images/basicArchitecture.png userGuide.html
Author: chamikara
Date: Mon Nov 28 21:02:29 2005
New Revision: 349649
URL: http://svn.apache.org/viewcvs?rev=349649&view=rev
Log:
Added Architecture Guide and User Guide for Sandesha2
Added:
webservices/sandesha/trunk/xdocs/architectureGuide.html
webservices/sandesha/trunk/xdocs/images/
webservices/sandesha/trunk/xdocs/images/RMModel.jpg (with props)
webservices/sandesha/trunk/xdocs/images/basicArchitecture.png (with props)
webservices/sandesha/trunk/xdocs/userGuide.html
Added: webservices/sandesha/trunk/xdocs/architectureGuide.html
URL: http://svn.apache.org/viewcvs/webservices/sandesha/trunk/xdocs/architectureGuide.html?rev=349649&view=auto
==============================================================================
--- webservices/sandesha/trunk/xdocs/architectureGuide.html (added)
+++ webservices/sandesha/trunk/xdocs/architectureGuide.html Mon Nov 28 21:02:29 2005
@@ -0,0 +1,289 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>Sandesha2 Architecture guide</title>
+ <meta name="generator" content="amaya 9.2.2, see http://www.w3.org/Amaya/"
+ />
+</head>
+
+<body>
+<h2>Introduction</h2>
+
+<p>Sandesha2 implements WS-ReliableMessaging for Axis2. From the point of
+view of the Axis2 engine, Sandesha2 is a module. When this module is engaged
+to a service, that service get reliable messaging capability. According to
+the WS-ReliableMessaging specification reliable communication happens between
+two endpoints. These two are called the RM Source and the RM Destination.
+Before communication, RM Source and RM Destination do a message exchange to
+create something called a sequence. A sequence is always identified by a
+unique sequenceID. The messages of a sequence are numbered starting from
+one.</p>
+
+<p>The reliability is obtained basically using acknowledgements. the RM
+Source is required to send each messages one or more times. RM Destination
+send back acknowledgements to notify the successful reception of messages.
+After receiving the acknowledgement for a certain message RM Source can stop
+retransmission of that message.</p>
+
+<p>When all messages of a certain sequence have been successfully transmitted
+to the RM Destination, RM Source sends a TerminateSequence message to the RM
+Destination. If RM Destination receive this it can free any resources
+allocated for this sequence.</p>
+
+<p></p>
+
+<p>Folliwing popular diagram explains the most basic operations of the RM
+Source and the RM Destination.</p>
+
+<p><img alt="WS-RM Model" src="images/RMModel.jpg" /></p>
+
+<p>Application Source which is basically the client code gives the messages
+to the RM Source. RM Source first does the initial message exchange with the
+RM Destination and establish a sequence. After that RM Source send the
+messages one or more times. RM Destination send back Acknowledgements. After
+receiving acknowledgements for all the messages RM Source will send a
+TerminateSequence message to the RM Destination.</p>
+
+<p></p>
+
+<p>RM Destination will obtain the messages and invoke them by passing to the
+Application Destination. If RM Destination is confugired to invoke the
+messages in order, it will have to pause the invocation of some messages
+until all previous once have been received and invoked.</p>
+
+<p></p>
+
+<p></p>
+
+<h2>Basic Architecture of Sandesha2</h2>
+
+<p></p>
+
+<p><img alt="Basic Architecture" src="images/basicArchitecture.png" /></p>
+
+<p></p>
+
+<p>Above diagram explains the basic architecture of Sandesha2. Let's try to
+understand each part of this in detail.</p>
+
+<p></p>
+
+<h3>Handlers</h3>
+
+<p>Sandesha module deploy three handlers into Axis2 phases.</p>
+
+<p>1. SandeshaOutHandler</p>
+
+<p>2. SandeshaInHandler</p>
+
+<p>3.SandeshaGlobalInHandler</p>
+
+<p></p>
+
+<p>SandesOutHandler is the only handler added to the outFlow by the Sandesha2
+module. This handler stops the out going application messages till a sequence
+is established. The handler is deployed to the RMPhase of the outFlow.</p>
+
+<p></p>
+
+<p>SandeshaGlobalInHandler is deployed to the predispatch phase (of inFlow)
+when the RMModule is engaged. So this get called for all the messages that
+come to Axis2. This does functions that should be performed globally such as
+duplicate detection.</p>
+
+<p></p>
+
+<p>SandeshaInHandler is the second handler of the inFlow. Since this is
+situated in the RMPhase which comes after the dispatch phase, this handler
+get called only for messages that come to RM enabled services.</p>
+
+<p></p>
+
+<h3>Sender</h3>
+
+<p>Sender is responsible for transmitting and retransmitting messages. The
+sender is a seperated thread that keeps running all the time. At each
+iteration Sender check the Sandesha2 Storage to see weather there are any
+messages to be sent. If there are any those messages are sent. If the message
+does not have to be retransmitted the Sender delete this entry from the
+Storage. Otherwise the entry is only modified, and will be sent at some other
+time. How exactly this happens will be explained later.</p>
+
+<p></p>
+
+<h3>Message Processors</h3>
+
+<p>Sandesha2 have a set of message processors each extend the
+MessageProcessor interface. Each message processor is responsible for
+processing a certain type of message. For example CreateSequenceProcessor
+will process incoming Create Sequence messages and Acknowledgement processor
+will process incoming Acknowledgement messages. Please check the class
+diagram to see all the MessageProcessors.</p>
+
+<p></p>
+
+<h3>InOrderInvoker</h3>
+
+<p>InOrderInvoker is another seperate thread started by the sandesha2 system.
+This is started only if Sadesha2 has been configured to support InOrder
+Invocation delivery assurance. This is responsible for invoking messages of a
+sequence in the order of message numbers.</p>
+
+<p></p>
+
+<h3>Sandesha Storage Framework</h3>
+
+<p>Sandesha Storage Framework is the cornerstone of Sandesha2. This was
+designed to support the RM Message exchage while being independent of the
+storage implementation used. Two main storage implementations are InMemory
+storage implementation and Database based storage implementations.</p>
+
+<p>Storage framework define several beans that extend the RMBean storage (so
+these are called RMBeans). Currently there are five RMBeans. They are.</p>
+<ol>
+ <li>CreateSequenceBean (fields - InternalSequenceID, CreateSequenceMsgID,
+ SequenceID)</li>
+ <li>SenderBean (fields - key, internalSequenceID, msgNo, msgID, msgType,
+ send, resent, sentCount)</li>
+ <li>NextMsgBean (fields sequenceID, nextMsgToInvoke)</li>
+ <li>InvokerBean (fields are key, sequenceID, msgNo)</li>
+ <li>SequencePropertyBean (sequenceID, propertyName, propertyValue)</li>
+</ol>
+
+<p>Each storage implementation should have five BeanManagers that define how
+to manage each of these beans. There are five BeanManager interaces that
+define how the managers should be defined. Also there is a StorageManager
+interface that define methods to create each of these BeanManagers. Another
+interface called Transaction has general transaction methods like commit and
+roleback.</p>
+
+<p>Collectively each Sandesha2 storage implementation should have following
+classes.</p>
+<ol>
+ <li>An implementation of the StorageManager interface.</li>
+ <li>Implementations of five Bean Manager interfaces.</li>
+ <li>An implementation of a transaction interface.</li>
+</ol>
+
+<p>After implementing these the user has to add these to the classpath (may
+be as a jar) and include the name of the StorageManager implementation class
+in the sandesha2.properties file. This will tell Sandesha2 to use this
+storage implementation as the default (this will need a restart of the Axis2
+engine).</p>
+
+<p></p>
+
+<h3>Delivery Assurances</h3>
+
+<p>You can instruct Sandesha2 to give the delivery assurance you want. The
+bacis configurable delivery assurance we provide is the odering of messages.
+By setting the InOrderInvocation property of sandesha2.properties file to
+true (the default), you can tell sandesha2 to invoke messages of a sequence
+in the order. Order will be decided based on the wsrm:messageNumber. If you
+set this property to false, sandesha2 will invoke messages as they come.
+Please note that if you set an invalid value to this property, sandesha2 will
+use the defult.</p>
+
+<p>Which delivery assurance to use depend on your requirements. If you want
+want the invocation to be as fast as possible and if you do not care about
+ordering, set the property to false. If you want ordering, set it to true.
+There could be a considerable performance improvement if you set this to
+false.</p>
+
+<p>Internally sandesha2 start a special thread if inorder invocation is
+required (InOrderInvoker). This thread which is continuously running will
+only invoke the messages in order.</p>
+
+<p>In the current implementation each message (identified by sequenceID and
+message number) will be invoked only once. So exactly once delivey assurance
+is guaranteed. You cannot ask sandesha2 to invoke the same message more than
+once.</p>
+
+<p></p>
+
+<h2>Example Scenario</h2>
+
+<p>This part explains how Sandesha2 framework work internally for the most
+common RM scenario. Which is the sending of a couple of Ping messages from a
+client to the server. We will mailnly look at how Sandesha2 use its storage
+to do the RM message exchange correctly. While reading this please keep in
+mind the RMBeans and their fields which were mentioned before.</p>
+
+<p><b>Client side</b></p>
+<ul>
+ <li>Client invoke the call.</li>
+ <li>SandeshaOutHandler pauses the message and create a new Create Sequence
+ Request message.</li>
+ <li>SandeshaOutHandler adds an entry to the CreateSequenceBeanManager. The
+ internalSequenceId is an identifier unique to the whole sequence. For the
+ client side this is the concantination of wsa:To and a constants set by
+ the client (SEQUENCE_KEY). The seqienceId property is initially null. The
+ createSeqMsgID is the message ID of the crerated Create Sequence
+ message.</li>
+ <li>SandeshaOutHandler adds two entries to the SenderBeanManager. One which
+ has the send property to false represents the application message. Other
+ which has the send property to true represents the Create Sequence
+ message. The Sender threads sends (and retransmits) only the Create
+ Sequence message.</li>
+ <li><p>Sometime later the client side receives an Create Sequence Response
+ message from the server. The SandeshaInHandler which is the Sandesha2
+ handler in the InFlow finds this and delegates the processing to the
+ CreateSequenceResponse message processor. It finds the correct
+ CreateSequence manager entry using the createSequenceMessageID property
+ (the value of the create sequence message ID comes in the relatesTo part
+ of the Create Sequence Response message).</p>
+ </li>
+ <li>Client update the sequenceId property of the CreateSequence entry. Also
+ the send value of the application message entries are set to true, so
+ that the sender start sending (and retransmitting) them.</li>
+ <li>When the client receive acknowlegements for the messages it sent, the
+ tast is deligate to the Acknwoledgement processor, It removes the
+ corresponsing entry of that application message ifrom the
+ SenderBeanManager.</li>
+ <li>If an acknowledgement says that all the sent messages (upto last
+ message) were successfully received, the Acknowledgement processor
+ creates an TerminateSequence message and adds an corresponding entry to
+ the Sender table.</li>
+</ul>
+
+<p><b>Server side</b></p>
+<ul>
+ <li>Server receives an CreateSequence message. It generates a new sequence
+ ID and creates a new CreateSequenceResponse message containing this.</li>
+ <li>Server adds an entry to the NextMessage Bean manager. The initial velue
+ for nextMessageToInvoke is 1.</li>
+ <li>Server adds an entry to the Sender bean manager (of server side)
+ representing the application message. The send value is true. The Create
+ Sequence Responese message is sent by the Sender.</li>
+ <li>After some time the server receives an application message. The server
+ side SandeshaInHandler delegates this to the ApplicationMessageProcessor
+ which creates an Acknowledgement and send it. If InOrder invocation is
+ enabled, an entry is added to the InvokerBeanManager representing this.
+ (suppose the message number of this message is 2)</li>
+ <li>The InOrderInvoker which keeps looking at the InvokerBeanManager
+ entries sees that there are entries to be invoked. </li>
+ <li>the InOrderInvoker checks the entry of the NextMessageBeanManager of
+ the relevent sequence and sees that it is 1. But since only message
+ number 2 is present in the invokerBeanManager entries the invocation is
+ not done.</li>
+ <li>After some time application message 1 also comes. Now the invoker sees
+ this entry and invoke the message. It also update the
+ NextMessageBeanManager nextMessageToInvoke property to 2. The invoker
+ again check weather the new entry for the NextMessageToInvoke (2) is
+ present in the InvokerBeanManager entries. Since this is present it is
+ also invoked. The value is again updated (to 3) but no invocation is done
+ since an entry is not found.</li>
+ <li>Some time later the server may receive an TerminateSequence message. It
+ can partly remove the resources allocated for the sequence. Other part
+ (which is required by the InOrderInvoker) is removed after the invocation
+ of the last message.</li>
+</ul>
+
+<p></p>
+
+<p></p>
+</body>
+</html>
Added: webservices/sandesha/trunk/xdocs/images/RMModel.jpg
URL: http://svn.apache.org/viewcvs/webservices/sandesha/trunk/xdocs/images/RMModel.jpg?rev=349649&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/sandesha/trunk/xdocs/images/RMModel.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/sandesha/trunk/xdocs/images/basicArchitecture.png
URL: http://svn.apache.org/viewcvs/webservices/sandesha/trunk/xdocs/images/basicArchitecture.png?rev=349649&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/sandesha/trunk/xdocs/images/basicArchitecture.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/sandesha/trunk/xdocs/userGuide.html
URL: http://svn.apache.org/viewcvs/webservices/sandesha/trunk/xdocs/userGuide.html?rev=349649&view=auto
==============================================================================
--- webservices/sandesha/trunk/xdocs/userGuide.html (added)
+++ webservices/sandesha/trunk/xdocs/userGuide.html Mon Nov 28 21:02:29 2005
@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>Sandesha2 User Guide</title>
+ <meta name="generator" content="amaya 9.2.2, see http://www.w3.org/Amaya/"
+ />
+</head>
+
+<body>
+<h2>Sandesha2 User Guide</h2>
+
+<p>This document introduces you to Apache Sandesha2. Sandesha2 is the
+WS-ReliableMessaging implementation for Axis2. With Sandesha2 you can host
+some reliable web services or interact with reliable web services hosted by
+others.</p>
+
+<p></p>
+
+<h2>Using Sandesha2 in the server side</h2>
+
+<p>First lets look at how to use Sandesha2 in the server side.</p>
+
+<p>You can set up Sandesha2 for the server side in three steps.</p>
+<ol>
+ <li>Download and deploy axis2(please see Axis2 user guide for more
+ details).</li>
+ <li>Add a user phase called RMPhase to all four flows of axis2.xml.</li>
+ <li>Download latest Sandesha2 distribution and add sandesha.mar file to
+ <AXIS2_HOME>\WEB_INF\modules directory.</li>
+</ol>
+
+<p>Now your sandesha2 module is setup and deployed.</p>
+
+<p></p>
+
+<p>To host reliable web service you have to create a service archive (aar)
+file with the given details (please see Axis2 user guide for more details on
+creating aar files).</p>
+
+<p>Add sandesha module reference to the services.xml (within the aar file) as
+given below.</p>
+<source><pre><service name="OneWayService">
+<module ref="sandesha"/>
+.......................
+<!-- Your operation definitions and other stuff
+........................
+</service></pre></source>
+
+<p>Create the service archieve file.</p>
+
+<p>Deploy it by dropping it to <AXIS2_HOME>/WEB-INF/services
+directory.</p>
+
+<p>Now your service is deployed with reliable messaging support.</p>
+
+<p></p>
+
+<h2>Using Sandesha2 in the client side</h2>
+
+<p>Add Sandesha2 module (sandesha.mar) in the way you normally add a module
+to the Axis2 client side (see Axis2 user guide for more details). Following
+scenarios will explain you how to write the client code.</p>
+
+<p></p>
+
+<h3>Basic scenarios</h3>
+
+<p></p>
+
+<p><b>Sample RM enabled client code for a one way service call.</b></p>
+
+<p></p>
+<source><pre>MessageSender sender = new MessageSender (AXIS2_CLIENT_PATH);
+<span style="background-color: #CCCCCC">sender.engageModule(new QName ("sandesha"));</span>
+sender.setTo(new EndpointReference(toEPR));
+sender.set(MessageContextConstants.TRANSPORT_URL,toEPR);
+sender.send("ping",getPingOMBlock("ping1"));
+sender.send("ping",getPingOMBlock("ping2"));
+<span style="background-color: #CCCCCC">sender.set(org.apache.sandesha2.Constants.LAST_MESSAGE, "true");</span>
+sender.send("ping",getPingOMBlock("ping3"));</pre></source>
+
+<p></p>
+
+<p></p>
+
+<p>There are only two difference here from your normal client code.</p>
+
+<p>First you have to engage the sandesha module as given in the line 2.</p>
+
+<p>Before the last message you must set the last message property, which is
+given in the line 7.</p>
+
+<p></p>
+
+<p><b>Simple RM enabled client code for a request reply service call.</b></p>
+
+<p>First thing to remember is that you are not able to get synchronous
+responses with Sandesha2. Because of this if you expect response message, you
+must have a return endpoint accessible from the server side. But making two
+channel blocking invocation is perfectly valid. But please make sure tht you
+have set a suitable time out interval.</p>
+
+<p></p>
+
+<p>Here is a code sample for this scenario.</p>
+
+<p></p>
+<source><pre>Call call = new Call(AXIS2_CLIENT_PATH);
+<span style="background-color: #CCCCCC">call.engageModule(new QName("sandesha"));</span>
+call.setTo(new EndpointReference(toEPR));
+call.setTransportInfo(org.apache.axis2.Constants.TRANSPORT_HTTP,org.apache.axis2.Constants.TRANSPORT_HTTP,true);
+Callback callback1 = new TestCallback ("Callback 1");
+call.invokeNonBlocking("echoString",getEchoOMBlock("echo1"),callback1);
+Callback callback2 = new TestCallback ("Callback 2");
+call.invokeNonBlocking("echoString",getEchoOMBlock("echo2"),callback2);
+<span style="background-color: #CCCCCC">call.set(Constants.LAST_MESSAGE, "true");</span>
+Callback callback3 = new TestCallback ("Callback 3");
+call.invokeNonBlocking("echoString",getEchoOMBlock("echo3"),callback3);</pre></source>
+
+<p></p>
+
+<p>Here also the only difference from a normal client code is addition of the
+sandesha module reference and the last message tag.</p>
+
+<p></p>
+
+<h3>Advance scenarios</h3>
+
+<p><b>Getting acknowledgements and faults to a given endpoint.</b></p>
+
+<p>In the dafault configuration response path for acknowledgements and faults
+related to a sequene is the anonymous endpoint. Because of this for example
+HTTP transport will send acknowledgements and faults in the HTTP response. If
+you want to avaoid this and if you want to get acknowledgements and faults to
+a different endpoing add following part to the client code before doing any
+incovation.</p>
+<source><pre>sender.set(Constants.AcksTo,<endpoint>); //example endpoing - http://tempuri.org/acks.</pre></source>
+
+<p></p>
+
+<p><b>Managing sequences.</b></p>
+
+<p>I the default behavious Sandesha 2 assumes that messages going to the same
+endpoing should go in the same RM sequence. If you invoke two endpoints they
+will go in two sequences. If you want you can tell sandesha2 to start two
+sequences for the same endpoint as well. To do this you have to set a
+property called Sequence Key.</p>
+<source><pre>call.set(Constants.SEQUENCE_KEY,<a string to identify the sequence>);</pre></source>
+
+<p>If the sequence key is different Sandesha2 will send messages in two
+sequences even if they are sent to the same endpoint.</p>
+
+<p></p>
+
+<p><b>Offering a sequence ID for the response sequence.</b></p>
+
+<p>This is a concept of reliable messaging which may not be very useful to
+you as a user. Here what you do is offering a sequene ID for the sequence to
+be created in the response side withing the first Create Sequence Request
+message itself. with this you can avoid sending of a extra Create Sequence
+message from the server to the client. To do this add following to the client
+code.</p>
+<source><pre>call.set(Constants.OFFERED_SEQUENCE_ID,<new uuid>);</pre></source>
+
+<p></p>
+
+<p></p>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: sandesha-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: sandesha-dev-help@ws.apache.org