Reference Guide

The demands on software projects increase rapidly, as time progresses. Companies no longer accept a brochure-like homepage to promote their business; they want their (web)applications to evolve together with their business. That means that not only projects and code bases become more complex, it also means that functionality is constantly added, changed and (unfortunately not enough) removed. It can be frustrating to find out that a seemingly easy-to-implement feature can require development teams to take apart an entire application. Furthermore, today's webapplications target an audience of potentially billions of people, making scalability a bare necessity.

Although there are many applications and frameworks around that deal with scalability issues, such as GigaSpaces and Terracotta, they share one fundamental flaw. These stacks try to solve the scalability issues while letting developers develop application using the layered architecture they are used to. In some cases, they even prevent or severely limit the use of a real domain model, forcing all domain logic into services. Although that is faster to start building an application, eventually this approach will cause complexity to increase and development to slow down.

Greg Young, initiator of the Command Query Responsiblity Segregation (CQRS) pattern addressed these issues by drastically changing the way applications are architected. Instead of separating logic into separate layers, logic is separated based on whether it is changing an applition's state or querying it. That means that executing commands (actions that potentially change an application's state) are executed by completely different components than those that query for the application's state. The most important reason for this separation is the fact that there are different technical and non-technical requirements for each of them. When commands are executed, the query components are (a)synchronously updated using events. This mechanism of updates through events, is what makes this architecture is extensible, scalable and ultimately more maintainable.

	Note
	A full explanation of CQRS is not within the scope of this document. If you would like to have more background information about CQRS, visit the Axon Framework website: www.axonframework.org. It contains links to background information.

Since CQRS is so fundamentally different than the layered-architecture which dominates the software landscape nowadays, it is quite hard to grasp. It is not uncommon for developers to walk into a few traps while trying to find their way around this architecture. That's why Axon Framework was conceived: to help developers implement CQRS applications while focussing on the business logic.

Axon Framework helps build scalable, extensible and maintainable applications by supporting developers apply the Command Query Responsiblity Segregation (CQRS) architectural pattern. It does so by providing implementations, sometimes complete, sometimes abstract, of the most important building blocks, such as aggregates, repositories and event busses (the dispatching mechanism for events). Furthermore, Axon provides annotation support, which allows you to build aggregates and event listeners withouth tying your code to Axon specific logic. This allows you to focus on your business logic, instead of the plumbing, and helps you makes your code easier to test in isolation.

Axon does not, in any way, try to hide the CQRS architecture or any of its components from developers. Therefore, depending on team size, it is still advisable to have one or more developers with a thorough understanding of CQRS on each team. However, Axon does help when it comes to guaranteeing delivering events to the right event listeners and processing them concurrently and in the correct order. These multi-threading concerns are typically hard to deal with, leading to hard-to-trace bugs and sometimes complete application failure. When you have a tight deadline, you probably don't even want to care about these concerns. Axon's code is thoroughly tested to prevent these types of bugs.

Most of the concerns Axon addresses are located inside the JVM. However, for an application to be scalable, a single JVM is not enough. Therefore, Axon provides the axon-intregration module, which allows events to be sent to a Spring Integration channel. From there, you can use Spring Integration to dispatch events to application components on different machines. In the near future, Axon will provide more ways to dispatch events between JVM's and physical machines.

Will each application benefit from Axon? Unfortunately not. Simple CRUD (Create, Read, Update, Delete) applications which are not expected to scale will probably not benefit from CQRS or Axon. Fortunately, there is a wide variety of applications that does benefit from Axon.

Applications that will most likely benefit from CQRS and Axon are those that show one or more of the following characteristics:

You can download the Axon Framework from our downloads page: axonframework.org/download.

This page offers a number of downloads. Typically, you would want to use the latest stable release. However, if you're eager to get started using the latest and greatest features, you could consider using the snapshot releases instead. The downloads page contains a number of assemblies for you to download. Some of them only provide the Axon library itself, while others also provide the libraries that Axon depends on. There is also a "full" zip file, which contains Axon, its dependencies, the sources and the documentation, all in a single download.

