svn commit: r1464126 - /qpid/proton/trunk/docs/markdown/messenger/message_disposition.md

[mg...@apache.org]

Author: mgoulish
Date: Wed Apr  3 17:59:15 2013
New Revision: 1464126

URL: http://svn.apache.org/r1464126
Log:
PROTON-260 : changes to reflect feedback from Rafi and Alan

Modified:
    qpid/proton/trunk/docs/markdown/messenger/message_disposition.md

Modified: qpid/proton/trunk/docs/markdown/messenger/message_disposition.md
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/docs/markdown/messenger/message_disposition.md?rev=1464126&r1=1464125&r2=1464126&view=diff
==============================================================================
--- qpid/proton/trunk/docs/markdown/messenger/message_disposition.md (original)
+++ qpid/proton/trunk/docs/markdown/messenger/message_disposition.md Wed Apr  3 17:59:15 2013
@@ -10,11 +10,11 @@ detect the disposition of their messages
 Message States
 ---------------------------
 
-Messages have one of four different states:
-  * `PN_STATUS_UNKNOWN`
-  * `PN_STATUS_PENDING`
-  * `PN_STATUS_ACCEPTED`
-  * `PN_STATUS_REJECTED`
+Messages have one of four different states:  
+  * `PN_STATUS_UNKNOWN`  
+  * `PN_STATUS_PENDING`  
+  * `PN_STATUS_ACCEPTED`  
+  * `PN_STATUS_REJECTED`  
 
 <br/>
 
@@ -64,8 +64,27 @@ Once a message is accepted or rejected, 
 be changed, even if you have a separate tracker associated with it.
 
 
+
+<br/>
+###when to accept###
+
+Although you _can_ accept messages implicitly by letting them fall 
+off the edge of your incoming window, you _shouldn't_.  Message
+disposition is an important form of communication to the sender.
+The best practice is to let the sender know your response, by 
+explicit acceptance or rejection, as soon as you can.  Implicitly 
+accepting messages by allowing them to fall off the edge of the 
+incoming window could delay your response to the sender for an 
+unpredictable amount of time.
+
+The purpose of a nonzero window size is really to place 
+a limit on how much state your Messenger needs to track.
+
+
+
 <br/>
 <br/>
+   
 
 
 ### sending ###
@@ -75,7 +94,7 @@ if it has a positive outgoing window siz
 
         pn_messenger_set_outgoing_window ( messenger, N );
 
-and if a tracker has been associated with that message in question.
+and if a tracker has been associated with that message in question.  
 This call:
 
         pn_messenger_outgoing_tracker ( messenger );
@@ -92,7 +111,7 @@ The returned value will be one of
 
 * `PN_STATUS_ACCEPTED`
 * `PN_STATUS_REJECTED` , or
-* `PN_STATUS_PENDING` - If the receiver has not disposed the message yet.
+* `PN_STATUS_PENDING` - If the receiver has not disposed the message yet.  
 
 
 If either the sender or the receiver simply declares the message (or range of messages) to
@@ -106,15 +125,34 @@ settled messages.
 
 <br/>
 
-_Note_
+### windows do not fill up ###
+When your incoming window fills up with messages it does not stop
+you from receiving more messages.  If your incoming window has size *N*
+the only effect of receiving *N+1* messages is that the oldest message
+is automatically accepted (if you have not already accepted or rejected
+it).
+
+If your outgoing window fills, and new messages going out force the
+oldest ones to fall off the edge, your application will just lose 
+the ability to track those oldest messages.
+<br/>
+
+_Note_  
 If a message is rejected by the receiver, it does not mean that
 the message was malformed.  Malformed messages cannot be sent.
 Even messages with no content are valid messages.
 Rejection by a receiver should be understood as the receiver
-saying "I don't want this." or possibly  "I don't want this _yet_."
-dependeing on your application.
-The sender could decide to try sending the same message again later,
+saying "I don't want this." or possibly  "I don't want this _yet_." 
+depending on your application.
+The sender could decide to try sending the same message again later, 
 or to send the message to another receiver, or to discard it.
 
+The AMQP 1.0 specification permits a distinction
+between _rejecting_ the message, and _releasing_ the message,
+but the Proton library does not (yet) expose the _releasing_ 
+disposition.
+
+
+
 
 



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org