jms-spec
  1. jms-spec
  2. JMS_SPEC-42

Make support for JMSXDeliveryCount mandatory

    Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.1
    • Fix Version/s: 2.0ED, 2.0
    • Labels:
      None

      Description

      This issue was raised by a member of the JSR 343 Expert Group and is logged here to allow the issue to be discussed and tracked.

      It is proposed that support for the JMS defined message property JMSXDeliveryCount be made mandatory.

      The JMS 1.1 specification currently defines an optional JMS defined message property JMSXDeliveryCount. When used, this is set by the JMS provider when a message is received, and is set to the number of times this message has been delivered (including the first time). The first time is 1, the second time 2, etc.

      Support for this property would allow arbitrary containers and applications to improve the way they handle "poisonous" messages - messages which cannot be consumed for some reason and need to be redelivered. For example, it would allow applications to detect when a message has been redelivered more than a specified number of times and perform some special handling such as redirecting it to some other destination.

      This property wouldn't need to be perfectly accurate every time. For example, it wouldn't be necessary to persist this value in the server. A "best efforts" implementation would probably be adequately.

        Issue Links

          Activity

          Hide
          Nigel Deakin added a comment - - edited

          I've now updated the javadocs and the draft spec with this change (these changes are additive, so those docs include other changes).

          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.

          Show
          Nigel Deakin added a comment - - edited I've now updated the javadocs and the draft spec with this change (these changes are additive, so those docs include other changes). 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.

            People

            • Assignee:
              Nigel Deakin
              Reporter:
              Nigel Deakin
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: