The most basic implementation of the repository is AbstractRepository. It takes care of the event publishing when an aggregate is saved. The actual persistence mechanism must still be implemented. This implementation doesn't provide any locking mechanism and expects the underlying data storage mechanism to provide it.

If the underlying data store does not provide any locking mechanism to prevent concurrent modifications of aggregates, consider using the abstract LockingRepository implementation. Besides providing event dispatching logic, it will also ensure that aggregates are not concurrently modified.

You can configure the LockingRepository to use an optimistic locking strategy, or a pessimistic one. When the optimistic lock detects concurrent access, the second thread saving an aggregate will receive a ConcurrencyException. The pessimistic lock will prevent concurrent access to the aggregate alltogether. The pessimistic locking strategy is the default strategy.

Event ordering and optimistic locking strategy

Note that the optimistic lock doesn't lock any threads at all. While this reduces contention, it also means that the thread scheduler of your underlying architecture (OS, CPU, etc) is free to schedule threads as it sees fit. In high-concurrent environments (many threads accessing the same aggregate simultaneously), this could lead to events not being dispatched in exactly the same order as they are generated. If this guarantee is important, use pessimistic locking instead.

ConcurrencyException vs ConflictingModificationException

Note that there is a clear distinction between a ConcurrencyException and a ConflictingModificationException. The first is used to indicate a repository cannot save an aggregate, because the changes it contains were not applied to the latest available version. The latter indicates that the loaded aggregate contains changes that might not have been seen by the end-user. See Section 5.5, “Advanced conflict detection and resolution” for more information.

This is a repository implementation that can store JPA compatible Aggregates, such as AbstractJpaAggregateRoot subclasses. It is configured with an EntityManager to manage the actual persistence, and a class specifiying the actual type of Aggregate stored in the Repository.

The abstract EventSourcingRepository implementation provides the basic functionality needed by any event sourcing repository in the AxonFramework. It depends on an EventStore, which abstracts the actual storage mechanism for the events. See Section 5.3, “Event store implementations”.

The EventSourcingRepository has two abstract methods: getTypeIdentifier() and instantiateAggregate(identifier, firstDomainEvent). The first should return a value that is passed to the event store that provides information about the type of aggregate the events relate to. A good starting point to use as return value is the simple name of a class (i.e. the fully qualified class name withouth the package name). The second method requires you to create an uninitialized instance of the aggregate using the given identifier. The repository will initialize this instance with the events obtained from the event store.

Initializing aggregates based on the events can be a time-consuming effort, compared to the direct aggregate loading of the simple repository implementations. The CachingEventSourcingRepository provides a cache from which aggregates can be loaded if available. You can configure any jcache implementation with this repository. Note that this implementation can only use caching in combination with a pessimistic locking strategy.

	Note
	Using a cache with optimistic locking would create undesired side-effects. Optimistic locking allows concurrent access to objects and will only fail when two threads have concurrently made any modifications to that object. When using a cache, both threads will receive the same instance of the object. They will both apply their changes to that same instance, potentially interfering with eachother.

The GenericEventSourcingRepository is a special EventSourcingRepository implementation that can act as a repository for any type of Event Sourced Aggregate Root. There is however, a convention that these EventSourcedAggregateRoot classes must adhere to: the type must declare an accessible constructor accepting an AggregateIdentifier as single parameter. This constructor may not perform any initialization on the aggregate, other than setting the identifier.

In many cases, this generic repository will suffice. If not, you can always choose to extend any of the other event sourcing repository implementations.

Depending on your architectural choices, it might be useful to inject dependencies into your aggregates using Spring. You could, for example, inject query repositories into your aggregate to ensure the existance (or inexistance) of certain values.

To inject dependencies into your aggregates, you need to configure a prototype bean of your aggregate root in the Spring context that also defines the SpringPrototypeEventSourcingRepository. Instead of creating regular instances of using a constructor, it uses the Spring Application Context to instantiate your aggregates. This will also inject any dependencies in your aggregate.

The HybridJpaRepository is a combination of the GenericJpaRepository and an Event Sourcing repository. It can only deal with event sourced aggregates, and stores them in a relational model as well as in an event store. When the repository reads an aggregate back in, it uses the relational model exclusively.

