Details

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

      Description

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

      This is a proposal to allow a JMS client to specify a delivery delay when sending a message. If a delivery delay has been specified for a message then the message will not be delivered to any consumers until after the delivery delay has expired.

      This feature has also been referred to as "delivery time", "timed messages" or "future messages".

      The API for delivery delay is intended to be similar to that for the existing timeToLive property of a MessageProducer and the corresponding JMSExpiration header field of a Message.

      There would be new methods on javax.jms.MessageProducer:

       
      public void setDeliveryDelay(long deliveryDelay) throws javax.jms.JMSException;
      
      This sets the minimum length of time in milliseconds from its dispatch time 
      that a produced message should be retained by the messaging system before 
      delivery to a consumer. 
      
      If the delivery delay is greater then the time to live then the message 
      will always be expired before delivery.
      
      public long getDeliveryDelay()
      
      Returns the minimum length of time in milliseconds from its dispatch time 
      that a produced message should be retained by the messaging system before delivery to a consumer. 
      

      There would be new methods on javax.jms.Message:

      public long getJMSDeliveryTime() throws JMSException
      
      Returns the message's delivery time. 
      
      When a message is sent, the JMSDeliveryTime header field is left unassigned. 
      After completion of the send or publish method, it holds the minimum delivery time time 
      of the message. This is the sum of the delivery delay value specified by the client and 
      the GMT at the time of the send or publish. 
      
      When the delivery delay is specified as zero, JMSDeliveryTime is set to zero to indicate
      that there is no delivery delay.
      
      A provider must not deliver a message before the defined delivery time has been reached.
      
      public void setJMSDeliveryTime(long deliveryTime) throws JMSException
      
      Sets the message's delivery time.
      
      JMS providers set this field when a message is sent. 
      This method can be used to change the value for a message that has been received. 
      

      Note that this public method is not intended for use by clients but is needed to allow providers to set this value on a message implemented by a different provider. There is a separate issue to clarify this behaviour: JMS_SPEC-34

        Issue Links

          Activity

          Hide
          Nigel Deakin added a comment -

          Following the various comments, the proposed API is as follows:

          New methods on MessageProducer

              /** Sets the default minimum length of time in milliseconds from its dispatch time
               * before a produced message becomes visible on the target destination and available
               * for delivery to consumers.  
               *
               * <P>deliveryDelay is set to zero by default.
               *
               * @param deliveryDelay the delivery delay in milliseconds.
               *
               * @exception JMSException if the JMS provider fails to set the delivery
               *                         delay due to some internal error.
               *
               * @see javax.jms.MessageProducer#getDeliveryDelay
               * @see javax.jms.Message#DEFAULT_DELIVERY_DELAY
               * 
               * @since 2.0
               */
            
             void setDeliveryDelay(long deliveryDelay) throws JMSException;      
             
             /** Gets the default minimum length of time in milliseconds from its dispatch time
              * before a produced message becomes visible on the target destination and available
              * for delivery to consumers.  
              *
              * @return the delivery delay in milliseconds.
              *
              * @exception JMSException if the JMS provider fails to get the delivery 
              *                         delay due to some internal error.
              *
              * @see javax.jms.MessageProducer#setDeliveryDelay
              * 
              * @since 2.0
              */ 
          
            long getDeliveryDelay() throws JMSException;   
          

          New methods on MessagingContext:

          /** Sets the default minimum length of time in milliseconds from its dispatch time
           * before a produced message becomes visible on the target destination and available
           * for delivery to consumers.  
           *
           * <P>deliveryDelay is set to zero by default.
           *
           * @param deliveryDelay the delivery delay in milliseconds.
           *
           * @exception JMSRuntimeException if the JMS provider fails to set the delivery
           *                         delay due to some internal error.
           *
           * @see javax.jms.MessagingContext#getDeliveryDelay
           * @see javax.jms.Message#DEFAULT_DELIVERY_DELAY
           */
          
          void setDeliveryDelay(long deliveryDelay);      
          
          /** Gets the default minimum length of time in milliseconds from its dispatch time
          * before a produced message becomes visible on the target destination and available
          * for delivery to consumers.  
          *
          * @return the delivery delay in milliseconds.
          *
          * @exception JMSRuntimeException if the JMS provider fails to get the delivery 
          *                         delay due to some internal error.
          *
          * @see javax.jms.MessagingContext#setDeliveryDelay
          */ 
          
          long getDeliveryDelay();   
          

          New methods on Message:

              /** Gets the message's delivery time value.
               *  
               * <P>When a message is sent, the <CODE>JMSDeliveryTime</CODE> header field 
               * is left unassigned. After completion of the <CODE>send</CODE> or 
               * <CODE>publish</CODE> method, it holds the delivery time of the
               * message. This is the sum of the deliveryDelay value specified by the
               * client and the GMT at the time of the <CODE>send</CODE> or 
               * <CODE>publish</CODE>.
               *
               * <P>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. 
               *
               * <P>Clients must not receive messages before the delivery time has been reached.
               * 
               * @return the message's delivery time, which is the sum of the deliveryDelay 
               * value specified by the client and the GMT at the time of the <CODE>send</CODE> or 
               * <CODE>publish</CODE>.
               *  
               * @exception JMSException if the JMS provider fails to get the message 
               *                         expiration due to some internal error.
               *
               * @see javax.jms.Message#setJMSDeliveryTime(long)
               * 
               * @since 2.0
               */ 
             long getJMSDeliveryTime() throws JMSException;
          
          
             /** Sets the message's delivery time value.
               *
               * <P>This method is for use by JMS providers only to set this field 
               * when a message is sent. This message cannot be used by clients 
               * to configure the delivery time of the message. This method is public
               * to allow one JMS provider to set this field when sending a message
               * whose implementation is not its own.
               *  
               * @param expiration the message's delivery time value
               *  
               * @exception JMSException if the JMS provider fails to set the delivery 
               *                         time due to some internal error.
               *
               * @see javax.jms.Message#getJMSDeliveryTime() 
               * 
               * @since 2.0
               */ 
             void setJMSDeliveryTime(long deliveryTime) throws JMSException;    
          

          A new static constant on Message:

              /** The message producer's default delivery delay is zero.
               * @since 2.0
               */
              static final long DEFAULT_DELIVERY_DELAY = 0;  
          
          Show
          Nigel Deakin added a comment - Following the various comments, the proposed API is as follows: New methods on MessageProducer /** Sets the default minimum length of time in milliseconds from its dispatch time * before a produced message becomes visible on the target destination and available * for delivery to consumers. * * <P>deliveryDelay is set to zero by default. * * @param deliveryDelay the delivery delay in milliseconds. * * @exception JMSException if the JMS provider fails to set the delivery * delay due to some internal error. * * @see javax.jms.MessageProducer#getDeliveryDelay * @see javax.jms.Message#DEFAULT_DELIVERY_DELAY * * @since 2.0 */ void setDeliveryDelay(long deliveryDelay) throws JMSException; /** Gets the default minimum length of time in milliseconds from its dispatch time * before a produced message becomes visible on the target destination and available * for delivery to consumers. * * @return the delivery delay in milliseconds. * * @exception JMSException if the JMS provider fails to get the delivery * delay due to some internal error. * * @see javax.jms.MessageProducer#setDeliveryDelay * * @since 2.0 */ long getDeliveryDelay() throws JMSException; New methods on MessagingContext : /** Sets the default minimum length of time in milliseconds from its dispatch time * before a produced message becomes visible on the target destination and available * for delivery to consumers. * * <P>deliveryDelay is set to zero by default. * * @param deliveryDelay the delivery delay in milliseconds. * * @exception JMSRuntimeException if the JMS provider fails to set the delivery * delay due to some internal error. * * @see javax.jms.MessagingContext#getDeliveryDelay * @see javax.jms.Message#DEFAULT_DELIVERY_DELAY */ void setDeliveryDelay(long deliveryDelay); /** Gets the default minimum length of time in milliseconds from its dispatch time * before a produced message becomes visible on the target destination and available * for delivery to consumers. * * @return the delivery delay in milliseconds. * * @exception JMSRuntimeException if the JMS provider fails to get the delivery * delay due to some internal error. * * @see javax.jms.MessagingContext#setDeliveryDelay */ long getDeliveryDelay(); New methods on Message : /** Gets the message's delivery time value. * * <P>When a message is sent, the <CODE>JMSDeliveryTime</CODE> header field * is left unassigned. After completion of the <CODE>send</CODE> or * <CODE>publish</CODE> method, it holds the delivery time of the * message. This is the sum of the deliveryDelay value specified by the * client and the GMT at the time of the <CODE>send</CODE> or * <CODE>publish</CODE>. * * <P>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. * * <P>Clients must not receive messages before the delivery time has been reached. * * @return the message's delivery time, which is the sum of the deliveryDelay * value specified by the client and the GMT at the time of the <CODE>send</CODE> or * <CODE>publish</CODE>. * * @exception JMSException if the JMS provider fails to get the message * expiration due to some internal error. * * @see javax.jms.Message#setJMSDeliveryTime(long) * * @since 2.0 */ long getJMSDeliveryTime() throws JMSException; /** Sets the message's delivery time value. * * <P>This method is for use by JMS providers only to set this field * when a message is sent. This message cannot be used by clients * to configure the delivery time of the message. This method is public * to allow one JMS provider to set this field when sending a message * whose implementation is not its own. * * @param expiration the message's delivery time value * * @exception JMSException if the JMS provider fails to set the delivery * time due to some internal error. * * @see javax.jms.Message#getJMSDeliveryTime() * * @since 2.0 */ void setJMSDeliveryTime(long deliveryTime) throws JMSException; A new static constant on Message : /** The message producer's default delivery delay is zero. * @since 2.0 */ static final long DEFAULT_DELIVERY_DELAY = 0;
          Hide
          Nigel Deakin added a comment -

          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:
          http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
          (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:
          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:

          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 4.4.10.2 "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.

          Show
          Nigel Deakin added a comment - 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: http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar (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: 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: 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 4.4.10.2 "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.
          Hide
          Nigel Deakin added a comment -

          Further updates have been made. For an up-to-date description of this feature, see section 4.12 "Delivery delay" of the JMS 2.0 public draft.

          Just one issue remains: this is described in section A.3.1 in the JMS 2.0 early draft.

          Show
          Nigel Deakin added a comment - Further updates have been made. For an up-to-date description of this feature, see section 4.12 "Delivery delay" of the JMS 2.0 public draft. Just one issue remains: this is described in section A.3.1 in the JMS 2.0 early draft.

            People

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

              Dates

              • Created:
                Updated:
                Resolved: