http://java.net/jira/browse/JMS_SPEC-42
There were no objections to this proposal when it was raised some time ago.
I've now updated the javadocs and the draft spec with this change (these changes are additive, so those docs include
other changes).
As with all these updates, I've summarised the changes in three places: this email, in the JIRA issue, or in the
changelog at the bottom of the spec document itself.
The updated Javadocs are here:
-----------------------------
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
The only change is to Message. This wording is very generic and doesn't mention individual properties. All I've done is
to mention that some properties may be mandatory, some may be optional. I've also added a clarification to state that
the effect of setting a message selector on a property (such as JMSXDeliveryCount) which is set by the provider on
receive is undefined.
The updated draft spec is here:
-------------------------------
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
All changes are highlighted clearly with changebars. The changes for this issue are as follows:
Section 3.5.9 "JMS Defined Properties" has been updated to state that the property JMSXDeliveryCount is now mandatory
with a reference to 3.5.11 "JMSXDeliveryCount" for a definition.
Some of the wording in this section has been rearranged to reflect the fact that some properties are optional but that
one (JMSXDeliveryCount) is now mandatory. A clarification has been added to state that the effect of setting a message
selector on a property (such as JMSXDeliveryCount) which is set by the provider on receive is undefined.
Section 3.4.7 "JMSRedelivered" has been updated to say "The JMS-defined message property JMSXDeliveryCount will be set
to the number of times a particular message has been delivered. See section 3.5.11 "JMSXDeliveryCount".
A new section 3.5.11 "JMSXDeliveryCount" has been added. This states:
When a client receives a message the mandatory JMS-defined message property JMSXDeliveryCount will be set to the
number of times the message has been delivered. The first time a message is received it will be set to 1, so a value of
2 or more means the message has been redelivered.
If the JMSRedelivered value is set then the {{JMSXDeliveryCount}}property must always be 2 or more.
The purpose of the JMSXDeliveryCount property is to allow consuming applications to identify whether a particular
message is being repeatedly redelivered and take appropriate action.
The value of the JMSXDeliveryCount property is not guaranteed to be exactly correct. The JMS provider is not
expected to persist this value to ensure that its value is not lost in the event of a failure.
4.4.11 Message Acknowledgement: The sentence "a session must set the JMSRedelivered flag of messages it redelivers due
to a recovery" has been amended to state that it should also increment the JMSXDeliveryCount property as well.
4.4.12 "Duplicate Delivery of Messages": The sentence "The JMSRedelivered message header field will be set for a message
redelivered under these circumstances" has been amended to the JMSXDeliveryCount property should be incremented as well.
4.5.2 "Asynchronous delivery": This states that if a message listener throws an exception in AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE mode the message will be immediately redelivered and the JMSRedelivered message header field will be
set. This has been amended to state that the JMSXDeliveryCount message property will be incremented as well.
4.10. "Reliability": This states "Unacknowledged messages redelivered due to system failure must have the JMSRedelivered
message header field set by the JMS provider.". This has been amended to state "Unacknowledged messages redelivered due
to system failure must have the JMSRedelivered message header field set, and the JMSXDeliveryCount incremented, by the
JMS provider, as described in sections 3.4.7 "JMSRedelivered" and 3.5.11 "JMSXDeliveryCount"
11.5.6 "JMSXDeliveryCount" is the change log for this change.