Acknowledging Messages Received by Clients
The messaging APIs provide acknowledgments to the Solace PubSub+ event broker for the Guaranteed messages that clients receive through a Flow. The figure below shows the process of how the Guaranteed messages that an application receives through a Flow are acknowledged.
Acknowledging Received Guaranteed Messages
API Acknowledgments
A Guaranteed Message window size limits the number of messages that the API can receive before it must return an acknowledgment to the event broker to indicate that it received the messages in the window. After the API sends this acknowledgment, the Guaranteed Message window reopens so that further messages can be sent to the API.
An application can control the windowed acknowledgments by changing the default acknowledgment timer and threshold parameters set through the Flow properties (refer to Important Flow (Message Consumer) Properties). Changing these defaults is not usually required and will change the performance characteristics of a Flow.
Application Acknowledgments
One of the two following application acknowledgment modes can be used for acknowledging a message:
- Auto-acknowledgment
- Client acknowledgment
The acknowledgment mode to use is set through one of the flow properties listed below. By default, the auto-acknowledgment mode is used.
Language |
Call |
JCSMP |
ConsumerFlowProperties.setAckMode(String ackMode) Possible values are:
|
Java RTO |
FlowHandle.PROPERTIES.ACKMODE Possible values in
|
C |
|
.NET |
FlowProperties.AckMode Possible values are:
|
JavaScript and Node.js |
solace.MessageConsumerProperties.acknowledgeMode Possible values are:
|
Auto-Acknowledgment Mode
When the auto-acknowledgment mode is used, the API automatically generates application-level acknowledgments. For JCSMP, an acknowledgment is sent after the message callback when messages are received asynchronously; and when JCSMP receives messages synchronously, an acknowledgment is sent before the message callback. For the Java RTO, C, and .NET APIs, an acknowledgment is sent after the message callback.
Client Acknowledgment Mode
When the client acknowledgment mode is used the client must explicitly send an acknowledgment for the message ID of each message received.
To explicitly send a client acknowledgment, call one of the methods or functions listed below.
Avoid allowing the number of outstanding unacknowledged messages to become excessively large (for example, 10,000 or more) because the egress message rate from the event broker can start to decline.
Language |
Call |
Java |
XMLMessage.ackMessage() |
Java RTO |
FlowHandle.ack(...) |
C |
solClient_flow_sendAck(...) |
.NET |
IFlow.Ack(...) |
JavaScript and Node.js |
solace.Message.acknowledge() Acknowledgement is called on the message object. |
When using the client acknowledgment mode with the C API, the maximum number of messages that the API can deliver to the application through the Flow without receiving client acknowledgments can be set through the SOLCLIENT_FLOW_PROP_MAX_UNACKED_MESSAGES
Flow property. By default, this property has a value of -1, which specifies that the maximum number of unacknowledged messages that can be delivered is not restricted by the API. (To change the maximum number of unacknowledged messages that may be received through an existing Flow, call solClient_flow_setMaxUnacked()
).