I've now updated the javadocs and the draft spec with details of this new feature (these changes are additive, so those docs include other changes).
The updated Javadocs are here:
(See two new methods on MessageProducer, two new methods on MessagingContext, and two new methods and a static constant on Message.
The updated draft spec is here:
(all changes are highlighted clearly with changebars. The changes for this issue are as follows:
A new section 3.4.13 "JMSDeliveryTime" which states:
When a message is sent, its delivery time is calculated as the sum of the delivery delay value specified on the send method and the current GMT value. On return from the send method, the message’s JMSDeliveryTime header field contains this value. When a message is received its JMSDeliveryTime header field contains this same value.
A message's delivery time is the earliest time when a provider may make the message visible on the target destination and available for delivery to consumers.
Clients must not receive messages before the delivery time has been reached.
A new section 4.13 "Delivery delay" which states:
A client can specify a delivery delay value in milliseconds for each message it sends. This value defines a message delivery time which is the sum of the message’s delivery delay and the GMT it is sent (for transacted sends, this is the time the client sends the message, not the time the transaction is committed).
A message's delivery time is the earliest time when a JMS provider may make the message visible on the target destination and available for delivery to consumers. The provider must not deliver messages before the delivery time has been reached.
For more information on message delivery delay, see Section 3.4.13 "JMSDeliveryTime".
Section 22.214.171.124 "Order of message sends" has been updated to state that messages with a later delivery time may be delivered after messages with an earlier delivery time.
Section 4.4.11 "Message Acknowledgement" has been updated to state that when a session's recover method is called the messages it now delivers may be different from those that were originally delivered due to the delivery of messages which could not previously be delivered as they had not reached their specified delivery time.
Section 4.6 "Message Producer" has been updated to mention that a client may now define a default delivery delay for messages sent by a producer.
Section 11.5.4 "Delivery delay" is the change log for this feature.
A deliberate decision was made to leave section 3.4.12 "Overriding message header fields" unchanged. This means that the spec will not permit an administrator to configure JMS to override the client specified values for JMSDeliveryTime.