Guaranteed messages are accomplished using ACKs and NACKs (acknowledged/unacknowledged). In this way, producers receive ACKs from the broker indicating that the broker has received and accepted the message, and consumers send ACKs to the event broker telling it that they have received and completed processing of the messages.
Producers
When an application sends a Guaranteed message, the API handles delivery of the message to the event broker on behalf of the application. If the API does not receive an acknowledgment for the message within a configurable timeout, the API retransmits the message. This does not result in duplicate messages as the event broker ensures de-duplication of retransmitted messages.
The timeout is configurable as an API property. For example, in the Java API (JCSMP), it is set with the PUB_ACK_TIME property of the JCSMPProperties class. It defaults to 2000 milliseconds or 2 seconds. Most applications use the default setting.
When receiving a Guaranteed message, the event broker sends an ACK to the producer when whichever one of the following happens first:
- once the event broker has received 1/3 of a window’s worth of messages.
- if it has been 1 second since the last unacknowledged message was received.
The settings of 1/3 and 1 second are not configurable.
Note that ACKs sent from the broker to the producer are cumulative and can acknowledge multiple messages. However, the API notifies the application that a message has been acknowledged on a pre-message basis.
Some APIs allow the publishing application to request that a message be acknowledged immediately. In this case, the event broker sends the ACK as soon as it has received the message and processed it. For example, in the Java API (JCSMP), the message class has the setAckImmediately() method, which takes a Boolean parameter where the default setting is false.
Consumers
There are two different kinds of ACKs for delivery of Guaranteed messages from a queue or topic endpoint to a consumer. These are application ACKs and transport ACKs.
Application ACKs tell the event broker that the application is done processing the message and that it can be removed from the queue or topic endpoint. The API sends transport ACKs as part of the Guaranteed messaging protocol that delivers messages from the event broker to the API. The API in turn delivers the message to the application.
Application ACKs
The API sends an application ACK when:
- the application calls the API’s method to acknowledge the message.
- the message callback returns (if the application is using AUTO acknowledge).
Once the event broker has delivered a message to a consumer, it waits indefinitely for the application ACK from the consumer while the consumer remains connected. The message is only redelivered if the client disconnects or if the consumer (also known as a flow in some APIs) is closed without the application having acknowledged the message.
Transport ACKs
The API sends a transport ACK when whichever one of the following happens first:
- once the consumer or flow has received a configurable percentage of a window’s worth of messages.
- if a configurable amount of time has passed since the message was received.
Note that transport ACKs are cumulative and can acknowledge multiple messages.
The percentage of the window is configurable as an API property. For example, in the Java API (JCSMP), it is set with the SUB_ACK_WINDOW_THRESHOLD property of the JCSMPProperties class. It defaults to 60%. The timeout is also configurable. For example, in the Java API (JCSMP), it is set with the SUB_ACK_TIME property of the JCSMPProperties class. It defaults to 1 second. Thus, by default, the Java API (JCSMP) sends a transport ACK whenever one of the following happens:
- the flow has received 60% of a window’s worth of messages
- if 1 second has elapsed since the message was received
Note, again, that the transport ACK only tells the event broker that the API has received the message for delivery to the application. Receipt of the transport ACK does not cause the event broker to remove the message from the queue or topic endpoint. This only happens when the application acknowledges the message with the application ACK.
When sending a Guaranteed message to a consumer, the event broker waits for 2 seconds for a transport ACK before retransmitting the message to the consuming API. Retransmitting does not result in duplicate messages as the API ensures de-duplication of the retransmitted messages and does not pass them to the application. The 2 second timeout is not configurable.