Package org.acemq.amqp.api

Class Ack

java.lang.Object

org.acemq.amqp.api.Ack

public abstract class Ack
extends Object

What should happen to a delivery once a handler has looked at it.

Most handlers never mention this type: returning normally accepts the message and throwing decides the rest. It exists for handlers that want to state the outcome directly, and because the four cases map exactly onto AMQP 1.0 dispositions, which is what keeps one consumer API honest across both protocols.

How each outcome is carried out

Outcome	AMQP 0-9-1	AMQP 1.0
accept()	basic.ack	accepted
retry(java.time.Duration, java.lang.String)	republish to the next retry tier	modified, or scheduled delivery
deadLetter(java.lang.String)	basic.nack without requeue	rejected
release()	basic.reject with requeue	released

This would be a sealed interface with record implementations, but the published bytecode targets Java 11; see ADR-015. The constructor is private so the set of outcomes stays closed, and the isX methods let callers branch without instanceof chains.

Method Summary

Modifier and Type	Method	Description
static Ack	accept()	The message was handled successfully and must not be delivered again.
static Ack	deadLetter(String reason)	The message can never be handled by this consumer, so it goes straight to the dead-letter queue without consuming retry attempts.
Optional<Duration>	delay()
boolean	isAccept()
boolean	isDeadLetter()
boolean	isRelease()
boolean	isRetry()
Optional<String>	reason()
static Ack	release()	This consumer will not handle the message, but another one should be given the chance.
static Ack	retry(Duration after, String reason)	The attempt failed but is worth repeating, so the message goes to the next retry tier with its attempt counter incremented.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

accept

public static Ack accept()

The message was handled successfully and must not be delivered again.

Returns:

the shared accept outcome

retry

public static Ack retry(Duration after,
 String reason)

The attempt failed but is worth repeating, so the message goes to the next retry tier with its attempt counter incremented.

The delay is a request, not a guarantee. The engine honours it exactly when the broker supports delayed delivery, and otherwise rounds it to the nearest generated tier.

Parameters:

after - how long to wait before the next attempt; must not be negative

reason - why the attempt failed, recorded for operators

Returns:

a retry outcome

deadLetter

public static Ack deadLetter(String reason)

The message can never be handled by this consumer, so it goes straight to the dead-letter queue without consuming retry attempts.

Parameters:

reason - why the message is being dead-lettered, recorded on the message

Returns:

a dead-letter outcome

release

public static Ack release()

This consumer will not handle the message, but another one should be given the chance.

The attempt counter is not incremented, so this is not a retry. It suits a consumer shedding load or shutting down. Beware of returning it unconditionally: the message will come straight back.

Returns:

the shared release outcome

isAccept

public boolean isAccept()

Returns:

true if this outcome accepts the message

isRetry

public boolean isRetry()

Returns:

true if this outcome schedules another attempt

isDeadLetter

public boolean isDeadLetter()

Returns:

true if this outcome dead-letters the message

isRelease

public boolean isRelease()

Returns:

true if this outcome returns the message for another consumer

delay

public Optional<Duration> delay()

Returns:

the requested retry delay, present only for a retry outcome

reason

public Optional<String> reason()

Returns:

why the message was retried or dead-lettered, when a reason was given