JMS persistent messages

IBM® MQ classes for JMS applications can use the NonPersistentMessageClass queue attribute to provide better performance for JMS persistent messages, at the expense of some reliability.

An IBM MQ queue has an attribute called NonPersistentMessageClass. The value of this attribute determines whether nonpersistent messages on the queue are discarded when the queue manager restarts.

You can set the attribute for a local queue by using the IBM MQ Script (MQSC) command, DEFINE QLOCAL, with either of the following parameters:

NPMCLASS(NORMAL): Nonpersistent messages on the queue are discarded when the queue manager restarts. This is the default value.
NPMCLASS(HIGH): Nonpersistent messages on the queue are not discarded when the queue manager restarts following a quiesced or immediate shutdown. Nonpersistent messages might be discarded, however, following a preemptive shutdown or a failure.

This topic describes how IBM MQ classes for JMS applications can use this queue attribute to provide better performance for JMS persistent messages.

The PERSISTENCE property of a Queue or Topic object can have the value HIGH. You can use the IBM MQ JMS administration tool to set this value, or an application can call the Destination.setPersistence() method passing the value WMQConstants.WMQ_PER_NPHIGH as a parameter.

If an application sends a JMS persistent message or a JMS nonpersistent message to a destination where the PERSISTENCE property has the value HIGH, and the underlying IBM MQ queue is set to NPMCLASS(HIGH), the message is put on the queue as an IBM MQ nonpersistent message. If the PERSISTENCE property of the destination does not have the value HIGH, or if the underlying queue is set to NPMCLASS(NORMAL), a JMS persistent message is put on the queue as an IBM MQ persistent message, and a JMS nonpersistent message is put on the queue as an IBM MQ nonpersistent message.

If a JMS persistent message is put on a queue as an IBM MQ nonpersistent message, and you want to ensure that the message is not discarded following a quiesced or immediate shutdown of a queue manager, all queues through which the message might be routed must be set to NPMCLASS(HIGH). In the publish/subscribe domain, these queues include subscriber queues. As an aid to enforcing this configuration, IBM MQ classes for JMS throws an InvalidDestinationException if an application tries to create a message consumer for a destination where the PERSISTENCE property has the value HIGH and the underlying IBM MQ queue is set to NPMCLASS(NORMAL).

Setting the PERSISTENCE property of a destination to HIGH does not affect how a message is received from that destination. A message sent as a JMS persistent message is received as a JMS persistent message, and a message sent as a JMS nonpersistent message is received as a JMS nonpersistent message.

When an application sends the first message to a destination where the PERSISTENCE property has the value HIGH, or when an application creates the first message consumer for a destination where the PERSISTENCE property has the value HIGH, IBM MQ classes for JMS issues an MQINQ call to determine whether NPMCLASS(HIGH) is set on the underlying IBM MQ queue. The application must therefore have the authority to inquire on the queue. In addition, IBM MQ classes for JMS preserves the result of the MQINQ call until the destination is deleted, and does not issue more MQINQ calls. Therefore, if you change the NPMCLASS setting on the underlying queue while the application is still using the destination, IBM MQ classes for JMS does not notice the new setting.

By allowing JMS persistent messages to be put on IBM MQ queues as IBM MQ nonpersistent messages, you are gaining performance at the expense of some reliability. If you require maximum reliability for JMS persistent messages, do not send the messages to a destination where the PERSISTENCE property has the value HIGH.

The JMS Layer can use SYSTEM.JMS.TEMPQ.MODEL, instead of SYSTEM.DEFAULT.MODEL.QUEUE. SYSTEM.JMS.TEMPQ.MODEL creates permanent dynamic queues that accept persistent messages, because SYSTEM.DEFAULT.MODEL.QUEUE cannot accept persistent messages. If you wish to use temporary queues to accept persistent messages, you must therefore use SYSTEM.JMS.TEMPQ.MODEL, or change the model queue to an alternative queue of your choosing.