If you really want to stay on the bleeding edge of development, you can also checkout the sources from the subversion repository: http://axonframework.googlecode.com/svn/trunk/.

If you use maven as your build tool, you need to configure the correct dependencies for your project. Add the following code in your dependencies section:

<dependency>
    <groupId>org.axonframework</groupId>
    <artifactId>axon-core</artifactId>
    <version>0.5</version>
</dependency>

Most of the features provided by the Axon Framework are optional and require additional dependencies. We have chosen not to add these dependencies by default, as they would potentioly clutter your project with artifacts you don't need. This section discusses these dependecies and describes in what scenarios you need them.

<dependency>
    <groupId>com.thoughtworks.xstream</groupId>
    <artifactId>xstream</artifactId
    <version>1.3.1</version>
</dependency>

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-core</artifactId>
    <version>1.0.3.RELEASE</version>
</dependency>

In some cases, it is desirable to set a transaction scope around the command handling process. For example when using synchronous event handling with event handlers that update tables in a database in combintation with the JpaEventStore. By setting the transaction scope in the command dispatching process, all changes can be performed within a single transaction. This provides full consistency guarantees.

Axon provides the SpringTransactionalInterceptor, which uses Spring's PlatformTransactionManager to manage the actual transactions. A transaction is committed when command handling is successful, or rolled back if the command handler (or one of the downstream interceptors) threw an exception.

The most important type of event in any CQRS application is the domain event. It represents an event that occurs inside your domain logic, such as a state change or special notification of a certain state. The latter not being per definition a state change.

In the Axon Framework, all domain events should extend the abstract DomainEvent class. This abstract class keeps track of the aggregate they are generated by, and the sequence number of the event inside the aggregate. This information is important for the Event Sourcing mechanism, as well as for event handlers (see Section 6.2, “Event Listeners”) that need to know the origin of an event.

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.

Note

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 AddressChangedEvent, and two implementations ContactMovedEvent and AddressCorrectedEvent that capture the intent of the state change. Some listeners will care about the intent (e.g. to send an address change confirmation email to the customer), while others don't (e.g. database updating event listeners). The latter will listen to events of the abstract type, while the former will listen to the concrete subtypes. Figure 4.1. Adding intent to events

There is a special type of DomainEvent, which has a special meaning: theAggregateDeletedEvent. This event can be extended to indicate that the event indicates a migration to a "deleted" state of the aggregate. Repositories must consider aggregates that have applied such an event as deleted. Loading such an aggregate in again results in an exception.

Snapshot events are instances of DomainEvent with a special intent. They are typically not dispatched via the event bus, but are used to summarize an arbitrary number of events from the past into a single entry. This can drastically improve performance when initializing an aggregate's state from a series of events. See Section 5.4, “Using Snapshot Events” for more information about snapshot events and their use.

Application events are events that cannot be categorized as domain events, but do have a significant importance for the application. When using application events, check if the event is actually a domain event that you over looked. Examples of application events are the expiry of a user session, or the notification of an email being successfully send. The usefulness of these events depend on the type of application you are creating.

In the Axon Framework, you can extend the abtract ApplicationEvent class for application events. This class will generate a unique identifier and a time stamp for the current event. Optionally, you can attach an object that acts as the source of the event. This source is loosely attached, which means that if the garbage collector cleans up the source, or when the event is serialized and deserialized, the original source class is not available anymore. Instead, you will have access to the type of source and the value of it's toString() method.

The third type of event identified by Axon Framework is the System Event. These events typically provide notifications of the status of the system. These events could, for example, indicate that a subsystem is non-responsive or has raised an exception.

All system events extend the abstract SystemEvent class. Upon construction of this event, you may pass an exception, defining the cause of the event, and a source object which is considered the source of the event. This object is loosely referenced from the event.

Axon framework provides a few repository implementations that can use event sourcing as storage method for aggregates. These repositories require that aggregates implement the EventSourcedAggregateRoot interface. As with most interfaces in Axon, we also provide one or more abstract implementation to help you on your way.

