Module dk.cloudcreate.essentials.components.foundation

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

Enum TransactionalMode

java.lang.Object

java.lang.Enum<TransactionalMode>

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

All Implemented Interfaces:

Serializable, Comparable<TransactionalMode>

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.

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 type with the specified name.
static TransactionalMode[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

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

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

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 Detail

values

public static TransactionalMode[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (TransactionalMode c : TransactionalMode.values())
    System.out.println(c);

Returns:

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

valueOf

public static TransactionalMode valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type has no constant with the specified name

NullPointerException - if the argument is null