Repositories are essential components in Axon Framework. However, they mostly remain behind the scenes, and developers don't need to interact with them directly. Usually, the framework can configure, instantiate and use the correct repository based on how the developer has constructed the domain components. That convenience sometimes leads to misunderstandings. Those are caused by the many meanings of the term "repository" and the assumptions developers make when they hear or read it.
Depending on what a given developer's background is, the term "repository" may be associated with
- 🟠 software repository (like Maven or npm)
- 🟠 code repository (like Git)
- 🟠 content repository (a database of digital content)
- 🟠 asset repository (a big "bucket" of assets)
- 🟠 data repository (a.k.a. data lake and data warehouse)
- 🟠 Spring Data Repository
- 🟠 DDD repository
There are likely more, but those are enough to illustrate the confusion. Even if the first few entries on the list above cross developers' minds, they should be able to reasonably quickly determine that none really makes sense in a framework like Axon. But then the "data repository" sounds generic enough. Those using Spring can easily assume the "Spring Data Repository" is the one. A "DDD repository" also sounds reasonable, given what the framework does. So which one Axon Framework refers to? Or did it add its own to the pile?
It's not about data lakes or data warehouses
Confusion may arise from overlaying abstract concerns over technical ones. Event Sourcing can be seen as a sort of implementation of a data lake storing indefinitely raw data (every single event in the system). Projections may appear as a sort of implementation of a data warehouse containing specific data for specific uses.
In such a line of thinking, both are data repositories, and thus people used to those concepts may expect that's what the term "repository" in Axon Framework is all about. It is not.
It's not about Spring Data Repository
Many developers use Axon Framework together with Spring and Spring Boot. Many falsely believe Axon Framework is built with Spring or requires Spring. While that demonstrates how well Axon fits in the Spring ecosystem, it also makes it easy to make false assumptions.
A Spring Data repository "significantly reduces the boilerplate code required to implement data access layers for various persistence stores". Axon needs to store data in various persistence stores. The conclusion that "repository" in Axon Framework refers to Spring Data Repository comes naturally to those who always use Spring to build applications. But that is not what it is. And yes, you don't have to use Spring if you don't want to.
It represents the term "repository" from Domain-Driven Design
The term originates from the "Domain-Driven Design: Tackling Complexity in the Heart of Software" book by Erik Evans. I highly recommend the book to any software developer. Those not convinced it's worth the "investment" may have a look at Domain Driven Design Quickly first.
Among other valuable concepts and patterns, DDD describes "repository" as follows:
"The Repository may store references to some of the objects. When an object is created, it may be saved in the repository, and retrieved from there to be used later. If the client requested an object from the repository, and the repository does not have it, it may get it from the storage. Either way, the repository acts as a storage place for globally accessible objects."
In a nutshell, it's an object repository. It is an abstract way to store and retrieve objects. The pattern does not specify how exactly this should be done. The Axon Framework's approach is somewhat stricter but generic enough and allows for multiple implementations:
"The repository is the mechanism that provides access to aggregates. The repository acts as a gateway to the actual storage mechanism used to persist the data. In CQRS, the repositories only need to be able to find aggregates based on their unique identifier. Any other types of queries should be performed against the query database."
So what does a "repository" actually do?
You can start with the
Repository interface to understand the concept in Axon Framework. That interface only provides methods to load and create new instances of an aggregate for a given identifier - the base functionality every repository must have, regardless of implementation.
The interface is implemented by the
AbstractRepository abstract class. This is where the essential logic of loading an aggregate within the current unit of work resides. It also takes care of dispatching the events associated with the aggregate when the unit of work is committed.
LockingRepository is another abstract class that extends the
AbstractRepository, providing a locking mechanism to prevent concurrent modifications of the aggregate. It is the base class for the two actual implementations of a repository that Axon Framework provides OOTB.
CachingEventSourcingRepository (providing improved loading performance) implementations rely on an
Event Store to persist aggregates (in the form of events).
By default, the framework assumes you want an event-sourced aggregate
(one with methods annotated with
@EventSourcingHandler). Thus, unless you have explicitly configured it otherwise, it will create an instance of
CachingEventSourcingRepositoryand configure it as the repository for the aggregate.
- When constructing an instance of an existing aggregate, the repository will instantiate an empty object and then trigger a process that reads all the past events related to the aggregate and calls the respective event-sourcing handler for each. It is also a function of the repository to optimize that process by taking into account snapshots and loading the intermediate aggregate state from the latest one.
The repository does not explicitly store aggregates. It does not have to - all related events
(which will be used to load its state) are persisted in the
Event Storewhen the unit of work is committed.
relies on data storage (typically a database) that can be accessed via
If your aggregate class is a valid
JPAentity, the framework understands that you want a state-stored aggregate. Thus, unless you have explicitly configured it otherwise, it will create an instance of
GenericJpaRepositoryand configure it as the repository for the aggregate.
When constructing an instance of an existing aggregate, the repository will load the
JPAentity from the configured data store. It will use the entity identifier to do so. That is why the same field must be both an aggregate identifier (
@AggregateIdentifier) and an entity identifier (
When the unit of work is committed, the repository will automatically store the updated
JPAentity in the configured data store.
The term repository in Axon Framework strictly follows the DDD concept of the same name. It is an abstract mechanism that provides access to aggregates. It has nothing to do with Spring Data Repository or any other popular word meanings. It is both configurable and extendable, allowing multiple implementations to be used simultaneously for different aggregate types. By default, Axon Framework provides fully functional implementations for event-sourced and state-stored aggregates.
Milen is a Developer Advocate at AxonIQ on a mission to help fellow Java developers around the globe design and build clean, modular and future proof software! After more than 15 years developing, designing and consulting on various solutions for leading European companies, he currently spends most of his time supporting communities and organizations and speaking at conferences all over the world.
September 28th, Amsterdam
Join us for the AxonIQ Conference 2023, where the developer community attends to get inspired by curated talks and networking.
September 27th, Amsterdam
The event to collaborate, discuss, and share knowledge about techniques, tools, and practices for building complex, distributed event-driven applications.