Module dk.cloudcreate.essentials.components.foundation

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

Enum Class TransactionalMode

java.lang.Object

java.lang.Enum<TransactionalMode>

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

All Implemented Interfaces:

Serializable, Comparable<TransactionalMode>, Constable

public enum TransactionalMode
extends Enum<TransactionalMode>

The transactional behaviour mode of a DurableQueues. The recommended value is SingleOperationTransaction (see the description)

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

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
FullyTransactional	When using this mode all the queueing, de-queueing methods requires an existing UnitOfWork started prior to being called.
SingleOperationTransaction	Useful for long-running message handling, you can choose to configure the DurableQueues to only require single operation (such as DurableQueues.getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery) , DurableQueues.deleteMessage(DeleteMessage) , etc.) as well as for certain NoSQL databases, such as MongoDB/DocumentDB, that have limitations when performing multiple data storage operations within a transaction. For these cases you can configure the TransactionalMode as SingleOperationTransaction where queueing and de-queueing are performed using separate (single document) transactions and where acknowledging/retry is performed as a separate transaction. During queueing if there is an existing UnitOfWork in progress, then the queue operation will join the existing UnitOfWork The advantage of this transactional mode is that any explicit UnitOfWork.markAsRollbackOnly()/UnitOfWork.markAsRollbackOnly(Exception), either directly our through e.g.

Method Summary

Modifier and Type	Method	Description
static TransactionalMode	valueOf(String name)	Returns the enum constant of this class with the specified name.
static TransactionalMode[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

FullyTransactional

public static final TransactionalMode FullyTransactional

When using this mode all the queueing, de-queueing methods requires an existing UnitOfWork started prior to being called. The reason for this is that Queues are typically used together with the Inbox Outbox pattern, which benefits from including queueing/de-queueing together with other database entity modifying operations.
When changing an entity and queueing/de-queueing happens in ONE shared transaction (NOTE this requires that the entity storage and the queue storage to use the same database - e.g. Postgresql or MongoDB) then the shared database transaction guarantees that all the data storage operations are committed or rollback as one
The disadvantage of this is that any explicit UnitOfWork.markAsRollbackOnly()/UnitOfWork.markAsRollbackOnly(Exception), either directly our through e.g. UnitOfWorkControllingCommandBusInterceptor, will cause the message handling to rollback and the message will retry indefinitely without any delay (i.e. the RedeliveryPolicy is ignored because message handling is rolledback)

SingleOperationTransaction

public static final TransactionalMode SingleOperationTransaction

Useful for long-running message handling, you can choose to configure the DurableQueues to only require single operation (such as DurableQueues.getNextMessageReadyForDelivery(GetNextMessageReadyForDelivery) , DurableQueues.deleteMessage(DeleteMessage) , etc.) as well as for certain NoSQL databases, such as MongoDB/DocumentDB, that have limitations when performing multiple data storage operations within a transaction.
For these cases you can configure the TransactionalMode as SingleOperationTransaction where queueing and de-queueing are performed using separate (single document) transactions and where acknowledging/retry is performed as a separate transaction.
During queueing if there is an existing UnitOfWork in progress, then the queue operation will join the existing UnitOfWork
The advantage of this transactional mode is that any explicit UnitOfWork.markAsRollbackOnly()/UnitOfWork.markAsRollbackOnly(Exception), either directly our through e.g. UnitOfWorkControllingCommandBusInterceptor, will NOT cause any message handling rollback, instead the normal RedeliveryPolicy will take effect as expected.

Method Details

values

public static TransactionalMode[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static TransactionalMode valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null