Package org.axonframework.modelling.saga

Interface Saga<T>

All Superinterfaces:
DescribableComponent, EventHandler, EventHandlingComponent, MessageHandler, ReplayStatusChangedHandler, ResetHandler
All Known Implementing Classes:
AnnotatedSaga
public interface Saga<T> extends EventHandlingComponent
Interface describing an implementation of a Saga. Sagas are instances that handle events and may possibly produce new commands or have other side effects. Typically, Sagas are used to manage long running business transactions.

Multiple instances of a single type of Saga may exist. In that case, each Saga will be managing a different transaction. Sagas need to be associated with concepts in order to receive specific events. These associations are managed through AssociationValues. For example, to associate a saga with an Order with ID 1234, this saga needs an association value with key "orderId" and value "1234".

Since:
0.7
Author:
Allard Buijze

  • Method Details

    • getSagaIdentifier

      String getSagaIdentifier()
      Returns the unique identifier of this saga.
      Returns:
      the unique identifier of this saga

    • getAssociationValues

      AssociationValues getAssociationValues()
      Returns a view on the Association Values for this saga instance. The returned instance is mutable.
      Returns:
      a view on the Association Values for this saga instance

    • invoke

      <R> R invoke(Function<T,R> invocation)
      Execute the given invocation against the root object of this Saga instance.
      Type Parameters:
      R - The type of return value expected
      Parameters:
      invocation - the function to invoke. The root object of the Saga is input to the function, the result is the result of the execution.
      Returns:
      The result of the invocation on the Saga.

    • execute

      void execute(Consumer<T> invocation)
      Execute the given invocation against the root object of this Saga instance.
      Parameters:
      invocation - the function to invoke. The root object of the Saga is input to the function.

    • isActive

      boolean isActive()
      Indicates whether or not this saga is active. A Saga is active when its life cycle has not been ended.
      Returns:
      true if this saga is active, false otherwise.

    • canHandle

      boolean canHandle(EventMessage event, ProcessingContext context)
      Indicates whether this saga instance takes the given event, which is the case when it is active and holds the AssociationValue that one of its handlers for this event resolves from it.

      This answers a different question than EventHandlingComponent.supports(org.axonframework.messaging.core.QualifiedName), which reports the events the saga type declares handlers for. Two saga instances of the same type therefore disagree here whenever they are associated with different values, and the component managing them needs that answer: a Saga that declines the event has not taken it, so a SagaCreationPolicy.IF_NONE_FOUND policy must still start a new instance. The returned MessageStream cannot express it, since a Saga that declines and a Saga that handled the event without producing anything both yield an empty stream.

      In Axon Framework 4 this method was inherited from MessageHandler, which Axon Framework 5 reduced to a marker interface, so the declaration lives here instead.

      Parameters:
      event - the event to check this saga instance against
      context - the ProcessingContext in which the event is being processed
      Returns:
      true when this saga instance takes the given event, false otherwise

    • sequenceIdentifierFor

      default Object sequenceIdentifierFor(EventMessage event, ProcessingContext context)
      Returns the sequence identifier for the given event. When two events have the same sequence identifier (as defined by their equals method), they will be executed sequentially. Important: All EventHandlers for the same QualifiedName within a single EventHandlingComponent must return the same sequence identifier for a given event. Mixing different sequence identifiers within the scope of a single EventHandlingComponent is not supported and may lead to undefined behavior.

      A single Saga instance never determines its own sequencing, as the component managing the sagas is in charge of the sequencing Hence, this method throws an UnsupportedOperationException whenever invoked.

      Specified by:
      sequenceIdentifierFor in interface EventHandlingComponent
      Parameters:
      event - The event for which to get the sequencing identifier.
      context - The processing context in which the event is being handled.
      Returns:
      A sequence identifier for the given event.
      Throws:
      UnsupportedOperationException - since sequencing is dictated by the component managing the sagas, not the saga itself

    • supportsReset

      default boolean supportsReset()
      Description copied from interface: EventHandlingComponent
      Indicates whether this component supports reset operations.

      When true, this component can participate in replay operations and its EventHandlingComponent.handle(ResetContext, ProcessingContext) method will be called before replay begins.

      By default, reset is supported.

      Specified by:
      supportsReset in interface EventHandlingComponent
      Returns:
      true if this component supports reset operations, false otherwise.

    • handle

      default MessageStream.Empty<Message> handle(ResetContext resetContext, ProcessingContext context)
      Description copied from interface: ResetHandler
      Handles the given ResetContext message, performing any necessary reset operations.

      This method is invoked before the processor begins replaying events. Handlers typically use this opportunity to clean up state that will be rebuilt during replay.

      If this method completes exceptionally, the reset operation will be aborted and no replay will occur.

      Specified by:
      handle in interface EventHandlingComponent
      Specified by:
      handle in interface ResetHandler
      Parameters:
      resetContext - The reset context message containing reset information and optional payload.
      context - The processing context for this operation.
      Returns:
      An empty message stream after handling completes successfully.