Ultra Messaging queuing applications generate context, source, and receiver events based on specific actions or results.

Context Events  <-

Ultra Messaging generates context events that your client application can listen for and respond to.

You can use context events to determine the state of the context connection.

Ultra Messaging generates the following brokered context events:

Registration Success (LBM_CONTEXT_EVENT_UMQ_REGISTRATION_SUCCESS_EX)

and Registration complete (LBM_CONTEXT_EVENT_UMQ_REGISTRATION_COMPLETE_EX)
When a context connects to a broker, Ultra Messaging generates these events.

Registration Error (LBM_CONTEXT_EVENT_UMQ_REGISTRATION_ERROR)

If a context loses connection with a broker, Ultra Messaging generates this event.

Source Events  <-

Ultra Messaging generates source events that the client application can listen for and respond to.

You can use source events to determine the state of the source and messages. For example, when you write a callback function to respond to source events, you can check for a registration complete event and start sending messages only after you receive the event.

When you use a brokered context, Ultra Messaging generates the following source events:

Registration complete (LBM_SRC_EVENT_UMQ_REGISTRATION_COMPLETE_EX)

A source must be registered on the broker before the broker can process messages from the source. When you create a source, you trigger a source registration. A registration complete source event indicates that the source is ready to send messages to the broker. Ultra Messaging generates an error if you send a message before the source is registered with a broker.

Message stable (LBM_SRC_EVENT_UMQ_MESSAGE_STABLE_EX)

Ultra Messaging generates a message stable event when a message reaches the broker and is stable. A message is stable when the broker has successfully processed the message based on the message queue configuration. If you receive a message stable event for a message, you do not have to resend the message even if the source is disconnected from the broker.

If the source is disconnected from the broker before you receive a message stable event for a message, you might need to resend the message. Ultra Messaging does not automatically resend a message upon disconnection. The client application must include a mechanism to process messages that do not reach the broker.

Message Reclaimed (LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX)

Ultra Messaging generates a message reclaimed event for each message sent. If the forced message reclaim flag is set (SRC_EVENT_UME_MESSAGE_RECLAIMED_EX_FLAG_FORCED), there is no guarantee that the message is stable.

Message Reclaimed (LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED)

This event is the same as the LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX event, except that it does not include a forced message reclaim flag.

Registration error (LBM_SRC_EVENT_UMQ_REGISTRATION_ERROR)

If the source is disconnected from the broker, Ultra Messaging generates a registration error event to indicate that the source is no longer registered with the broker. For example, if the broker shuts down and the source loses its connection to the broker, Ultra Messaging generates a registration error event and any message that you send or is in flight does not reach the broker. You must wait for a registration complete event before you send more messages to the broker.

In a high availability multi-node deployment, if the active broker shuts down, Ultra Messaging elects one of the standby brokers as the new active broker. The source connects to the new active broker by default. Ultra Messaging generates a registration error event when the source loses connection to the previous active broker and a registration complete event when the source successfully registers with the new active broker.

Message ID (LBM_SRC_EVENT_UMQ_MESSAGE_ID_INFO)

For each message a source sends, Ultra Messaging generates an event that contains the message ID.

To enable this event, set the LBM_SRC_SEND_EX_FLAG_UMQ_MESSAGE_ID_INFO flag of the lbm_src_send_ex_info_t object passed on the send call.

Message Sequence Number (LBM_SRC_EVENT_SEQUENCE_NUMBER_INFO)

For each message a source sends, Ultra Messaging generates an event that contains the message sequence number.

To enable this event, set the LBM_SRC_SEND_EX_FLAG_SEQUENCE_NUMBER_INFO flag of the lbm_src_send_ex_info_t object passed on the send call.

Flight Size Notification (LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION)

Ultra Messaging can generate a flight size event when the number of in-flight messages exceeds or drops under the configured flight size. To enable this event, set configuration option umq_flight_size_behavior (context) to notify. Also, recast the event data pointer as type lbm_src_event_flight_size_notification_t.

If the number of in-flight messages exceeds the configured flight size, the lbm_src_event_flight_size_notification_t::state value is LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_STATE_OVER. If the number of in-flight messages drops below the configured flight size, the lbm_src_event_flight_size_notification_t::state value is LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_STATE_UNDER.

Source Wakeup Notification (LBM_SRC_EVENT_WAKEUP)

Ultra Messaging can generate a wakeup event when a source send operation, blocked because the number of in-flight messages exceeded the configured flight size, is able to send again. To enable this event, set configuration option umq_flight_size_behavior (context) to block. Also, recast the event data pointer as pointer type lbm_src_event_wakeup_t *.

When a source becomes unblocked, the lbm_src_event_wakeup_t::flags value is LBM_SRC_EVENT_WAKEUP_FLAG_NORMAL.

Receiver Events  <-

Ultra Messaging generates receiver events that the client application can listen for and respond to.

You can use receiver events to determine the state of the receiver and messages.

When you use brokered contexts, Ultra Messaging generates Registration complete event (LBM_MSG_UMQ_REGISTRATION_COMPLETE_EX).

A receiver must be registered on the broker before the broker can send messages to the receiver. When you create a receiver, you trigger a receiver registration. Upon registration with a broker, Ultra Messaging sends to the client application an instance of the lbm_msg_umq_registration_complete_ex_t object. This object contains the broker name, IP address, and port.

Registration error (LBM_MSG_UMQ_REGISTRATION_ERROR)

Ultra Messaging generates this event if any of the following actions occurs:

1. A broker does not connect with a receiver.
2. A brokered receiver has lost connection to a broker.

The event message contains the broker name, IP address, and port.

Beginning of Index (LBM_MSG_UMQ_INDEX_ASSIGNED_EX)

When a receiver detects a new index from the broker, Ultra Messaging generates this event. The event message contains broker and index information.

Release of Index (LBM_MSG_UMQ_INDEX_RELEASED_EX)

When a receiver receives the last message in a group of index-queued messages, Ultra Messaging generates this event. The event message contains broker and index information.

Event Changes  <-

UMQ 6.8 and beyond does not generate all the events that pre-6.8 versions generated.

The following list shows events from UMQ versions earlier than 6.8 that UMQ 6.8 queuing does not generate:

• LBM_MSG_UMQ_INDEX_ASSIGNMENT_ERROR
• LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX
• LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX
• LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_ERROR
• LBM_MSG_BOS
• LBM_MSG_EOS
• LBM_MSG_NO_SOURCE_NOTIFICATION
• LBM_MSG_UMQ_DEREGISTRATION_COMPLETE_EX
• LBM_CONTEXT_EVENT_UMQ_INSTANCE_LIST_NOTIFICATION