Module dk.cloudcreate.essentials.components.foundation

Package dk.cloudcreate.essentials.components.foundation.messaging.queue

Interface DurableQueues

All Superinterfaces:

Lifecycle

public interface DurableQueues
extends Lifecycle

The DurableQueues concept supports intra-service point-to-point messaging using durable Queues that guarantee At-Least-Once delivery of messages.
The only requirement is that message producers and message consumers can access the same underlying durable Queue storage.

In a service oriented architecture it's common for all deployed instances of a given service (e.g. a Sales service) to share the same underlying database(s). As long as the different deployed (Sales) services instances can share the same underlying database, then you use the DurableQueues concept for point to point messaging across all deployed (Sales service) instances in the cluster.
If you need cross-service point to point messaging support, e.g. across instances of different services (such as across Sales, Billing and Shipping services), then you need to use a dedicated distributed Queueing service such as RabbitMQ.

This library focuses on providing a Durable Queue supporting message redelivery and Dead Letter Message functionality and comes in two flavours PostgresqlDurableQueues and MongoDurableQueues which both implement the DurableQueues interface.

Durable Queue concept that supports queuing a message on to a named Queue. Each message is associated with a unique QueueEntryId
Each Queue is uniquely identified by its QueueName
Queued messages can, per Queue, asynchronously be consumed by a QueuedMessageHandler, by registering it as a DurableQueueConsumer using consumeFromQueue(QueueName, RedeliveryPolicy, int, QueuedMessageHandler)
The Durable Queue concept supports competing consumers guaranteeing that a message is only consumed by one message handler at a time

The DurableQueueConsumer supports retrying failed messages, according to the specified RedeliveryPolicy, and ultimately marking a repeatedly failing message as a Poison-Message/Dead-Letter-Message.
The RedeliveryPolicy supports fixed, linear and exponential backoff strategies. The DurableQueues supports delayed message delivery as well as Poison-Message/Dead-Letter-Messages, which are messages that have repeatedly failed processing.
Poison Messages/Dead-Letter-Messages won't be delivered to a DurableQueueConsumer, unless they're explicitly resurrected call resurrectDeadLetterMessage(QueueEntryId, Duration)

Ordered Messages
If you're queuing with OrderedMessage then, IF and only IF, only a single cluster node is consuming from the Queue, such as with an Inbox or Outbox configured with MessageConsumptionMode.SingleGlobalConsumer (which uses a FencedLock to coordinate message consumption across cluster nodes) in order to be able to guarantee that OrderedMessage's are delivered in OrderedMessage.getOrder() per OrderedMessage.getKey() across as many parallel message consumers as you wish to use.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	DurableQueues.QueueingSortOrder	The sorting order for the QueuedMessage.getId()

Method Summary