public class MyAggregateRoot extends AbstractEventSourcedAggregateRoot {

    private String someProperty;

    public MyAggregateRoot() {
        apply(new MyAggregateCreatedEvent());
    }

    public MyAggregateRoot(UUID identifier) {
        super(identifier);
    }

    public void handle(DomainEvent event) {
        if (event instanceof MyAggregateCreatedEvent) {
            // do something with someProperty
        }
        // and more if-else-if logic here
    }
}                

AbstractAnnotatedAggregateRoot

As you see in the example above, the implementation of the handle() method can become quite verbose and hard to read. The AbstractAnnotatedAggregateRoot can help. The AbstractAnnotatedAggregateRoot is a specialization of the AbstractAggregateRoot that provides @EventHandler annotation support to your aggregate. Instead of a single handle() method, you can split the logic in separate methods, with names that you may define yourself. Just annotate the event handler methods with @EventHandler, and the AbstractAnnotatedAggregateRoot will invoke the right method for you.

public class MyAggregateRoot extends AbstractEventSourcedAggregateRoot {
    private String someProperty;

    public MyAggregateRoot() {
        apply(new MyAggregateCreatedEvent());
    }

    public MyAggregateRoot(UUID identifier) {
        super(identifier);
    }

    @EventHandler
    private void handleMyAggregateCreatedEvent(MyAggregateCreatedEvent event) {
        // do something with someProperty
    }
}                

In all circumstances, exactly one event handler method is invoked. The AbstractAnnotatedAggregateRoot will search the most specific method to invoke, in the following order:

1. On the actual instance level of the class hierarchy (as returned by this.getClass()), all annotated methods are evaluated

2. If one or more methods are found of which the parameter is of the event type or a super type, the method with the most specific class (the subclass) is chosen and invoked

3. If no methods are found on this level of the class hierarchy, the super type is evaluated the same way

4. When the level of the AbstractAnnotatedAggregateRoot is reached, and no suitable event handler is found, an UnhandledEventException is thrown.

Event handler methods may be private, as long as the security settings of the JVM allow the Axon Framework to change the accessibility of the method. This allows you to clearly separate the public API of your aggregate, which exposes the methods that generate events, from the internal logic, which processes the events.

Tip

An Aggregate will only contain fields of properties it uses for validation or business logic decisions. That means you will likely have some events that have no direct effect on any fields in the aggregate. In that case you can choose to create a handleOtherEvents(DomainEvent event) method with an empty body. This handler will be called for any event for which there is no specific handler, preventing any exception being thrown. Do consider, however, that doing so may result in unexpected behavior if an event handler for a specific type of event is forgotten.

Event listeners need to be registered with an event bus (see Section 6.1, “Event Bus”) to be notified of events. Axon, however, provides a base implementation that take care of this, and other things, for you.

AnnotationEventListenerAdapter

The AnnotationEventListenerAdapter can wrap any object into an event listener. The adapter will invoke the most appropriate event handler method available. These event handler methods must be annotated with the @EventHandler annotation and are resolved according to the same rules that count for annotated aggregate roots (see the section called “ AbstractAnnotatedAggregateRoot ”).

The constructor of the AnnotationEventListenerAdapter takes two parameters: the annotated bean, and the EventBus, to which the listener should subscribe. You can subscribe and unsubscribe the event listener using the subscribe() and unsubscribe() methods on the adapter.

	Tip
	If you use Spring, you can automatically wrap all annotated event listeners with an adapter automatically by configuring a bean of type AnnotationEventListenerBeanPostProcessor. This post processor will automatically find and wrap annotated event listeners inside an AnnotationEventListenerAdapter and register them with an event bus.

By default, event listeners process events in the thread that dispatches them. This means that the thread that executes the command will have to wait untill all event handling has finished. For some types of event listeners this is not the optimal form of processing. Asynchronous event processing improves the scalability of the application, with the penalty of added complexity to deal with "eventual consistency". With the Axon Framework, you can easily convert any event handler into an asynchronous event handler by wrapping it in an AsynchronousEventHandlerWrapper or, when using annotations, adding the type-level AsynchronousEventListener annotation.

