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-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
