UMQ applications are much like UMP persistence applications, but with even fewer recovery concerns.
First, UMQ receivers typically have no concept of recovery. In queuing semantics, the individual receiver has no requirement to pick up where it left off. By default, the Queue assigns another receiver if the original receiver goes away. However, you can also configure a queue to avoid reassignment or to never reassign.
Secondly, sources either submit messages to queues or they don't. Sources that fail before a queue can acknowledge the messages as stable should simply resend the messages once recovered. In this regard, the same recovery sequence for sources at a high level can be applied to UMQ sources. Thus recovery from failure for applications is fairly straightforward.
Each context belonging to a UMQ source or receiver application registers with a queue. This registration uses a Registration ID, which is not used in the same manner as with UMP persistent stores (which register sources and receivers). UMQ Registration IDs identify individual contexts and not individual source and receiver objects. Also, UMQ Registration IDs can (and should) vary per invocation. Applications can set the use of specific Registration IDs with specific queues if they desire. But we recommend you let UMQ generate these Registration IDs or use Queue Session IDs to generate/manage them.
UMQ directs the registration of contexts with queues internally. The following is a high level description of the registration sequence.
Context creates a source object with umq_queue_name set to the desired Queue.
The context resolves the Queue using Queue Information Records (QIR) and Queue Query Records (QQR).
The context generates a Registration ID randomly or uses one provided by your application from the lbm_umq_queue_entry_t for the context.
UMQ registers the context with the Queue by sending the Registration ID to be used to the Queue.
Like UMP, you can use Session IDs to manage context registration IDs and receiver assignment IDs. The Session ID is a 64-bit value that that identifies a receiving context and its set of receivers for a particular topic. A single Session ID allows queues to correctly identify all receivers for a particular application.
With Session IDs, a receiver that fails can return with its original assignment ID and continue to receive queued messages, and receive them in the correct order. In this scenario, with option message-reassignment-timeout (see Options for a Topic's ume-attributes Element) set to 0 (never reassign), the queue continues to send queued messages to the same designated receiver in the designated order, even in the event of receiver failure and recovery.
To set the queue Session ID, set option umq_session_id to a unique value. Do not replicate this value elsewhere, even for sending applications.
UMQ assigns each message a unique Message ID (lbm_umq_msgid_t), which is composed of the sending application's context Registration ID and a unique, incrementing stamp. These Message IDs must be unique for a given queue, however, the application can use them for a variety of processing purposes.
Because receivers may be assigned messages and have failures before they can consume a message (or fail while consuming a message), queues use the following parameters to control how long a message should take to be consumed.
total lifetime
reassignment timeout
maximum reassignments
If the assigned receiver does not consume a message after the reassignment timeout expires, the queue reassigns the message to another receiver provided the total lifetime has not expired.
A queue can reassign an unconsumed message repeatedly until either it reaches the maximum reassignments or the total lifetime expires. The queue marks reassigned messages as having been re-assigned. Receivers may use this re-assignment flag as a hint that they may want to treat the message differently.
The lifetime begins when the queue first assigns the message. When the total lifetime expires, the queue either discards the message from the queue permanently or sends it to the Dead Letter Queue, if configured.
You can set a message lifetime in the following ways.
For a Source - To set a message lifetime default for a particular source, set umq_msg_total_lifetime to the number of milliseconds after which the message should not be assigned. Set message-reassignment-timeout and message-max-reassignments in Options for an Application Set's ume-attributes Element.
For a Source Sending to ULB Receivers - Set the message lifetime default with umq_ulb_application_set_message_lifetime. Set the reassignment timeout with umq_ulb_application_set_message_reassignment_timeout. Set the maximum reassignments with umq_ulb_application_set_message_max_reassignments.
For a Queue Topic - Set the umestored Queue Topic attribute, message-total-lifetime, to the number of milliseconds after which the message should not be assigned. Set message-reassignment-timeout and message-max-reassignments in Options for a Queue Topic's ume-attributes Element.
For a particular message send - Use an extended send call,
lbm_src_send_ex, that includes a pointer to lbm_umq_msg_total_lifetime_info_t in lbm_src_send_ex_info_t. Set the umq_msg_total_lifetime member to a lbm_umq_msg_total_lifetime_info_t structure and set the lbm_umq_msg_total_lifetime_info_t.umq_msg_total_lifetime to override
the total lifetime configured via umq_msg_total_lifetime.
For MIM - To set a message lifetime default for Multicast Immediate Messages (MIM), set the message lifetime option for the context, umq_msg_total_lifetime, to the number of milliseconds after which the message should not be assigned.
A receiving application can pre-empt reassignment configurations by using lbm_msg_umq_reassign() for either UMQ
or ULB receivers. This function takes an lbm_msg_t and flags for
arguments. With no flags set, the queue reassigns the message. With the
LBM_MSG_UMQ_REASSIGN_FLAG_DISCARD flag set, the queue discards the message. The
corresponding Java and .NET methods are LBMMessage.reassign().
Copyright 2007 - 2014 Informatica Corporation.