Modifier and Type	Method	Description
boolean	acknowledgeMessageAsHandled(AcknowledgeMessageAsHandled operation)	Mark the message as acknowledged - this operation also deletes the messages from the Queue Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default boolean	acknowledgeMessageAsHandled(QueueEntryId queueEntryId)	Mark the message as acknowledged - this operation deletes the messages from the Queue Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
DurableQueues	addInterceptor(DurableQueuesInterceptor interceptor)	Add a DurableQueuesInterceptor to this DurableQueues instance The DurableQueuesInterceptor allows you to intercept all high level operations
default DurableQueues	addInterceptors(List<DurableQueuesInterceptor> interceptors)	Add DurableQueuesInterceptor's to this DurableQueues instance The DurableQueuesInterceptor allows you to intercept all high level operations
DurableQueueConsumer	consumeFromQueue(ConsumeFromQueue operation)	Start an asynchronous message consumer. Note: There can only be one DurableQueueConsumer per QueueName per DurableQueues instance Log levels of interest:
default DurableQueueConsumer	consumeFromQueue(QueueName queueName, RedeliveryPolicy redeliveryPolicy, int parallelConsumers, QueuedMessageHandler queueMessageHandler)	Start an asynchronous message consumer. Note: There can only be one DurableQueueConsumer per QueueName per DurableQueues instance Log levels of interest:
default DurableQueueConsumer	consumeFromQueue(String consumerName, QueueName queueName, RedeliveryPolicy redeliveryPolicy, int parallelConsumers, QueuedMessageHandler queueMessageHandler)	Start an asynchronous message consumer. Note: There can only be one DurableQueueConsumer per QueueName per DurableQueues instance Log levels of interest:
boolean	deleteMessage(DeleteMessage operation)	Delete a message (Queued or Dead Letter Message) Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default boolean	deleteMessage(QueueEntryId queueEntryId)	Delete a message (Queued or Dead Letter Message) Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
Optional<QueuedMessage>	getDeadLetterMessage(GetDeadLetterMessage operation)	Get a queued message that's marked as a QueuedMessage.isDeadLetterMessage()
default Optional<QueuedMessage>	getDeadLetterMessage(QueueEntryId queueEntryId)	Get a queued message that's marked as a QueuedMessage.isDeadLetterMessage()
List<QueuedMessage>	getDeadLetterMessages(GetDeadLetterMessages operation)	Query Dead Letter Messages (i.e.
default List<QueuedMessage>	getDeadLetterMessages(QueueName queueName, DurableQueues.QueueingSortOrder queueingSortOrder, long startIndex, long pageSize)	Query Dead Letter Messages (i.e.
Optional<QueuedMessage>	getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery operation)	Query the next Queued Message (i.e.
default Optional<QueuedMessage>	getNextMessageReadyForDelivery(QueueName queueName)	Query the next Queued Message (i.e.
Optional<QueuedMessage>	getQueuedMessage(GetQueuedMessage operation)	Get a queued message that is NOT marked as a QueuedMessage.isDeadLetterMessage()
default Optional<QueuedMessage>	getQueuedMessage(QueueEntryId queueEntryId)	Get a queued message that is NOT marked as a QueuedMessage.isDeadLetterMessage()
List<QueuedMessage>	getQueuedMessages(GetQueuedMessages operation)	Query Queued Messages (i.e.
default List<QueuedMessage>	getQueuedMessages(QueueName queueName, DurableQueues.QueueingSortOrder queueingSortOrder, long startIndex, long pageSize)	Query Queued Messages (i.e.
Optional<QueueName>	getQueueNameFor(QueueEntryId queueEntryId)	Get the name of the Queue where the message with queueEntryId is queued (either as a normal queued messages or a dead-letter/poison-message)
Set<QueueName>	getQueueNames()	Get all the QueueName's with messages queued, dead-letter-messages/poison-messages queued or which has an active queue consumer
long	getTotalDeadLetterMessagesQueuedFor(GetTotalDeadLetterMessagesQueuedFor operation)	Get the total number of dead-letter-messages/poison-messages queued for the given queue
default long	getTotalDeadLetterMessagesQueuedFor(QueueName queueName)	Get the total number of dead-letter-messages/poison-messages queued for the given queue
long	getTotalMessagesQueuedFor(GetTotalMessagesQueuedFor operation)	Get the total number of messages queued (i.e.
default long	getTotalMessagesQueuedFor(QueueName queueName)	Get the total number of messages queued (i.e.
TransactionalMode	getTransactionalMode()	The transactional behaviour mode of this DurableQueues instance
Optional<UnitOfWorkFactory<? extends UnitOfWork>>	getUnitOfWorkFactory()
boolean	hasMessagesQueuedFor(QueueName queueName)	Check if there are any messages queued (i.e.
Optional<QueuedMessage>	markAsDeadLetterMessage(MarkAsDeadLetterMessage operation)	Mark an already Queued Message as a Dead Letter Message (or Poison Message). Dead Letter Messages won't be delivered to any DurableQueueConsumer (called by the DurableQueueConsumer) To deliver a Dead Letter Message you must first resurrect the message using resurrectDeadLetterMessage(QueueEntryId, Duration) Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default Optional<QueuedMessage>	markAsDeadLetterMessage(QueueEntryId queueEntryId, Exception causeForBeingMarkedAsDeadLetter)	Mark an already Queued Message as a Dead Letter Message (or Poison Message). Dead Letter Messages won't be delivered to any DurableQueueConsumer (called by the DurableQueueConsumer) To deliver a Dead Letter Message you must first resurrect the message using resurrectDeadLetterMessage(QueueEntryId, Duration) Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
int	purgeQueue(PurgeQueue operation)	Delete all messages (Queued or Dead letter Messages) in the given queue
default int	purgeQueue(QueueName queueName)	Delete all messages (Queued or Dead letter Messages) in the given queue
default List<NextQueuedMessage>	queryForMessagesSoonReadyForDelivery(QueueName queueName, int maxNumberOfMessagesToReturn)	Query for the next maxNumberOfMessagesToReturn queued messages that are soon ready to be delivered using Instant.now() as withNextDeliveryTimestampAfter This is a useful method for a custom queue consumer to know if it's necessary to call getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery)
List<NextQueuedMessage>	queryForMessagesSoonReadyForDelivery(QueueName queueName, Instant withNextDeliveryTimestampAfter, int maxNumberOfMessagesToReturn)	Query for the next maxNumberOfMessagesToReturn queued messages that are soon ready to be delivered This is a useful method for a custom queue consumer to know if it's necessary to call getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery)
QueueEntryId	queueMessage(QueueMessage operation)	Queue a message for asynchronous delivery without delay to a DurableQueueConsumer Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default QueueEntryId	queueMessage(QueueName queueName, Message message)	Queue a message for asynchronous delivery without delay to a DurableQueueConsumer Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default QueueEntryId	queueMessage(QueueName queueName, Message message, Exception causeOfEnqueuing, Duration deliveryDelay)	Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default QueueEntryId	queueMessage(QueueName queueName, Message message, Duration deliveryDelay)	Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default QueueEntryId	queueMessage(QueueName queueName, Message message, Optional<Exception> causeOfEnqueuing, Optional<Duration> deliveryDelay)	Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default QueueEntryId	queueMessage(QueueName queueName, Message message, Optional<Duration> deliveryDelay)	Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
QueueEntryId	queueMessageAsDeadLetterMessage(QueueMessageAsDeadLetterMessage operation)	Queue the message directly as a Dead Letter Message.
default QueueEntryId	queueMessageAsDeadLetterMessage(QueueName queueName, Message message, Exception causeOfError)	Queue the message directly as a Dead Letter Message.
List<QueueEntryId>	queueMessages(QueueMessages operation)	Queue multiple messages to the same queue.
default List<QueueEntryId>	queueMessages(QueueName queueName, List<? extends Message> messages)	Queue multiple messages to the same queue.
default List<QueueEntryId>	queueMessages(QueueName queueName, List<? extends Message> messages, Duration deliveryDelay)	Queue multiple messages to the same queue.
default List<QueueEntryId>	queueMessages(QueueName queueName, List<? extends Message> messages, Optional<Duration> deliveryDelay)	Queue multiple messages to the same queue.
DurableQueues	removeInterceptor(DurableQueuesInterceptor interceptor)	Remove a DurableQueuesInterceptor from this DurableQueues instance
Optional<QueuedMessage>	resurrectDeadLetterMessage(ResurrectDeadLetterMessage operation)	Resurrect a Dead Letter Message for redelivery after the specified deliveryDelay Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default Optional<QueuedMessage>	resurrectDeadLetterMessage(QueueEntryId queueEntryId, Duration deliveryDelay)	Resurrect a Dead Letter Message for redelivery after the specified deliveryDelay Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
Optional<QueuedMessage>	retryMessage(RetryMessage operation)	Schedule the message for redelivery after the specified deliveryDelay (called by the DurableQueueConsumer) Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional
default Optional<QueuedMessage>	retryMessage(QueueEntryId queueEntryId, Exception causeForRetry, Duration deliveryDelay)	Schedule the message for redelivery after the specified deliveryDelay (called by the DurableQueueConsumer) Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Methods inherited from interface dk.cloudcreate.essentials.components.foundation.Lifecycle

isStarted, start, stop

Method Details

getQueueNames

Set<QueueName> getQueueNames()

Get all the QueueName's with messages queued, dead-letter-messages/poison-messages queued or which has an active queue consumer

Returns:

all the QueueName's with messages queued, dead-letter-messages/poison-messages queued or which has an active queue consumer

addInterceptor

DurableQueues addInterceptor(DurableQueuesInterceptor interceptor)

Add a DurableQueuesInterceptor to this DurableQueues instance
The DurableQueuesInterceptor allows you to intercept all high level operations

Parameters:

interceptor - the interceptor to add

Returns:

this DurableQueues instance

addInterceptors

default DurableQueues addInterceptors(List<DurableQueuesInterceptor> interceptors)

Add DurableQueuesInterceptor's to this DurableQueues instance
The DurableQueuesInterceptor allows you to intercept all high level operations

Parameters:

interceptors - the interceptors to add

Returns:

this DurableQueues instance

removeInterceptor

DurableQueues removeInterceptor(DurableQueuesInterceptor interceptor)

Remove a DurableQueuesInterceptor from this DurableQueues instance

Parameters:

interceptor - the interceptor to remove

Returns:

this DurableQueues instance

getQueueNameFor

Optional<QueueName> getQueueNameFor(QueueEntryId queueEntryId)

Get the name of the Queue where the message with queueEntryId is queued (either as a normal queued messages or a dead-letter/poison-message)

Parameters:

queueEntryId - the queue entry id of the message we want to know the QueueName for

Returns:

The QueueName wrapped in an Optional if DurableQueues contains a normal queued messages or a dead-letter/poison-message; otherwise an Optional.empty()

getDeadLetterMessage

default Optional<QueuedMessage> getDeadLetterMessage(QueueEntryId queueEntryId)

Get a queued message that's marked as a QueuedMessage.isDeadLetterMessage()

Parameters:

queueEntryId - the messages unique queue entry id

Returns:

the message wrapped in an Optional if the message exists and QueuedMessage.isDeadLetterMessage(), otherwise Optional.empty()

getDeadLetterMessage

Optional<QueuedMessage> getDeadLetterMessage(GetDeadLetterMessage operation)

Get a queued message that's marked as a QueuedMessage.isDeadLetterMessage()

Parameters:

operation - the GetDeadLetterMessage operation

Returns:

the message wrapped in an Optional if the message exists and QueuedMessage.isDeadLetterMessage(), otherwise Optional.empty()

getQueuedMessage

default Optional<QueuedMessage> getQueuedMessage(QueueEntryId queueEntryId)

Get a queued message that is NOT marked as a QueuedMessage.isDeadLetterMessage()

Parameters:

queueEntryId - the messages unique queue entry id

Returns:

the message wrapped in an Optional if the message exists and NOT a QueuedMessage.isDeadLetterMessage(), otherwise Optional.empty()

getQueuedMessage

Optional<QueuedMessage> getQueuedMessage(GetQueuedMessage operation)

Get a queued message that is NOT marked as a QueuedMessage.isDeadLetterMessage()

Parameters:

operation - the GetQueuedMessage operation

Returns:

the message wrapped in an Optional if the message exists and NOT a QueuedMessage.isDeadLetterMessage(), otherwise Optional.empty()

getTransactionalMode

TransactionalMode getTransactionalMode()

The transactional behaviour mode of this DurableQueues instance

Returns:

The transactional behaviour mode of a DurableQueues instance

getUnitOfWorkFactory

Optional<UnitOfWorkFactory<? extends UnitOfWork>> getUnitOfWorkFactory()

Returns:

If getTransactionalMode() is TransactionalMode.FullyTransactional then it will return the UnitOfWorkFactory wrapped in an Optional, otherwise it will return an Optional.empty()

consumeFromQueue

default DurableQueueConsumer consumeFromQueue(String consumerName,
 QueueName queueName,
 RedeliveryPolicy redeliveryPolicy,
 int parallelConsumers,
 QueuedMessageHandler queueMessageHandler)

Start an asynchronous message consumer.
Note: There can only be one DurableQueueConsumer per QueueName per DurableQueues instance
Log levels of interest:

 dk.cloudcreate.essentials.components.foundation.messaging.queue.DurableQueueConsumer
 dk.cloudcreate.essentials.components.foundation.messaging.queue.DurableQueueConsumer.MessageHandlingFailures
 

Parameters:

consumerName - the name of the consumer (for logging purposes)

queueName - the name of the queue that the consumer will be listening for queued messages ready to be delivered to the QueuedMessageHandler provided

redeliveryPolicy - the redelivery policy in case the handling of a message fails

parallelConsumers - the number of parallel consumers (if number > 1 then you will effectively have competing consumers on the current node)

queueMessageHandler - the message handler that will receive QueuedMessage's. See PatternMatchingQueuedMessageHandler

Returns:

the queue consumer

consumeFromQueue

default DurableQueueConsumer consumeFromQueue(QueueName queueName,
 RedeliveryPolicy redeliveryPolicy,
 int parallelConsumers,
 QueuedMessageHandler queueMessageHandler)

Start an asynchronous message consumer.
Note: There can only be one DurableQueueConsumer per QueueName per DurableQueues instance
Log levels of interest:

 dk.cloudcreate.essentials.components.foundation.messaging.queue.DurableQueueConsumer
 dk.cloudcreate.essentials.components.foundation.messaging.queue.DurableQueueConsumer.MessageHandlingFailures
 

Parameters:

queueName - the name of the queue that the consumer will be listening for queued messages ready to be delivered to the QueuedMessageHandler provided

redeliveryPolicy - the redelivery policy in case the handling of a message fails

parallelConsumers - the number of parallel consumers (if number > 1 then you will effectively have competing consumers on the current node)

queueMessageHandler - the message handler that will receive QueuedMessage's. See PatternMatchingQueuedMessageHandler

Returns:

the queue consumer

consumeFromQueue

DurableQueueConsumer consumeFromQueue(ConsumeFromQueue operation)

Start an asynchronous message consumer.
Note: There can only be one DurableQueueConsumer per QueueName per DurableQueues instance
Log levels of interest:

 dk.cloudcreate.essentials.components.foundation.messaging.queue.DurableQueueConsumer
 dk.cloudcreate.essentials.components.foundation.messaging.queue.DurableQueueConsumer.MessageHandlingFailures
 

Parameters:

operation - The ConsumeFromQueue operation

Returns:

the queue consumer

queueMessage

default QueueEntryId queueMessage(QueueName queueName,
 Message message)

Queue a message for asynchronous delivery without delay to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the message is added to

message - the message

Returns:

the unique entry id for the message queued

queueMessage

QueueEntryId queueMessage(QueueMessage operation)

Queue a message for asynchronous delivery without delay to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - the QueueMessage operation

Returns:

the unique entry id for the message queued

queueMessage

default QueueEntryId queueMessage(QueueName queueName,
 Message message,
 Optional<Duration> deliveryDelay)

Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the message is added to

message - the message (Message/OrderedMessage)

deliveryDelay - Optional delay for the first delivery of the message to the DurableQueueConsumer

Returns:

the unique entry id for the message queued

See Also:

• OrderedMessage

queueMessage

default QueueEntryId queueMessage(QueueName queueName,
 Message message,
 Duration deliveryDelay)

Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the message is added to

message - the message (Message/OrderedMessage)

deliveryDelay - Optional delay for the first delivery of the message to the DurableQueueConsumer

Returns:

the unique entry id for the message queued

See Also:

• OrderedMessage

queueMessage

default QueueEntryId queueMessage(QueueName queueName,
 Message message,
 Optional<Exception> causeOfEnqueuing,
 Optional<Duration> deliveryDelay)

Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the message is added to

message - the message (Message/OrderedMessage)

causeOfEnqueuing - the optional reason for the message being queued

deliveryDelay - Optional delay for the first delivery of the message to the DurableQueueConsumer

Returns:

the unique entry id for the message queued

See Also:

• OrderedMessage

queueMessage

default QueueEntryId queueMessage(QueueName queueName,
 Message message,
 Exception causeOfEnqueuing,
 Duration deliveryDelay)

Queue a message for asynchronous delivery optional delay to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the message is added to

message - the message payload (Message/OrderedMessage)

causeOfEnqueuing - the optional reason for the message being queued

deliveryDelay - Optional delay for the first delivery of the message to the DurableQueueConsumer

Returns:

the unique entry id for the message queued

See Also:

• OrderedMessage

queueMessageAsDeadLetterMessage

default QueueEntryId queueMessageAsDeadLetterMessage(QueueName queueName,
 Message message,
 Exception causeOfError)

Queue the message directly as a Dead Letter Message. Dead Letter Messages won't be delivered to any DurableQueueConsumer
To deliver a Dead Letter Message you must first resurrect the message using resurrectDeadLetterMessage(QueueEntryId, Duration)

Parameters:

queueName - the name of the Queue the message is added to

message - the message (Message/OrderedMessage)

causeOfError - the reason for the message being queued directly as a Dead Letter Message

Returns:

the unique entry id for the message queued

See Also:

• OrderedMessage

queueMessageAsDeadLetterMessage

QueueEntryId queueMessageAsDeadLetterMessage(QueueMessageAsDeadLetterMessage operation)

Queue the message directly as a Dead Letter Message. Dead Letter Messages won't be delivered to any DurableQueueConsumer
To deliver a Dead Letter Message you must first resurrect the message using resurrectDeadLetterMessage(QueueEntryId, Duration)

Parameters:

operation - the QueueMessageAsDeadLetterMessage operation

Returns:

the unique entry id for the message queued

queueMessages

default List<QueueEntryId> queueMessages(QueueName queueName,
 List<? extends Message> messages,
 Optional<Duration> deliveryDelay)

Queue multiple messages to the same queue. All the messages will receive the same QueuedMessage.getNextDeliveryTimestamp()
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the messages will be added to

messages - the message to enqueue (Message/OrderedMessage)

deliveryDelay - optional: how long will the queue wait until it delivers the messages to the DurableQueueConsumer

Returns:

the unique entry id's for the messages queued ordered in the same order as the payloads that were queued

queueMessages

default List<QueueEntryId> queueMessages(QueueName queueName,
 List<? extends Message> messages,
 Duration deliveryDelay)

Queue multiple messages to the same queue. All the messages will receive the same QueuedMessage.getNextDeliveryTimestamp()
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the messages will be added to

messages - the messages to enqueue (Message/OrderedMessage)

deliveryDelay - optional: how long will the queue wait until it delivers the messages to the DurableQueueConsumer

Returns:

the unique entry id's for the messages queued ordered in the same order as the payloads that were queued

queueMessages

default List<QueueEntryId> queueMessages(QueueName queueName,
 List<? extends Message> messages)

Queue multiple messages to the same queue. All the messages will receive the same QueuedMessage.getNextDeliveryTimestamp()
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue the messages will be added to

messages - the message to enqueue (Message/OrderedMessage)

Returns:

the unique entry id's for the messages queued, ordered in the same order as the payloads that were queued

queueMessages

List<QueueEntryId> queueMessages(QueueMessages operation)

Queue multiple messages to the same queue. All the messages will receive the same QueuedMessage.getNextDeliveryTimestamp()
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - The QueueMessages operation

Returns:

the unique entry id's for the messages queued ordered in the same order as the payloads that were queued

retryMessage

default Optional<QueuedMessage> retryMessage(QueueEntryId queueEntryId,
 Exception causeForRetry,
 Duration deliveryDelay)

Schedule the message for redelivery after the specified deliveryDelay (called by the DurableQueueConsumer)
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueEntryId - the unique id of the message that must we will retry the delivery of

causeForRetry - the reason why the message delivery has to be retried

deliveryDelay - how long will the queue wait until it delivers the message to the DurableQueueConsumer

Returns:

the QueuedMessage message wrapped in an Optional if the operation was successful, otherwise it returns an Optional.empty()

retryMessage

Optional<QueuedMessage> retryMessage(RetryMessage operation)

Schedule the message for redelivery after the specified deliveryDelay (called by the DurableQueueConsumer)
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - the RetryMessage operation

Returns:

the QueuedMessage message wrapped in an Optional if the operation was successful, otherwise it returns an Optional.empty()

markAsDeadLetterMessage

default Optional<QueuedMessage> markAsDeadLetterMessage(QueueEntryId queueEntryId,
 Exception causeForBeingMarkedAsDeadLetter)

Mark an already Queued Message as a Dead Letter Message (or Poison Message).
Dead Letter Messages won't be delivered to any DurableQueueConsumer (called by the DurableQueueConsumer)
To deliver a Dead Letter Message you must first resurrect the message using resurrectDeadLetterMessage(QueueEntryId, Duration)
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueEntryId - the unique id of the message that must be marked as a Dead Letter Message

causeForBeingMarkedAsDeadLetter - the reason for the message being marked as a Dead Letter Message

Returns:

the QueuedMessage message wrapped in an Optional if the operation was successful, otherwise it returns an Optional.empty()

markAsDeadLetterMessage

Optional<QueuedMessage> markAsDeadLetterMessage(MarkAsDeadLetterMessage operation)

Mark an already Queued Message as a Dead Letter Message (or Poison Message).
Dead Letter Messages won't be delivered to any DurableQueueConsumer (called by the DurableQueueConsumer)
To deliver a Dead Letter Message you must first resurrect the message using resurrectDeadLetterMessage(QueueEntryId, Duration)
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - the MarkAsDeadLetterMessage operation

Returns:

the QueuedMessage message wrapped in an Optional if the operation was successful, otherwise it returns an Optional.empty()

resurrectDeadLetterMessage

default Optional<QueuedMessage> resurrectDeadLetterMessage(QueueEntryId queueEntryId,
 Duration deliveryDelay)

Resurrect a Dead Letter Message for redelivery after the specified deliveryDelay
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueEntryId - the unique id of the Dead Letter Message that must we will retry the delivery of

deliveryDelay - how long will the queue wait until it delivers the message to the DurableQueueConsumer

Returns:

the QueuedMessage message wrapped in an Optional if the operation was successful, otherwise it returns an Optional.empty()

resurrectDeadLetterMessage

Optional<QueuedMessage> resurrectDeadLetterMessage(ResurrectDeadLetterMessage operation)

Resurrect a Dead Letter Message for redelivery after the specified deliveryDelay
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - the ResurrectDeadLetterMessage operation

Returns:

the QueuedMessage message wrapped in an Optional if the operation was successful, otherwise it returns an Optional.empty()

acknowledgeMessageAsHandled

default boolean acknowledgeMessageAsHandled(QueueEntryId queueEntryId)

Mark the message as acknowledged - this operation deletes the messages from the Queue
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueEntryId - the unique id of the Message to acknowledge

Returns:

true if the operation went well, otherwise false

acknowledgeMessageAsHandled

boolean acknowledgeMessageAsHandled(AcknowledgeMessageAsHandled operation)

Mark the message as acknowledged - this operation also deletes the messages from the Queue
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - the AcknowledgeMessageAsHandled operation

Returns:

true if the operation went well, otherwise false

deleteMessage

default boolean deleteMessage(QueueEntryId queueEntryId)

Delete a message (Queued or Dead Letter Message)
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueEntryId - the unique id of the Message to delete

Returns:

true if the operation went well, otherwise false

deleteMessage

boolean deleteMessage(DeleteMessage operation)

Delete a message (Queued or Dead Letter Message)
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

operation - the DeleteMessage operation

Returns:

true if the operation went well, otherwise false

getNextMessageReadyForDelivery

default Optional<QueuedMessage> getNextMessageReadyForDelivery(QueueName queueName)

Query the next Queued Message (i.e. not including Dead Letter Messages) that's ready to be delivered to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

Parameters:

queueName - the name of the Queue where we will query for the next message ready for delivery

Returns:

the next message ready to be delivered (wrapped in an Optional) or Optional.empty() if no message is ready for delivery

getNextMessageReadyForDelivery

Optional<QueuedMessage> getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery operation)

Query the next Queued Message (i.e. not including Dead Letter Messages) that's ready to be delivered to a DurableQueueConsumer
Note this method MUST be called within an existing UnitOfWork IF using TransactionalMode.FullyTransactional

The normal message processing flow looks like this:

 durableQueues.queueMessage(queueName, message);
 var msgUnderDelivery = durableQueues.getNextMessageReadyForDelivery(queueName);
 if (msgUnderDelivery.isPresent()) {
    try {
       handleMessage(msgUnderDelivery.get());
       durableQueues.acknowledgeMessageAsHandled(msgUnderDelivery.get().getId());
    } catch (Exception e) {
       durableQueues.retryMessage(msgUnderDelivery.get().getId(),
                                  e,
                                  Duration.ofMillis(500));
    }
 }
 

When using TransactionalMode.SingleOperationTransaction then depending on the type of errors that can occur this MAY leave a dequeued message in a state of being marked as "being delivered" forever
This is why DurableQueues supporting these modes must ensure that they periodically discover messages that have been under delivery for a long time (aka. stuck messages or timed-out messages) and reset them in order for them to be redelivered.

Parameters:

operation - the GetNextMessageReadyForDelivery operation

Returns:

the next message ready to be delivered (wrapped in an Optional) or Optional.empty() if no message is ready for delivery

hasMessagesQueuedFor

boolean hasMessagesQueuedFor(QueueName queueName)

Check if there are any messages queued (i.e. not including Dead Letter Messages) for the given queue

Parameters:

queueName - the name of the Queue where we will query for queued messages

Returns:

true if there are messages queued on the given queue, otherwise false

getTotalMessagesQueuedFor

default long getTotalMessagesQueuedFor(QueueName queueName)

Get the total number of messages queued (i.e. not including Dead Letter Messages) for the given queue

Parameters:

queueName - the name of the Queue where we will query for the number of queued messages

Returns:

the number of queued messages for the given queue

getTotalMessagesQueuedFor

long getTotalMessagesQueuedFor(GetTotalMessagesQueuedFor operation)

Get the total number of messages queued (i.e. not including Dead Letter Messages) for the given queue

Parameters:

operation - the GetTotalMessagesQueuedFor operation

Returns:

the number of queued messages for the given queue

getTotalDeadLetterMessagesQueuedFor

default long getTotalDeadLetterMessagesQueuedFor(QueueName queueName)

Get the total number of dead-letter-messages/poison-messages queued for the given queue

Parameters:

queueName - the name of the Queue where we will query for the number of dead-letter-messages/poison-messages

Returns:

the number of queued messages for the given queue

getTotalDeadLetterMessagesQueuedFor

long getTotalDeadLetterMessagesQueuedFor(GetTotalDeadLetterMessagesQueuedFor operation)

Get the total number of dead-letter-messages/poison-messages queued for the given queue

Parameters:

operation - the GetTotalDeadLetterMessagesQueuedFor operation

Returns:

the number of queued messages for the given queue

getQueuedMessages

default List<QueuedMessage> getQueuedMessages(QueueName queueName,
 DurableQueues.QueueingSortOrder queueingSortOrder,
 long startIndex,
 long pageSize)

Query Queued Messages (i.e. not including any Dead Letter Messages) for the given Queue

Parameters:

queueName - the name of the Queue where we will query for queued messages

queueingSortOrder - the sort order for the QueuedMessage.getId()

startIndex - the index of the first message to include in the result (used for pagination)

pageSize - how many messages to include in the result (used for pagination)

Returns:

the messages matching the criteria

getQueuedMessages

List<QueuedMessage> getQueuedMessages(GetQueuedMessages operation)

Query Queued Messages (i.e. not including any Dead Letter Messages) for the given Queue

Parameters:

operation - the GetQueuedMessages operation

Returns:

the messages matching the criteria

getDeadLetterMessages

default List<QueuedMessage> getDeadLetterMessages(QueueName queueName,
 DurableQueues.QueueingSortOrder queueingSortOrder,
 long startIndex,
 long pageSize)

Query Dead Letter Messages (i.e. not normal Queued Messages) for the given Queue

Parameters:

queueName - the name of the Queue where we will query for Dead letter messages

queueingSortOrder - the sort order for the QueuedMessage.getId()

startIndex - the index of the first message to include in the result (used for pagination)

pageSize - how many messages to include in the result (used for pagination)

Returns:

the dead letter messages matching the criteria

getDeadLetterMessages

List<QueuedMessage> getDeadLetterMessages(GetDeadLetterMessages operation)

Query Dead Letter Messages (i.e. not normal Queued Messages) for the given Queue

Parameters:

operation - the GetDeadLetterMessages operation

Returns:

the dead letter messages matching the criteria

purgeQueue

default int purgeQueue(QueueName queueName)

Delete all messages (Queued or Dead letter Messages) in the given queue

Parameters:

queueName - the name of the Queue where all the messages will be deleted

Returns:

the number of deleted messages

purgeQueue

int purgeQueue(PurgeQueue operation)

Delete all messages (Queued or Dead letter Messages) in the given queue

Parameters:

operation - the PurgeQueue operation

Returns:

the number of deleted messages

queryForMessagesSoonReadyForDelivery

default List<NextQueuedMessage> queryForMessagesSoonReadyForDelivery(QueueName queueName,
 int maxNumberOfMessagesToReturn)

Query for the next maxNumberOfMessagesToReturn queued messages that are soon ready to be delivered using Instant.now() as withNextDeliveryTimestampAfter
This is a useful method for a custom queue consumer to know if it's necessary to call getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery)

Parameters:

queueName - the name of the queue being queried

maxNumberOfMessagesToReturn - the maximum number of messages to return

Returns:

the messages soon ready to be delivered

queryForMessagesSoonReadyForDelivery

List<NextQueuedMessage> queryForMessagesSoonReadyForDelivery(QueueName queueName,
 Instant withNextDeliveryTimestampAfter,
 int maxNumberOfMessagesToReturn)

Query for the next maxNumberOfMessagesToReturn queued messages that are soon ready to be delivered
This is a useful method for a custom queue consumer to know if it's necessary to call getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery)

Parameters:

queueName - the name of the queue being queried

withNextDeliveryTimestampAfter - return NextQueuedMessage with a NextQueuedMessage.nextDeliveryTimestamp > than this timestamp

maxNumberOfMessagesToReturn - the maximum number of messages to return

Returns:

the messages soon ready to be delivered