Delivery delay for JMS messages
For JMS 2.0 or later, you can specify a delivery delay when sending a message. The queue manager does not deliver the message until after the specified delivery delay has elapsed.
An application can specify a delivery delay in milliseconds, when it sends a message, by using
MessageProducer.setDeliveryDelay(long deliveryDelay) or
JMSProducer.setDeliveryDelay(long deliveryDelay). This value is added to the time
at which the message is sent and gives the earliest time at which any other application can get that
Delivery delay is implemented by using a single internal staging queue. Messages that have a nonzero delivery delay are placed on this queue with a header that indicates the delivery delay and information about the target queue. A component of the queue manager that is called the delivery delay processor monitors the messages on the staging queue. When a message's delivery delay completes, the message is taken off the staging queue and placed on the target queue.
The IBM® MQ implementation of delivery delay is only
available for use when you are using the JMS client.
The following restrictions apply if you are using delivery delay with IBM MQ. These restrictions apply equally to
JMSRuntimeExceptions are thrown in the case of
- Any attempt to call
MessageProducer.setDeliveryDelaywith a nonzero value when connected to a queue manager earlier than IBM MQ 8.0, results in a
JMSExceptionwith a MQRC_FUNCTION_NOT_SUPPORTED message.
- Delivery delay is not supported for clustered destinations that have a DEFBIND value other than MQBND_BIND_NOT_FIXED. If a
MessageProducerhas a nonzero delivery delay set and an attempt is made to send to a destination that does not meet this requirement, then the call results in a
JMSExceptionwith an MQRC_OPTIONS_ERROR message.
- Any attempt to set a time to live value that is less than a previously specified nonzero delivery delay, or vice versa, results in a
JMSExceptionwith a MQRC_EXPIRY_ERROR message. This checking is done on calling
sendmethods, depending on the exact set of operations chosen.
- Use of retained publications and delivery delay is not supported. Attempting to publish a message with a delivery delay if that message has been marked as retained by using
msg.setIntProperty(JmsConstants.JMS_IBM_RETAIN, JmsConstants.RETAIN_PUBLICATION)results in a
JMSExceptionwith a MQRC_OPTIONS_ERROR message.
- Delivery delay and message grouping is not supported and any attempt to use this combination
results in a
JMSExceptionwith a MQRC_OPTIONS_ERROR message.
Any failure to send a message with delivery delay results in the client throwing a
JMSException with a suitable error message, for example queue full. In some situations, the error message might apply to the target destination, or the staging queue, or both.
IBM MQ carries out authorization checks on the original target destination when the application sends a message with a nonzero delivery delay. If the application is not authorized, then the send fails. When the queue manager detects that a message's delivery delay is complete, it opens the target queue. No authorization checks are carried out at this point.
- On Multiplatforms, SYSTEM.DDELAY.LOCAL.QUEUE exists by default. The system queue must be altered so that its MAXMSGL and MAXDEPTH attributes are sufficient for the expected load.
- On IBM MQ for z/OS®, SYSTEM.DDELAY.LOCAL.QUEUE is used as a staging queue for messages that are sent with delivery delay to both local and shared queues. On z/OS, the queue must be created and be defined so that its MAXMSGL and MAXDEPTH attributes are sufficient for the expected load.
When this queue is created, it must be secured so that as few users as possible have access to it. Access to the queue must be for maintenance and monitoring purposes only.
When a message is sent by a JMS application with a nonzero delivery delay, it is put to this queue with a new message ID. The original message ID is placed in the correlation ID of the message. This correlation ID allows an application to retrieve a message from the staging queue when required, for example if a large delivery delay was used by mistake.
Considerations for z/OS
If your system is running on z/OS, there are additional considerations to take into account if you want to use delivery delay.
If delivery delay is to be used, the system queue SYSTEM.DDELAY.LOCAL.QUEUE must be defined. It must be defined with a storage class that is sufficient for its expected load, and with INDXTYPE(NONE), and MSGDLVSQ(FIFO) specified. A sample definition of the system queue is provided, commented out, in the CSQ4INSG JCL.
Target destination resolution
If the message is sent to a queue, resolution is driven twice; once by the JMS application and once by the queue manager when it takes the message off the staging queue and sends it to the target queue.
Target subscriptions for publications are matched when the JMS application calls the send method.If a message is sent with persistence or priority according to the queue definition, then the value is set on the first resolution and not the second.
Delivery delay preserves the behavior of the expiry property, MQMD.Expiry. For example, if a message was put from a JMS application with an expiry interval of 20,000 ms and a delivery delay of 5,000 ms, and got after an elapsed time of 10,000 ms, then the value of the MQMD.expiry field might be approximately 50 tenths of a second. This value indicates that 15 seconds has elapsed from the time the message was put, to the time when it was got.
If a message expires while on the staging queue and one of the MQRO_EXPIRATION_* options is set, then the report generated is for the original message as sent by the application, the header used to contain the delivery delay information is removed.
Stopping and starting the delivery delay processor
On z/OS, the delivery delay processor is integrated into the queue manager MSTR address space. When the queue manager starts, the delivery delay processor also starts. If the staging queue is available, it opens the queue and waits for messages to arrive on it to be processed. If the staging queue has not been defined, or is disabled for gets, or another error occurs, the delivery delay processor shuts down. If the staging queue is later defined, or altered to be get enabled, the delivery delay processor restarts. If the delivery delay processor shuts down for any other reason, it can be restarted by altering the PUT attribute of the staging queue from ENABLED to DISABLED and back to ENABLED again. Should you need to stop the delivery delay processor for any reason, set the PUT attribute of the staging queue to DISABLED.
On Multiplatforms, the delay processor starts with the queue manager, and is automatically restarted in the event of a recoverable failure.
Failure to put to target queue
If a delayed message cannot be put to the target queue once its delay completes, the message is dealt with as indicated in its report options: it is either discarded or sent to the dead letter queue. If this action fails, then an attempt is made to put the message later. If the action is successful an exception report is generated and sent to the specified queue, if the report is requested. If the report message could not be sent, the report message is sent to the dead letter queue. If sending the report to the dead letter queue fails and the message is persistent, all changes are discarded and the original message rolled back and redelivered later. If the message is non-persistent the report message is discarded, but other changes are committed. If a delayed publication cannot be delivered because a subscriber has unsubscribed, or in the case of a non-durable subscriber, because it has disconnected, then the message is discarded silently. Report messages are still generated as described earlier.
If a delayed publication cannot be delivered to a subscriber and is instead put to the dead letter queue, and the put to the dead letter queue fails then the message is discarded.
To reduce the likelihood of the put to the target queue failing after the delivery delay has completed, the queue manager performs some basic checks when the JMS client sends a message with a nonzero delivery delay. These checks include whether the queue is put disabled, if the message is bigger than the maximum message length allowed, and if the queue is full.
Matching of a publication to available subscriptions occurs when the JMS application sends a message with a nonzero delivery delay. A message for each matching subscriber is put to the SYSTEM.DDELAY.LOCAL.QUEUE queue, where it is kept until the delivery delay completes. If one of those subscribers is a proxy subscription for another queue manager, then the fan-out on that queue manager occurs after the delivery delay is complete. This might result in subscribers on the other queue manager receiving publications that were originally published before they subscribed. This is a deviation from the JMS 2.0 or later specification.
Delivery delay with publish/subscribe is only supported if the target topic is configured with (N)PMSGDLV = ALLAVAIL. An attempt to use any other values results in a MQRC_PUBLICATION_FAILURE error. If the delivery delay processor fails while it is putting the message to the target queue, the result is as described in the "Failure to put to target queue" section.
All report options are supported and actioned by the delivery processor, other than the following options that are ignored, but passed through on the message when it is sent to the target queue: