Message
interface, there is a clear distinction between the different types of Messages and how they are treated.NoteNote that all Messages are immutable. Storing data in a Message actually means creating a new Message based on the previous one, with extra information added to it. This guarantees that Messages are safe to use in a multi-threaded and distributed environment.
CommandMessage
implementations.EventMessage
. The actual type of Message used depends on the origin of the Event. When an Event is raised by an Aggregate, it is wrapped in a DomainEventMessage
(which extends EventMessage
). All other Events are wrapped in an EventMessage.
Aside from common Message
attributes like a unique Identifier an EventMessage
also contains a timestamp. The DomainEventMessage
additionally contains the type and identifier of the aggregate that raised the Event. It also contains the sequence number of the event in the aggregate's event stream, which allows the order of events to be reproduced.NoteEven though theDomainEventMessage
contains a reference to the Aggregate Identifier, you should always include the identifier in the actual Event itself as well. The identifier in the DomainEventMessage is used by the EventStore to store events and may not always provide a reliable value for other purposes.
NoteIn general, you should not base business decisions on information in the meta-data of event messages. If that is the case, you might have information attached that should really be part of the Event itself instead. Meta-data is typically used for reporting, auditing and tracing.
NoteAlthough Domain Events technically indicate a state change, you should try to capture the intention of the state in the event, too. A good practice is to use an abstract implementation of a domain event to capture the fact that certain state has changed, and use a concrete sub-implementation of that abstract class that indicates the intention of the change. For example, you could have an abstractAddressChangedEvent
, and two implementationsContactMovedEvent
andAddressCorrectedEvent
that capture the intent of the state change. Some listeners don't care about the intent (e.g. database updating event listeners). These will listen to the abstract type. Other listeners do care about the intent and these will listen to the concrete subtypes (e.g. to send an address change confirmation email to the customer).​​
GenericEventMessage
is an implementation that allows you to wrap your Event in a Message. You can use the constructor, or the static asEventMessage()
method. The latter checks whether the given parameter doesn't already implement the Message
interface. If so, it is either returned directly (if it implements EventMessage
,) or it returns a new GenericEventMessage
using the given Message
's payload and Meta Data. If an Event is applied (published) by an Aggregate Axon will automatically wrap the Event in a DomainEventMessage
containing the Aggregate's Identifier, Type and Sequence Number.UnitOfWork
to your annotated method. In other locations, you can retrieve the Unit of Work bound to the current thread by calling CurrentUnitOfWork.get()
. Note that this method will throw an exception if there is no Unit of Work bound to the current thread. Use CurrentUnitOfWork.isStarted()
to find out if one is available.unitOfWork.getOrComputeResource()
and the lifecycle callback methods, such as onRollback()
, afterCommit()
and onCleanup()
allow you to register resources and declare actions to be taken during the processing of this Unit of Work.NoteNote that the Unit of Work is merely a buffer of changes, not a replacement for Transactions. Although all staged changes are only committed when the Unit of Work is committed, its commit is not atomic. That means that when a commit fails, some changes might have been persisted, while others are not. Best practices dictate that a Command should never contain more than one action. If you stick to that practice, a Unit of Work will contain a single action, making it safe to use as-is. If you have more actions in your Unit of Work, then you could consider attaching a transaction to the Unit of Work's commit. UseunitOfWork.onCommit(..)
to register actions that need to be taken when the Unit of Work is being committed.
RollbackConfigurationType.NEVER
, will always commit the Unit of Work,RollbackConfigurationType.ANY_THROWABLE
, will always roll back when an exception occurs,RollbackConfigurationType.UNCHECKED_EXCEPTIONS
, will roll back on Errors and Runtime ExceptionRollbackConfigurationType.RUNTIME_EXCEPTION
, will roll back on Runtime Exceptions (but not on Errors)DefaultUnitOfWork
will provide you with the functionality you need. It expects processing to happen within a single thread. To execute a task in the context of a Unit Of Work, simply call UnitOfWork.execute(Runnable)
or UnitOfWork.executeWithResult(Callable)
on a new DefaultUnitOfWork
. The Unit Of Work will be started and committed when the task completes, or rolled back if the task fails. You can also choose to manually start, commit or rollback the Unit Of Work if you need more control.CurrentUnitOfWork.set(UnitOfWork)
). Subsequently the message is typically handled by a message handler in this phase.onPrepareCommit
listeners are invoked. If a Unit of Work is bound to a transaction, the onCommit
listeners are invoked to commit any supporting transactions. When the commit succeeds, the afterCommit
listeners are invoked. If a commit or any step before fails, the onRollback
listeners are invoked. The message handler result is contained in the ExecutionResult
of the Unit Of Work, if available.unitOfWork.getResources()
method allows you to access the resources attached to the current Unit of Work. Several helper methods are available on the Unit of Work directly, to make working with resources easier.unitOfWork.root()
. If a Unit of Work is the root, it will simply return itself.CorrelationDataProvider
as the mechanism to extract the Correlation Data from a given Message. There are three implementations of CorrelationDataProvider
that come with Axon:MessageOriginProvider
- Provides the correlation identifier and trace identifier based on configurable keys in meta-data. The Correlation Identifier identifies the current message, whilst the Trace Identifier is the identifier of the message which started the current processing (note: this could be the identifier of the current message if the current message starts the processing). Processing in this context can be understood as a business transaction. This is the default CorrelationDataProvider
.SimpleCorrelationDataProvider
- This is a broader provider than MessageOriginProvider
, in the sense that it does not rely on Correlation and Trace Identifiers alone, but defines configurable headers (similar to keys in MessageOriginProvider
) and based on them extracts information from the message's meta-data.MultiCorrelationDataProvider
- A simple wrapper which has a list of CorrelationDataProvider
s where it delegates the Correlation Data extraction to.CorrelationDataProvider
.CorrelationDataProvider
s there is a CorrelationDataInterceptor
which is a handler interceptor and it registers all configured CorrelationDataProvider
s with a current unit of work.Configurer#configureCorrelationDataProviders(Function<Configuration, List<CorrelationDataProvider>> correlationDataProviderBuilder)
it is possible to configure CorrelationDataProvider
s. If you are using Spring, having a bean of type CorrelationDataProvider
in the Spring Application Context is sufficient.