This repository removes the need for Event Upcasters, making data migrations potentially easier. Since the aggregates are event sourced, you keep the ability to use the given-when-then test fixtures (see Chapter 8, Testing). On the other hand, since it doesn't use the event store for reading, it doesn't allow for automated conflict resolution.

The FileSystemEventStore stores the events in a file on the file system. It provides good performance and easy configuration. The downside of this event store is that is does not provide transaction support and doesn't cluster very well. The only configuration needed is the location where the event store may store its files and the serializer to use to actually serialize and deserialize the events. Note that the provided url must end on a slash. This is due to the way Spring's Resource implementations work.

The JpaEventStore stores events in a JPA-compatible data source. Unlike the file system version, the JPAEventStore supports transactions. The JPA event store can also load events based on their timestamps.

To use the JpaEventStore, you must have the javax.persistence annotations on your classpath. Furthermore, you should configure your persistence context (defined in META-INF/persistence.xml file) to contain the classes org.axonframework.eventstore.jpa.DomainEventEntry and org.axonframework.eventstore.jpa.SnapshotEventEntry.

Below is an example configuration of a persistence context configuration:

<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
    <persistence-unit name="eventStore" transaction-type="RESOURCE_LOCAL">
        <class>org...eventstore.jpa.DomainEventEntry</class> 
        <class>org...eventstore.jpa.SnapshotEventEntry</class>
    </persistence-unit>
</persistence>

	In this sample, there is is specific persistence unit for the event store. You may, however, choose to add the third line to any other persistence unit configuration.
	This line registers the DomainEventEntry (the class used by the JpaEventStore) with the persistence context.

Detecting duplicate key violations in the database

Axon uses Locking to prevent two threads from accessing the same Aggregate. However, if you have multiple JVMs on the same database, this won't help you. In that case, you'd have to rely on the database to detect conflicts. Concurrent access to the event store will result in a Key Constraint Violation, as the table only allows a single Event for an aggregate with any sequence number. Inserting a second event for an existing aggregate with an existing sequence number will result in an error. The JPA EventStore can detect this error and translate it to a ConcurrencyException. However, each database system reports this violation differently. If you register your DataSource with the JpaEventStore, it will try to detect the type of database and figure out which error codes represent a Key Constraint Violation. Alternatively, you may provide a PersistenceExceptionTranslator instance, which can tell if a given exception represents a Key Constraint Violation. If no DataSource or PersistenceExceptionTranslator is provided, exceptions from the Database driver are thrown as-is.

If you have specific requirements for an event store, it is quite easy to implement one using different underlying data sources. Reading and appending events is done using a DomainEventStream, which is quite similar to iterator implementations.

	Tip
	The SimpleDomainEventStream class will make the contents of a sequence (List or array) of DomainEvent instances accessible as event stream.

Event Stores need a way to serialize the Domain Event to prepare it for storage. By default, Axon uses the XStreamEventSerializer, which uses XStream (see xstream.codehaus.org) to serialize Domain Events into XML and vice versa. XStream is very fast and is more flexible than Java Serialization. Furthermore, the result of XStream serialization is human readable. Quite useful for logging and debugging purposes.

The XStreamEventSerializer can be configured. You can define aliases it should use for certain packages, classes or even fields. Besides being a nice way to shorten potentially long names, aliases can also be used when class definitions of event change. For more information about aliases, visit the XStream website: xstream.codehaus.org.

You may also implement your own Event Serializer, simply by creating a class that implements EventSerializer, and configuring the Event Store to use that implementation instead of the default.

It is not unlikely that a definition of an Event remains unchanged during the entire lifespan of an application. New insights, changes in requirements and many other factors can lead to modifications in Events. Since the Event Store is considered a read and append-only data source, your application must be able to read all events, regardless of when they have been added.

In Axon, Events have a revision, a numeric value that defaults to 0. If an Event definition changes, you should update the revision number too. The deserialization process can then be adapted when your application needs to cope with old revisions of events. A class file for an Event only needs to support the latest revision. When old revisions are deserialized, they can be "upcasted" to the newer revision.

The EventUpcaster is responsible for transforming old events into the last revision. Upcasters typically work on an intermediate representation of the Event. In the case of the XStreamEventSerializater, this intermediate representation is dom4j (see http://dom4j.sourceforge.net/), an easy to use java XML library that integrates nicely with XStream. The EventUpcaster can modify the XML structure of the event so that it matches the new definition.