Acknowledging Messages Received by Clients

The Solace Java RTO API provides acknowledgments to the Solace 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. During this flow, client applications can also send a negative acknowledgment (NACK) for malformed messages or messages that could not be processed.

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 adjust the windowed acknowledgments by changing the default acknowledgment timer and threshold parameters set through the flow properties. For more information, see Important Flow 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. 

The following shows how to perform acknowledgment for the Solace Java RTO API:

For Solace Java RTO API, use FlowHandle.PROPERTIES.ACKMODE

Possible values in SolEnum.AckMode are:

• AckMode.AUTO
• AckMode.CLIENT

Auto-Acknowledgment Mode

When the auto-acknowledgment mode is used, the API automatically generates application-level acknowledgments.

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. Optionally, you can use negative acknowledgments as well. For more information, see Negative Acknowledgments for Specific Messages.

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:

For the Solace Java RTO API, use FlowHandle.ack(...)

Negative Acknowledgments for Specific Messages

You can use negative acknowledgments (NACKs) if you have configured your applications for client acknowledgments (see Client Acknowledgment Mode). When you use NACKs, you can send a settlement outcome to let the event broker know the result from processing a guaranteed message that was received. Based on the settlement outcome, the event broker knows how to handle the message on its queue. You can use the following settlement outcomes:

• ACCEPTED—This ACK notifies the event broker that your client application successfully processed the guaranteed message. When the event broker receives this outcome it removes the message from its queue.
  • When you call a settlement function/methods with an outcome of ACCEPTED, it is the same as calling an ACK function/methods in Client Acknowledgment Mode.
• FAILED—This NACK notifies the event broker that your client application did not process the message. When the event broker receives this NACK it attempts to redeliver the message while adhering to delivery count limits.
• REJECTED—This NACK notifies the event broker that your client application could process the message but it was not accepted (for example, failed validation). When the event broker receives this NACK it removes the message from its queue and then moves the message to the dead message queue (DMQ) if it is configured.

Before you can use NACKs, you must add the FAILED, REJECTED, or both outcomes as NACK types when you create the flow to prepare the flow to work with negative acknowledgments. You do not need to add the ACCEPTED outcome because it is always available. If you try to use an outcome that has not been added, you get an error of Required Settlement Outcome Not Supported.

To enable and prepare the flow to use negative acknowledgments, set REQUIRED_OUTCOME_FAILED, REQUIRED_OUTCOME_REJECTED, or both to ENABLE:

int flowProps = 0;
String[] flowProperties = new String[10];
flowProperties[flowProps++] = FlowHandle.PROPERTIES.REQUIRED_OUTCOME_FAILED;
flowProperties[flowProps++] = SolEnum.BooleanValue.ENABLE;
flowProperties[flowProps++] = FlowHandle.PROPERTIES.REQUIRED_OUTCOME_REJECTED;
flowProperties[flowProps++] = SolEnum.BooleanValue.ENABLE;

To acknowledge a message, you can send an ACK or NACK using:

flowHandle.settle(msgId, messageOutcome);

Possible values to use:

• MessageOutcome.ACCEPTED
• MessageOutcome.FAILED
• MessageOutcome.REJECTED

Using NACKs with the Solace Java RTO API

The following sample code shows how to send NACKs using the Solace Java RTO API:

// Session must have SolEnum.CapabilityName.AD_APP_ACK_FAILED capability in order for negative MessageOutcomes to be supported
// MessageOutcome.ACCEPTED is always supported
 
FlowHandle flowHandle = Solclient.Allocator.newFlowHandle();
 
// Setting Flow Properties
int flowProps = 0;
String[] flowProperties = new String[10];
flowProperties[flowProps++] = FlowHandle.PROPERTIES.ACKMODE;
flowProperties[flowProps++] = SolEnum.AckMode.CLIENT;
flowProperties[flowProps++] = FlowHandle.PROPERTIES.REQUIRED_OUTCOME_FAILED;
flowProperties[flowProps++] = SolEnum.BooleanValue.ENABLE;
flowProperties[flowProps++] = FlowHandle.PROPERTIES.REQUIRED_OUTCOME_REJECTED;
flowProperties[flowProps++] = SolEnum.BooleanValue.ENABLE;
 
sessionHandle.createFlowForHandle(flowHandle, flowProperties, queue, null,
             new MessageCallbackSample() {
             @Override
             public void onMessage(Handle handle) {
                 FlowHandle flowHandle = (FlowHandle) handle;
                 MessageHandle msgHandle = flowHandle.getRxMessage();
                 long msgId = msgHandle.getGuaranteedMessageId();
                            
                 /* An example try-catch block for processing and settling a message. */    
                 try {
                     processMessage(msgHandle);
                     flowHandle.settle(msgId, MessageOutcome.ACCEPTED);
                 } catch (Exception e){
                     flowHandle.settle(msgId, MessageOutcome.FAILED);
                 }
             }    
              }, flowEventCallback);