Module dk.cloudcreate.essentials.components.foundation
Package dk.cloudcreate.essentials.components.foundation.messaging.eip.store_and_forward

Interface Outbox

All Known Implementing Classes:
Outboxes.DurableQueueBasedOutboxes.DurableQueueBasedOutbox
public interface Outbox
The Outbox supports the transactional Store and Forward pattern from Enterprise Integration Patterns supporting At-Least-Once delivery guarantee.
The Outbox pattern is used to handle outgoing messages, that are created as a side effect of adding/updating an entity in a database, but where the message infrastructure (such as a Queue, Kafka, EventBus, etc.) that doesn't share the same underlying transactional resource as the database.
Instead, you need to use an Outbox that can join in the same UnitOfWork/transactional-resource that the database is using.
The message is added to the Outbox in a transaction/UnitOfWork and afterwards the UnitOfWork is committed.
If the transaction fails then both the entity and the message will be rolled back when then UnitOfWork rolls back.
After the UnitOfWork has been committed, the messages will be asynchronously delivered to the message consumer in a new UnitOfWork.
The Outbox itself supports Message Redelivery in case the Message consumer experiences failures.
This means that the Message consumer, registered with the Outbox, can and will receive Messages more than once and therefore its message handling has to be idempotent.

If you're working with OrderedMessage's then the Outbox consumer must be configured with OutboxConfig.getMessageConsumptionMode() having value MessageConsumptionMode.SingleGlobalConsumer in order to be able to guarantee that OrderedMessage's are delivered in OrderedMessage.getOrder() per OrderedMessage.getKey() across as many OutboxConfig.numberOfParallelMessageConsumers as you wish to use.

  • Method Summary

    Modifier and Type
    Method
    Description
    Outbox
    consume(Consumer<Message> messageConsumer)
    Start consuming messages from the Outbox using the provided message consumer.
    This is the same as calling setMessageConsumer(Consumer) followed by startConsuming()
    Only needs to be called if the instance was created without a message consumer such as via Outboxes.getOrCreateOutbox(OutboxConfig)
    void
    deleteAllMessages()
    Delete all messages (Queued or Dead letter Messages) in the underlying storage (such as a Queue)
    long
    getNumberOfOutgoingMessages()
    Get the number of message in the outbox that haven't been sent yet
    boolean
    hasAMessageConsumer()
    Has the instance been created with a Message consumer or has consume(Consumer) been called
    boolean
    isConsumingMessages()
    Is the provided Message consumer consuming messages from the Outbox
    OutboxName
    name()
    The name of the outbox
    Outbox
    sendMessage(Message message)
    Send a message asynchronously.
    This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The message will be delivered asynchronously to the message consumer
    Outbox
    sendMessage(Message message, Duration deliveryDelay)
    Send a message asynchronously and where the message should be delivered later.
    This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The message will be delivered asynchronously to the message consumer
    default Outbox
    sendMessage(Object payload)
    Send a message (without meta-data) asynchronously.
    This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The message will be delivered asynchronously to the message consumer
    default Outbox
    sendMessage(Object payload, MessageMetaData metaData)
    Send a message (with meta-data) asynchronously.
    This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The message will be delivered asynchronously to the message consumer
    default Outbox
    sendMessage(Object payload, MessageMetaData metaData, Duration deliveryDelay)
    Send a message (with meta-data) asynchronously and where the message should be delivered later.
    This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The message will be delivered asynchronously to the message consumer
    default Outbox
    sendMessage(Object payload, Duration deliveryDelay)
    Send a message (without meta-data) asynchronously and where the message should be delivered later.
    This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The message will be delivered asynchronously to the message consumer
    default Outbox
    sendMessageList(List<? extends Object> payloads)
    Send a list of message payloads.
    default Outbox
    sendMessageList(List<? extends Object> payloads, Duration deliveryDelay)
    Send a list of message payloads with delayed delivery.
    Outbox
    sendMessages(List<Message> messages)
    Send a list of messages
    These messages will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The messages will be delivered asynchronously to the message consumer
    Outbox
    sendMessages(List<Message> messages, Duration deliveryDelay)
    Send a list of messages with delayed delivery
    These messages will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
    The messages will be delivered asynchronously to the message consumer
    Outbox
    setMessageConsumer(Consumer<Message> messageConsumer)
    Set the message consumer.
    Outbox
    startConsuming()
    Start consuming messages from the Outbox.
    Outbox
    stopConsuming()
    Stop consuming messages from the Outbox.

  • Method Details

    • consume

      Outbox consume(Consumer<Message> messageConsumer)
      Start consuming messages from the Outbox using the provided message consumer.
      This is the same as calling setMessageConsumer(Consumer) followed by startConsuming()
      Only needs to be called if the instance was created without a message consumer such as via Outboxes.getOrCreateOutbox(OutboxConfig)

      If an OrderedMessage is delivered via an Outbox using a FencedLock (such as the Outboxes.durableQueueBasedOutboxes(DurableQueues, FencedLockManager)) to coordinate message consumption, then you can find the FencedLock.getCurrentToken() of the consumer in the Message.getMetaData() under key MessageMetaData.FENCED_LOCK_TOKEN

      Parameters:
      messageConsumer - the message consumer. See PatternMatchingMessageHandler
      Returns:
      this outbox instance

    • setMessageConsumer

      Outbox setMessageConsumer(Consumer<Message> messageConsumer)
      Set the message consumer. To start consuming call startConsuming()
      Parameters:
      messageConsumer - the message consumer. See PatternMatchingMessageHandler
      Returns:
      this outbox instance

    • startConsuming

      Outbox startConsuming()
      Start consuming messages from the Outbox. Requires calling setMessageConsumer(Consumer) first
      If an OrderedMessage is delivered via an Outbox using a FencedLock (such as Outboxes.durableQueueBasedOutboxes(DurableQueues, FencedLockManager) to coordinate message consumption, then you can find the FencedLock.getCurrentToken() of the consumer in the Message.getMetaData() under key MessageMetaData.FENCED_LOCK_TOKEN
      Returns:
      this outbox instance

    • stopConsuming

      Outbox stopConsuming()
      Stop consuming messages from the Outbox. Calling this method will remove the message consumer and to resume message consumption you need to call consume(Consumer)
      Returns:
      this outbox instance

    • hasAMessageConsumer

      boolean hasAMessageConsumer()
      Has the instance been created with a Message consumer or has consume(Consumer) been called
      Returns:
      Has the instance been created with a Message consumer or has consume(Consumer) been called

    • isConsumingMessages

      boolean isConsumingMessages()
      Is the provided Message consumer consuming messages from the Outbox
      Returns:
      Is the provided Message consumer consuming messages from the Outbox

    • name

      OutboxName name()
      The name of the outbox
      Returns:
      the name of the outbox

    • deleteAllMessages

      void deleteAllMessages()
      Delete all messages (Queued or Dead letter Messages) in the underlying storage (such as a Queue)

    • sendMessage

      default Outbox sendMessage(Object payload)
      Send a message (without meta-data) asynchronously.
      This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The message will be delivered asynchronously to the message consumer
      Parameters:
      payload - the message payload
      Returns:
      this outbox instance

    • sendMessage

      default Outbox sendMessage(Object payload, Duration deliveryDelay)
      Send a message (without meta-data) asynchronously and where the message should be delivered later.
      This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The message will be delivered asynchronously to the message consumer
      Parameters:
      payload - the message payload
      deliveryDelay - duration before the message should be delivered
      Returns:
      this outbox instance

    • sendMessage

      default Outbox sendMessage(Object payload, MessageMetaData metaData)
      Send a message (with meta-data) asynchronously.
      This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The message will be delivered asynchronously to the message consumer
      Parameters:
      payload - the message payload
      metaData - the message meta-data
      Returns:
      this outbox instance

    • sendMessage

      default Outbox sendMessage(Object payload, MessageMetaData metaData, Duration deliveryDelay)
      Send a message (with meta-data) asynchronously and where the message should be delivered later.
      This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The message will be delivered asynchronously to the message consumer
      Parameters:
      payload - the message payload
      metaData - the message meta-data
      deliveryDelay - duration before the message should be delivered
      Returns:
      this outbox instance

    • sendMessageList

      default Outbox sendMessageList(List<? extends Object> payloads)
      Send a list of message payloads. The payloads will be converted to Message's
      These messages will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The messages will be delivered asynchronously to the message consumer
      Parameters:
      payloads - the list of message payloads
      Returns:
      this outbox instance

    • sendMessageList

      default Outbox sendMessageList(List<? extends Object> payloads, Duration deliveryDelay)
      Send a list of message payloads with delayed delivery. The payloads will be converted to Message's
      These messages will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The messages will be delivered asynchronously to the message consumer
      Parameters:
      payloads - the list of message payloads
      Returns:
      this outbox instance

    • sendMessages

      Outbox sendMessages(List<Message> messages)
      Send a list of messages
      These messages will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The messages will be delivered asynchronously to the message consumer
      Parameters:
      messages - the list of messages
      Returns:
      this outbox instance
      See Also:

    • sendMessages

      Outbox sendMessages(List<Message> messages, Duration deliveryDelay)
      Send a list of messages with delayed delivery
      These messages will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The messages will be delivered asynchronously to the message consumer
      Parameters:
      messages - the list of messages
      deliveryDelay - duration before the messages should be delivered
      Returns:
      this outbox instance
      See Also:

    • sendMessage

      Outbox sendMessage(Message message)
      Send a message asynchronously.
      This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The message will be delivered asynchronously to the message consumer
      Parameters:
      message - the message
      Returns:
      this outbox instance
      See Also:

    • sendMessage

      Outbox sendMessage(Message message, Duration deliveryDelay)
      Send a message asynchronously and where the message should be delivered later.
      This message will be stored durably (without any duplication check) in connection with the currently active UnitOfWork (or a new UnitOfWork will be created in case there isn't an active UnitOfWork).
      The message will be delivered asynchronously to the message consumer
      Parameters:
      message - the message
      deliveryDelay - duration before the message should be delivered
      Returns:
      this outbox instance
      See Also:

    • getNumberOfOutgoingMessages

      long getNumberOfOutgoingMessages()
      Get the number of message in the outbox that haven't been sent yet
      Returns:
      Get the number of message in the outbox that haven't been sent yet