@SagaEventHandlermethods. Unlike regular event handlers, multiple instances of a saga may exist at any time. Sagas are managed by a single event processor (Tracking or Subscribing), which is dedicated to dealing with events for that specific saga type.
@SagaEventHandler. If a specific event signifies the start of a transaction, add another annotation to that same method:
@StartSaga. This annotation will create a new saga and invoke its event handler method when a matching event is published.
forceNewproperty on the
@EndSaga. The saga its life cycle will be ended after the invocation of the handler. Alternatively, you can call
SagaLifecycle.end()from inside the saga to end the life cycle. This allows you to conditionally end the saga.
AssociationValueconsists of a key and a value. The key represents the type of identifier used, for example "orderId" or "order". The value represents the corresponding value, "1" or "2" in the previous example.
@SagaEventHandlerannotated methods are evaluated is identical to that of
@EventHandlermethods (see Annotated event handler). A method matches if the parameters of the handler method match the incoming event, and if the saga has an association with the property defined on the handler method.
@SagaEventHandlerannotation has two attributes, of which
associationPropertyis the most important one. This is the name of the property on the incoming event that should be used to find associated sagas. The key of the association value is the name of the property. The value is the value returned by property its getter method.
String getOrderId(), which returns "123". If a method accepting this event is annotated with
@SagaEventHandler(associationProperty="orderId"), this Event is routed to all Sagas that have been associated with an
AssociationValuewith key "orderId" and value "123". This may either be exactly one, more than one, or even none at all.
@SagaEventHandlerannotation. It would then become
ResourceInjector. It is used by the
SagaRepositoryto inject resources into a saga. Axon provides a
SpringResourceInjector, which injects annotated fields and methods with resources from the Application Context. Axon also provides a
SimpleResourceInjector, which injects resources that have been registered with it into
@Injectannotated methods and fields.
TipSince resources should not be persisted with the saga, make sure to add the
transientkeyword to those fields. This will prevent the serialization mechanism to attempt to write the contents of these fields to the repository. The repository will automatically re-inject the required resources after a saga has been deserialized.
SimpleResourceInjectorallows for a pre-specified collection of resources to be injected. It scans the (setter) methods and fields of a Saga to find ones that are annotated with
ConfigurationResourceInjector. It will inject any resource available in the configuration. Components like the
CommandGatewayare available by default. You can also register your own components using
SpringResourceInjectoruses Spring's dependency injection mechanism to inject resources into a Saga. This means you can use setter injection or direct field injection if you require. The method or field to be injected needs to be annotated in order for Spring to recognize it as a dependency, for example with
AnnotatedSagaManager, which is provided to an Event Processor to perform the actual invocation of handlers. It is initialized using the type of the Saga to manage, as well as a
SagaRepositorywhere Sagas of that type can be stored and retrieved. A single
AnnotatedSagaManagercan only manage a single Saga type.
SagaRepositoryis responsible for storing and retrieving sagas, for use by the
SagaManager. It is capable of retrieving specific saga instances by their identifier as well as by their association values.
AnnotatedSagaRepositoryimplementation, which allows the lookup of saga instances while guaranteeing that only a single instance of the saga may be accessed at the same time. It uses a
SagaStoreto perform the actual persistence of saga instances.
CachingSagaStorewhich wraps another implementation to add caching behavior. Note that the
CachingSagaStoreis a write-through cache, which means save operations are always immediately forwarded to the backing Store, to ensure data safety.
JpaSagaStoreuses JPA to store the state and association values of sagas. Sagas themselves do not need any JPA annotations; Axon will serialize the sagas using a
Serializer(similar to event serialization, you can choose between an
JacksonSerializer, which can be set by configuring the default
Serializerin your application. For more details, see Serializers.
JpaSagaStoreis configured with an
EntityManagerProvider, which provides access to an
EntityManagerinstance to use. This abstraction allows for the use of both application managed and container managed
EntityManagers. Optionally, you can define the serializer to serialize the Saga instances with. Axon defaults to the
JdbcSagaStoreuses plain JDBC to store stage instances and their association values. Similar to the
JpaSagaStore, saga instances do not need to be aware of how they are stored. They are serialized using a serializer.
JdbcSagaStoreis initialized with either a
ConnectionProvider. While not required, when initializing with a
ConnectionProvider, it is recommended to wrap the implementation in a
UnitOfWorkAwareConnectionProviderWrapper. It will check the current Unit of Work for an already open database connection, to ensure that all activity within a unit of work is done on a single connection.
JdbcSagaRepositoryuses plain SQL statements to store and retrieve information. This may mean that some operations depend on the database specific SQL dialect. It may also be the case that certain database vendors provide non-standard features that you would like to use. To allow for this, you can provide your own
SagaSqlSchemais an interface that defines all the operations the repository needs to perform on the underlying database. It allows you to customize the SQL statement executed for each operation. The default is the
GenericSagaSqlSchema. Other implementations available are
MongoSagaStorestores the saga instances and their associations in a MongoDB database. The
MongoSagaStorestores all sagas in a single collection in a MongoDB database. For each saga instance, a single document is created.
MongoSagaStorealso ensures that at any time, only a single Saga instance exists for any unique Saga in a single JVM. This ensures that no state changes are lost due to concurrency issues.
MongoSagaStoreis initialized using a
MongoTemplateand optionally a
MongoTemplateprovides a reference to the collection to store the sagas in. Axon provides the
DefaultMongoTemplate, which takes a
MongoClientinstance as well as the database name and name of the collection to store the sagas in. The database name and collection name may be omitted. In that case, they default to
CachingSagaStoreimplementation. It is a
SagaStorethat wraps another one, which does the actual storage. When loading sagas or association values, the
CachingSagaStorewill first consult its caches, before delegating to the wrapped repository. When storing information, all calls are always delegated to ensure that the backing storage always has a consistent view on the saga's state.
CachingSagaStore. The constructor of the
CachingSagaStoretakes three parameters: 1. The
SagaStoreto wrap 2. The cache to use for association values 3. The cache to use for saga instances
Default Saga Processor nameWith a Saga called
MySaga, that would mean the processor is called
SagaConfigurerto construct the Saga, Saga Manager, Saga Repository and Saga Store. A default configuration for a Saga called
MySagawould look as follows:
@Sagato auto-configure it:
SagaStoreto use. The
SagaStorerepresents the mechanism that 'physically' stores the Saga instances, for which it uses the
AnnotatedSagaRepository(the default) to store and retrieve Saga instances. If no
SagaStoreis configured Axon defaults an
InMemorySagaStore, thus not persisting the Saga on shutdown. To configure a
MySagaconsider the following snippet:
SagaConfigurershould be used through the
JdbcSagaStorerespectively. To provide a custom
SagaStore, providing a bean to the application context and defining the bean name on the