Package org.axonframework.messaging.unitofwork

Interface UnitOfWork<T extends Message<?>>

All Known Implementing Classes:
AbstractUnitOfWork, BatchingUnitOfWork, CommandHandlingEntry, DefaultUnitOfWork, DisruptorUnitOfWork
public interface UnitOfWork<T extends Message<?>>
This class represents a Unit of Work that monitors the processing of a Message.

Before processing begins a Unit of Work is bound to the active thread by registering it with the CurrentUnitOfWork. After processing, the Unit of Work is deregistered from the CurrentUnitOfWork.

Handlers can be notified about the state of the processing of the Message by registering with this Unit of Work.

Since:
0.6
Author:
Allard Buijze

  • Method Details

    • start

      void start()
      Starts the current unit of work. The UnitOfWork instance is registered with the CurrentUnitOfWork.

    • commit

      void commit()
      Commits the Unit of Work. This should be invoked after the Unit of Work Message has been processed. Handlers registered to the Unit of Work will be notified.

      After the commit (successful or not), any registered clean-up handlers (onCleanup(Consumer)}) will be invoked and the Unit of Work is deregistered from the CurrentUnitOfWork.

      If the Unit of Work fails to commit, e.g. because an exception is raised by one of its handlers, the Unit of Work is rolled back.

      Throws:
      IllegalStateException - if the UnitOfWork wasn't started or if the Unit of Work is not the 'current' Unit of Work returned by CurrentUnitOfWork.get().

    • rollback

      default void rollback()
      Initiates the rollback of this Unit of Work, invoking all registered rollback (and clean-up handlers #onCleanup(Consumer) respectively. Finally, the Unit of Work is deregistered from the CurrentUnitOfWork.

      If the rollback is a result of an exception, consider using rollback(Throwable) instead.

      Throws:
      IllegalStateException - if the Unit of Work is not in a compatible phase.

    • rollback

      void rollback(Throwable cause)
      Initiates the rollback of this Unit of Work, invoking all registered rollback (and clean-up handlers #onCleanup(Consumer) respectively. Finally, the Unit of Work is deregistered from the CurrentUnitOfWork.
      Parameters:
      cause - The cause of the rollback. May be null.
      Throws:
      IllegalStateException - if the Unit of Work is not in a compatible phase.

    • isActive

      default boolean isActive()
      Indicates whether this UnitOfWork is started. It is started when the start() method has been called, and if the UnitOfWork has not been committed or rolled back.
      Returns:
      true if this UnitOfWork is started, false otherwise.

    • phase

      UnitOfWork.Phase phase()
      Returns the current phase of the Unit of Work.
      Returns:
      the Unit of Work phase

    • onPrepareCommit

      void onPrepareCommit(Consumer<UnitOfWork<T>> handler)
      Register given handler with the Unit of Work. The handler will be notified when the phase of the Unit of Work changes to UnitOfWork.Phase.PREPARE_COMMIT.
      Parameters:
      handler - the handler to register with the Unit of Work

    • onCommit

      void onCommit(Consumer<UnitOfWork<T>> handler)
      Register given handler with the Unit of Work. The handler will be notified when the phase of the Unit of Work changes to UnitOfWork.Phase.COMMIT.
      Parameters:
      handler - the handler to register with the Unit of Work

    • afterCommit

      void afterCommit(Consumer<UnitOfWork<T>> handler)
      Register given handler with the Unit of Work. The handler will be notified when the phase of the Unit of Work changes to UnitOfWork.Phase.AFTER_COMMIT.
      Parameters:
      handler - the handler to register with the Unit of Work

    • onRollback

      void onRollback(Consumer<UnitOfWork<T>> handler)
      Register given handler with the Unit of Work. The handler will be notified when the phase of the Unit of Work changes to UnitOfWork.Phase.ROLLBACK. On rollback, the cause for the rollback can obtained from the supplied
      Parameters:
      handler - the handler to register with the Unit of Work

    • onCleanup

      void onCleanup(Consumer<UnitOfWork<T>> handler)
      Register given handler with the Unit of Work. The handler will be notified when the phase of the Unit of Work changes to UnitOfWork.Phase.CLEANUP.
      Parameters:
      handler - the handler to register with the Unit of Work

    • parent

      Optional<UnitOfWork<?>> parent()
      Returns an optional for the parent of this Unit of Work. The optional holds the Unit of Work that was active when this Unit of Work was started. In case no other Unit of Work was active when this Unit of Work was started the optional is empty, indicating that this is the Unit of Work root.
      Returns:
      an optional parent Unit of Work

    • isRoot

      default boolean isRoot()
      Check that returns true if this Unit of Work has not got a parent.
      Returns:
      true if this Unit of Work has no parent

    • root

      default UnitOfWork<?> root()
      Returns the root of this Unit of Work. If this Unit of Work has no parent (see parent()) it returns itself, otherwise it returns the root of its parent.
      Returns:
      the root of this Unit of Work

    • getMessage

      T getMessage()
      Get the message that is being processed by the Unit of Work. A Unit of Work processes a single Message over its life cycle.
      Returns:
      the Message being processed by this Unit of Work

    • transformMessage

      UnitOfWork<T> transformMessage(Function<T,? extends Message<?>> transformOperator)
      Transform the Message being processed using the given operator and stores the result.

      Implementations should take caution not to change the message type to a type incompatible with the current Unit of Work. For example, do not return a CommandMessage when transforming an EventMessage.

      Parameters:
      transformOperator - The transform operator to apply to the stored message
      Returns:
      this Unit of Work

    • getCorrelationData

      MetaData getCorrelationData()
      Get the correlation data contained in the message being processed by the Unit of Work.

      By default this correlation data will be copied to other messages created in the context of this Unit of Work, so long as these messages extend from GenericMessage.

      Returns:
      The correlation data contained in the message processed by this Unit of Work

    • registerCorrelationDataProvider

      void registerCorrelationDataProvider(CorrelationDataProvider correlationDataProvider)
      Register given correlationDataProvider with this Unit of Work. Correlation data providers are used to provide meta data based on this Unit of Work's Message when getCorrelationData() is invoked.
      Parameters:
      correlationDataProvider - the Correlation Data Provider to register

    • resources

      Map<String,Object> resources()
      Returns a mutable map of resources registered with the Unit of Work.
      Returns:
      mapping of resources registered with this Unit of Work

    • getResource

      default <R> R getResource(String name)
      Returns the resource attached under given name, or null if no such resource is available.
      Type Parameters:
      R - The type of resource
      Parameters:
      name - The name under which the resource was attached
      Returns:
      The resource mapped to the given name, or null if no resource was found.

    • getOrComputeResource

      default <R> R getOrComputeResource(String key, Function<? super String,R> mappingFunction)
      Returns the resource attached under given name. If there is no resource mapped to the given key yet the mappingFunction is invoked to provide the mapping.
      Type Parameters:
      R - The type of resource
      Parameters:
      key - The name under which the resource was attached
      mappingFunction - The function that provides the mapping if there is no mapped resource yet
      Returns:
      The resource mapped to the given key, or the resource returned by the mappingFunction if no resource was found.

    • getOrDefaultResource

      default <R> R getOrDefaultResource(String key, R defaultValue)
      Returns the resource attached under given name. If there is no resource mapped to the given key, the defaultValue is returned.
      Type Parameters:
      R - The type of resource
      Parameters:
      key - The name under which the resource was attached
      defaultValue - The value to return if no mapping is available
      Returns:
      The resource mapped to the given key, or the resource returned by the mappingFunction if no resource was found.

    • attachTransaction

      default void attachTransaction(TransactionManager transactionManager)
      Attach a transaction to this Unit of Work, using the given transactionManager. The transaction will be managed in the lifecycle of this Unit of Work. Failure to start a transaction will cause this Unit of Work to be rolled back.
      Parameters:
      transactionManager - The Transaction Manager to create, commit and/or rollback the transaction

    • execute

      default void execute(Runnable task)
      Execute the given task in the context of this Unit of Work. If the Unit of Work is not started yet it will be started.

      If the task executes successfully the Unit of Work is committed. If any exception is raised while executing the task, the Unit of Work is rolled back and the exception is thrown.

      Parameters:
      task - the task to execute

    • execute

      default void execute(Runnable task, RollbackConfiguration rollbackConfiguration)
      Execute the given task in the context of this Unit of Work. If the Unit of Work is not started yet it will be started.

      If the task executes successfully the Unit of Work is committed. If an exception is raised while executing the task, the rollbackConfiguration determines if the Unit of Work should be rolled back or committed, and the exception is thrown.

      Parameters:
      task - the task to execute
      rollbackConfiguration - configuration that determines whether or not to rollback the unit of work when task execution fails

    • executeWithResult

      default <R> ResultMessage<R> executeWithResult(Callable<R> task)
      Execute the given task in the context of this Unit of Work. If the Unit of Work is not started yet it will be started.

      If the task executes successfully the Unit of Work is committed and the result of the task is returned. If any exception is raised while executing the task, the Unit of Work is rolled back and the exception is thrown.

      Type Parameters:
      R - the type of result that is returned after successful execution
      Parameters:
      task - the task to execute
      Returns:
      The result of the task wrapped in Result Message

    • executeWithResult

      <R> ResultMessage<R> executeWithResult(Callable<R> task, @Nonnull RollbackConfiguration rollbackConfiguration)
      Execute the given task in the context of this Unit of Work. If the Unit of Work is not started yet it will be started.

      If the task executes successfully the Unit of Work is committed and the result of the task is returned. If execution fails, the rollbackConfiguration determines if the Unit of Work should be rolled back or committed.

      Type Parameters:
      R - the type of result that is returned after successful execution
      Parameters:
      task - the task to execute
      rollbackConfiguration - configuration that determines whether or not to rollback the unit of work when task execution fails
      Returns:
      The result of the task wrapped in Result Message

    • getExecutionResult

      ExecutionResult getExecutionResult()
      Get the result of the task that was executed by this Unit of Work. If the Unit of Work has not been given a task to execute this method returns null.

      Note that the value of the returned ExecutionResult's ExecutionResult.isExceptionResult() does not determine whether or not the UnitOfWork has been rolled back. To check whether or not the UnitOfWork was rolled back check isRolledBack().

      Returns:
      The result of the task executed by this Unit of Work, or null if the Unit of Work has not been given a task to execute.

    • isRolledBack

      boolean isRolledBack()
      Check if the Unit of Work has been rolled back.
      Returns:
      true if the unit of work was rolled back, false otherwise.

    • isCurrent

      default boolean isCurrent()
      Check if the Unit of Work is the 'currently' active Unit of Work returned by CurrentUnitOfWork.get().
      Returns:
      true if the Unit of Work is the currently active Unit of Work