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.

To Set an Acknowledgment Mode

Language

Call

JCSMP

ConsumerFlowProperties.setAckMode(String ackMode)

Possible values are:

  • JCSMPProperties.SUPPORTED_MESSAGE_ACK_AUTO

  • JCSMPProperties.SUPPORTED_MESSAGE_ACK_CLIENT

Java RTO

FlowHandle.PROPERTIES.ACKMODE

Possible values in SolEnum.AckMode are:

  • AckMode.AUTO

  • AckMode.CLIENT

C

  • SOLCLIENT_FLOW_PROP_ACKMODE_AUTO

  • SOLCLIENT_FLOW_PROP_ACKMODE_CLIENT

.NET

FlowProperties.AckMode

Possible values are:

  • AutoAck

  • ClientAck

JavaScript and Node.js

solace.MessageConsumerProperties.acknowledgeMode

Possible values are:

  • solace.MessageConsumerAcknowledgeMode.AUTO

  • solace.MessageConsumerAcknowledgeMode.CLIENT

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.

To send an Explicit Client Acknowledgment

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()).