ws-sandesha-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chamik...@apache.org
Subject svn commit: r349649 - in /webservices/sandesha/trunk/xdocs: architectureGuide.html images/ images/RMModel.jpg images/basicArchitecture.png userGuide.html
Date Tue, 29 Nov 2005 05:02:58 GMT
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
+    &lt;AXIS2_HOME&gt;\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>&lt;service name="OneWayService"&gt;
+&lt;module ref="sandesha"/&gt;
+.......................
+&lt;!-- Your operation definitions and other stuff
+........................
+&lt;/service&gt;</pre></source>
+
+<p>Create the service archieve file.</p>
+
+<p>Deploy it by dropping it to &lt;AXIS2_HOME&gt;/WEB-INF/services
+directory.</p>
+
+<p>Now your service is deployed with reliable messaging support.</p>
+
+<p></p>
+
+<h2>Using Sandesha2 in the client side</h2>
+
+<p>Add Sandesha2 module (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,&lt;endpoint&gt;); //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,&lt;a string to identify the
sequence&gt;);</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,&lt;new uuid&gt;);</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


Mime
View raw message