The AsynchronousEventHandlerWrapper needs some extra configuration to make an event handler asynchronous. The first thing that the wrapper needs is an Executor, for example a ThreadPoolExecutor. The second is the SequencingPolicy, a definition of which events may be processed in parallel, and which sequentially. The last one is optional: the TransactionManager, which enables you to run event processing within a transaction. The next pragraphs will provide more details about the configuration options.

The Executor is responsible for executing the event processing. The actual implementation most likely depends on the environment that the application runs in and the SLA of the event handler. An example is the ThreadPoolExecutor, which maintains a pool of threads for the event handlers to use to process events. The AsynchonousEventHandlerWrapper will manage the processing of incoming events in the provided executor. If an instance of a ScheduledThreadPoolExecutor is provided, the AsynchronousEventHandlerWrapper will automatically leverage its ability to schedule processing in the cases of delayed retries. See Section 6.2.3, “Managing transactions in asynchronous event handling” for more information about transactions.

The SequencingPolicy defines whether events must be handled sequentially, in parallel or a combination of both. Policies return a sequence identifier of a given event. If two events have the same sequence identifier, this means that they must be handled sequentially be the event handler. A null sequence identifier means the event may be processed in parallel with any other event.

Axon provides a number of common policies you can use:

Besides these provided policies, you can define your own. All policies must implement the EventSequencingPolicy interface. This interface defines a single method, getSequenceIdentifierFor, that returns the identifier sequence identifier for a given event. Events for which an equals sequence identifer is returned must be processed sequentially. Events that produce a different sequence identifier may be processed concurrently. For performance reasons, policy implementations should return null if the event may be processed in parallel to any other event. This is faster, because Axon does not have to check for any restrictions on event processing.

A TransactionManager can be assigned to a AsynchronousEventHandlerWrapper to add transactional processing of events. To optimize processing, events can be processed in small batches inside a transaction. The transaction manager has the ability to influence the size of these batches and can decide to either commit, skip or retry event processing based on the result of a batch. See Section 6.2.3, “Managing transactions in asynchronous event handling” for more information.

@AsynchronousEventListener(sequencingPolicyClass = MyCustomPolicy.class)
public class MyEventListener() {

    @EventHandler
    public void onSomeImportantEvent(MyEvent event) {
        // eventProcessing logic
    }
}

public class MyCustomPolicy implements EventSequencingPolicy {
    public Object getSequenceIdentifierFor(Event event) {
        if (event instanceof MyEvent) {
            // let's assume that we do processing based on the someProperty field.
            return ((MyEvent) event).someProperty();
        }
        return null;
    }
}                    

In some cases, your event handlers have to store data in systems that use transactions. Starting and committing a transaction for each single event has a big performance impact. In Axon, events are processed in batches. The batch size depends of the number of events that need to be processed and the settings provided by the event handler. By default, the batch size is set to the number of events available in the processing queue at the time a batch starts.

In most cases, event handling is done using a thread pool executor, or scheduler. The scheduler will schedule batches of event processing as soon as event become available. When a batch is completed, the scheduler will reschedule processing of the next batch, as long as more events are available. The smaller a batch, the more "fair" the distribution of event handler processing is, but also the more scheduling overhead you create.

When an event listener is wrapped with the AsynchronousEventHandlerWrapper, you can configure a TransactionManager to handle transactions for the event listener. The transaction manager can, based on the information in the TransactionStatus object, decide to start, commit or rollback a transaction to an external system.

The beforeTransaction(TransactionStatus) method is invoked just before Axon will start handling an event batch. You can use the TransactionStatus object to configure the batch before it is started. For example, you can change the maximum number of events that may run in the batch.

The afterTransaction(TransactionStatus) method is invoked after the batch has been processed, but before the scheduler has scheduled the next batch. Based on the value of isSuccessful(), you can decide to commit or rollback the underlying transaction.