Messaging Concepts
One of the core concepts in Axon is messaging. All communication between components is done using message objects. This gives these components the location transparency needed to be able to scale and distribute these components when necessary.
Although all these messages implement the Message interface, there is a clear distinction between the different types of messages and how they are treated.
All messages contain a payload, metadata and unique identifier. The payload of the message is the functional description of what the message means. The combination of the class name of this object and the data it carries, describe the application’s meaning of the message. The metadata allows you to describe the context in which a message is being sent. You can, for example, store tracing information, to allow the origin or cause of messages to be tracked. You can also store information to describe the security context under which a command is being executed.
|
All messages are immutable
Note 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. |
Commands
Commands describe an intent to change the application’s state.
They are implemented as (preferably read-only) POJOs that are wrapped using one of the CommandMessage implementations.
Commands always have exactly one destination. While the sender does not care which component handles the command or where that component resides, it may be interesting knowing the outcome of it. That is why command messages sent over the command bus allow for a result to be returned.
Events
Events are objects that describe something that has occurred in the application. A typical source of events is the aggregate. When something important has occurred within the aggregate, it will raise an event. In Axon Framework, events can be any object. You are highly encouraged to make sure all events are serializable.
When Events are dispatched, Axon wraps them in an 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 the 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.
|
Include aggregate identifiers in tyour events
Even though the |
The original event object is stored as the payload of an EventMessage.
Next to the payload, you can store information in the metadata of an event message.
The intent of the metadata is to store additional information about an event that is not primarily intended as business information.
Auditing information is a typical example.
It allows you to see under which circumstances an Event was raised.
Such as the user account that triggered the processing, or the name of the machine that processed the event.
|
Do not base business decisions on metadata
In general, you should not base business decisions on information in the metadata of event messages. If that is the case, you might have information attached that should really be part of the event itself instead. Metadata is typically used for reporting, auditing and tracing. |
Although not enforced, it is good practice to make domain events immutable, preferably by making all fields final and by initializing the event within the constructor. Consider using a Builder pattern if event construction is too cumbersome.
|
Capture intent in your events
Although 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 abstract 
|
When dispatching an Event on the Event Bus, you will need to wrap it in an Event Message.
The 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 Metadata.
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.
Queries
Queries describe a request for information or state. A query can have multiple handlers. When dispatching queries, the client indicates whether he wants a result from one or from all available query handlers.
Message flow
When building Axon Framework applications, you will typically see a flow of messages. Commands are sent to the Command Bus, which dispatches them to the appropriate Command Handler. The command handler will apply events that will be published and handled by Event Handlers. These handlers can update the read model, which can be queried using Query Messages.
Using AxonIQ Console, you can monitor the flow of messages in your application as you can see in the image below.
Besides seeing the flow, every message handler is individually monitored, providing deep insight into the performance and behavior of your application. For more information, see the AxonIQ Console Reference Guide or sign up directly.