qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > Client Failover Behaviour
Date Fri, 23 Sep 2011 16:53:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/21/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/qpid/Client+Failover+Behaviour">Client
Failover Behaviour</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~andrew.kennedy">Andrew
Kennedy</a>
    </h4>
        <br/>
                         <h4>Changes (5)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >When connection to broker is lost
due to network failure a Qpid client should be able to re-establish connection to a Qpid broker
if failover policy is not switched off by specifying *&quot;nofailover&quot;* as a
failover option in a connection URL. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The failover functionality on
Qpid client should be based on principle *&quot;stop the world&quot;*. When connection
is lost and <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">faiolver</span>
<span class="diff-added-words"style="background-color: #dfd;">failover</span>
is started the Qpid Client should not allow an invocation of  JMS operations which requires
sending or receiving data over the network (such as producer.send(), connection.createSession(),
consumer#receive etc). Such operations should be blocked until failover functionality restores
the connectivity with any of the supported failover methods (&#39;singlebroker&#39;,
&#39;roundrobin&#39;, &#39;failover_exchange&#39;). <br></td></tr>
            <tr><td class="diff-unchanged" > <br>The failover reconnect
feature should keep trying to reconnect to the Broker(s) in the background until connection
is restored or the application calls Connection.close() or all failover method reconnection
attempts are exhausted. Each failover method defines their own reconnection options and behavior.
<br> <br></td></tr>
            <tr><td class="diff-unchanged" >How to configure failover with connection
URL is depicted in [Connection URL Format|https://cwiki.apache.org/qpid/connection-url-format.html]
(This document describes all existing failover methods and their configuration options). <br></td></tr>
            <tr><td class="diff-unchanged" > <br>On restoring connectivity
blocked JMS operations should be allowed to finish. If the failover functionality cannot re-establish
the connection a JMSException should be thrown within any JMS operation requiring transferring
data over the network. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >The spec allows for redelivery of
this message: <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{quote}
<br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words"><span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">&quot;</span>4.4.14</span>
Duplicate Delivery of Messages <br></td></tr>
            <tr><td class="diff-unchanged" >... <br> <br>When a client
uses the AUTO_ACKNOWLEDGE mode it is not in direct control of message acknowledgment. Since
such clients cannot know for certain if a particular message has been acknowledged, they must
be prepared for re-delivery of the last consumed message. This can be caused by the client
completing its work just prior to a failure that prevents the message acknowledgment from
occurring. Only a session’s last consumed message is <br></td></tr>
            <tr><td class="diff-changed-lines" >subject to this <span class="diff-changed-words">ambiguity.<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">&quot;</span></span>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{quote}
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>Any call to recover() performed
following failover should be successfull, as the failover occurrence was already notified
through the ExceptionListener if there was one, and the request to recover() would result
in cleaning the Session and resuming message delivery with the first message sent by the new
broker. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p><font color="#ff0000">This is a draft of expected Failover Behaviour</font></p>


<h2><a name="ClientFailoverBehaviour-Qpidclientfailoverbasicprinciples."></a>Qpid
client failover basic principles.</h2>

<p>When connection to broker is lost due to network failure a Qpid client should be
able to re-establish connection to a Qpid broker if failover policy is not switched off by
specifying <b>"nofailover"</b> as a failover option in a connection URL.</p>

<p>The failover functionality on Qpid client should be based on principle <b>"stop
the world"</b>. When connection is lost and failover is started the Qpid Client should
not allow an invocation of  JMS operations which requires sending or receiving data over the
network (such as producer.send(), connection.createSession(), consumer#receive etc). Such
operations should be blocked until failover functionality restores the connectivity with any
of the supported failover methods ('singlebroker', 'roundrobin', 'failover_exchange').</p>

<p>The failover reconnect feature should keep trying to reconnect to the Broker(s) in
the background until connection is restored or the application calls Connection.close() or
all failover method reconnection attempts are exhausted. Each failover method defines their
own reconnection options and behavior.</p>

<p>How to configure failover with connection URL is depicted in <a href="https://cwiki.apache.org/qpid/connection-url-format.html"
class="external-link" rel="nofollow">Connection URL Format</a> (This document describes
all existing failover methods and their configuration options).</p>

<p>On restoring connectivity blocked JMS operations should be allowed to finish. If
the failover functionality cannot re-establish the connection a JMSException should be thrown
within any JMS operation requiring transferring data over the network.</p>

<p>When the client connection is recreated, existing Sessions, Producers, Consumers
will be refreshed transparently to allow message processing to continue, with certain caveats
described further below.</p>

<h3><a name="ClientFailoverBehaviour-FailovernotificationviaExceptionListener"></a>Failover
notification via Exception Listener</h3>

<p>In case if failover happens (or not, in the case of NoFailover method) and a Connection
has registered ExceptionListener  a special JMS exception (ConnectionLostException) needs
to be sent into ExceptionListener to notify user that network failure happens. The JMS client
application code can then decide what approach to take; call connection.close() etc, or take
advantage of their configured failover reconnect feature.</p>

<p>If the client has no Exception Listener, they will not receive this notification.
Exceptions indicating failover occured will only be thrown from other synchronous JMS methods
as required by their functionality, e.g. commit() and acknowledge() (see below for further
details).</p>

<h3><a name="ClientFailoverBehaviour-AutoAcknowledge"></a>Auto Acknowledge</h3>

<p>In Auto Acknowledge mode, by default the last message received by the application
may fail to be acknowledged if the connection gets closed during onMessage, or before the
call to receive() completes the acknowledgement.</p>

<p>In the receive() case, any such failure should be propagated as a JMSException through
the method call, and in onMessage such failure has to be notified through the ExceptionListener
if there is one.</p>

<p>The spec allows for redelivery of this message:</p>

<blockquote>
<p>4.4.14 Duplicate Delivery of Messages<br/>
...</p>

<p>When a client uses the AUTO_ACKNOWLEDGE mode it is not in direct control of message
acknowledgment. Since such clients cannot know for certain if a particular message has been
acknowledged, they must be prepared for re-delivery of the last consumed message. This can
be caused by the client completing its work just prior to a failure that prevents the message
acknowledgment from occurring. Only a session’s last consumed message is<br/>
subject to this ambiguity.</p></blockquote>

<p>Any call to recover() performed following failover should be successfull, as the
failover occurrence was already notified through the ExceptionListener if there was one, and
the request to recover() would result in cleaning the Session and resuming message delivery
with the first message sent by the new broker.</p>

<h3><a name="ClientFailoverBehaviour-DupsOkAcknowledge"></a>Dups Ok Acknowledge</h3>

<p>Duplicates are allowed in this mode, therefor any application using it should be
prepared to accept any number of duplicates and thus failover can be performed silently (other
than previously mentioned Connection level Exception Listener notification that failover has
occurred).</p>

<h3><a name="ClientFailoverBehaviour-ClientAcknowledge"></a>Client Acknowledge</h3>

<p>A Client Ack Session should be considered 'dirty' if any unacknowledged messages
have been received by the application. When the Session is refreshed during failover, if the
Session is dirty then any unacknowledged messages previously received on the Session before
failover can no longer be acknowledged and must be considered 'stale'.</p>

<p>All messages held by the client prior to failover (unacknowledged messages given
to the application, and prefetched messages) should be discarded by the client as they can
no longer be acknowledged, and record retained as to whether the Session was dirty when failover
occurred. Only messages given to the client after failover will now be available to the application.
When the next call to message.acknowledge() is performed, recover() should be called implicitly
to clean the Session and an exception should be thrown (which one TBC, but thrown in addition
to previous notification through the Exception Listener that failover has occurred) to indicate
that we were unable to complete the acknowledgement process. If none of the new messages given
to the client by the broker have been received by the application, this recover() call could
be a no-op other than marking the Session clean, otherwise it may have to perform a full recover
against the broker.</p>

<p>Any call to recover() performed following failover should be successfull, as the
failover occurence was already notified through the ExceptionListener if there was one, and
the request to recover() would result in cleaning the Session and resuming message delivery
with the first message sent by the new broker.</p>

<h3><a name="ClientFailoverBehaviour-SessionTransacted"></a>Session Transacted</h3>

<p>A Transacted Session should be considered 'dirty' if any uncommited send/receive
operations exist. When the Session is refreshed during failover, if the Session is dirty then
any uncommitted send/receive work previously conducted on the Session before failover must
be considered 'stale'. When the next call to commit() is made, the Session will automatically
be rolled back and TransactionRolledBackException thrown to notify the application of the
situation, allowing it to simply replay its transaction and continue.</p>

<p>Any call to rollback() performed following failover should be successfull, as the
failover occurence was already notified through the ExceptionListener if there was one, and
the request to rollback() would result in cleaning the Session and resuming message delivery
with the first message sent by the new broker.</p>

<h3><a name="ClientFailoverBehaviour-QueueBrowsers"></a>Queue Browsers</h3>

<p>If failover occurred while iterating through QueueBrowser enumerations a sub-class
of NotSuchElementException should be thrown by default.</p>

<h3><a name="ClientFailoverBehaviour-TemporaryQueues"></a>Temporary Queues</h3>

<p>On successful failover, it is expected that a Qpid client should restore all temporary
queues (by redeclaring the queues with the same name+attributes) created before failover.
</p>

<h3><a name="ClientFailoverBehaviour-LinkReliabilityOptions"></a>Link Reliability
Options</h3>

<p>Where a Link Reliability option is specified on an Address, it must be in conformance
with the Acknowledge Mode being used by the Session. E.g, if requesting at-least-once link
behaviour for a destination on a No-Acknowledge Session, an exception should be thrown as
this combination is contradictory. The JMS Session Acknowledge Mode set in the code should
take precedence.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/qpid/Client+Failover+Behaviour">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=27827404&revisedVersion=2&originalVersion=1">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/qpid/Client+Failover+Behaviour?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org


Mime
View raw message