Entities

In Axon Framework, an entity is a stateful component on the command side that accumulates state from prior commands and uses it to enforce business rules when handling new ones. Axon supports event-sourced entities, where state is rebuilt by replaying a sequence of events. If you are new to event sourcing, see Events core concepts for an introduction.

When to use entities

Use an entity when a command needs state established by earlier commands:

"A course cannot accept more students than its capacity": the handler needs to know how many are enrolled.
"A bank account cannot go below zero": the handler needs the current balance.
"An order can only be cancelled if it has not shipped": the handler needs the order status.

When not to use entities

Do not use an entity when the command can be validated without reading prior state:

Sending a notification.
Creating a resource with a client-supplied identifier, with no existing state to check.
Forwarding a command to an external system that owns the state.

These are stateless command handlers: simpler and cheaper to run. If you are adding an entity only to hold a flag that is set once and never changes, that is a signal the command may not need an entity.

Subsections

Sub-section Purpose

Sub-section	Purpose
Event-sourced entities	How to define and configure an event-sourced entity: creational and instance command handlers, event sourcing handlers, `@EntityCreator` patterns, and the declarative approach.
Stateful command handlers	How to keep command handling logic in a dedicated class separate from the entity, using `@InjectEntity` to receive entity state as a parameter. This is the recommended approach for Vertical Slice Architecture.
Entity hierarchies	How to structure a parent entity that owns child entities, including command and event routing, single vs. collection children, and custom routing strategies.
Entity inheritance	How the event sourcing handlers declared on an entity class and its supertypes run: overrides, separate handlers, immutable chaining, and changing the concrete type.
Polymorphic entities	How to model multiple concrete entity types sharing a common abstract parent, with type selection at creation time.
Entity identifier resolution	How Axon resolves the entity identifier from a command: the built-in resolvers, custom resolvers, and the `EntityIdResolverDefinition`.
Entity-specific command handler interceptors	How to derive an interceptor that interceptors a command before it enters a specific entity, supporting interceptor tasks using that entity.

Event-sourced entities

How to define and configure an event-sourced entity: creational and instance command handlers, event sourcing handlers, @EntityCreator patterns, and the declarative approach.

Stateful command handlers

How to keep command handling logic in a dedicated class separate from the entity, using @InjectEntity to receive entity state as a parameter. This is the recommended approach for Vertical Slice Architecture.

Entity hierarchies

How to structure a parent entity that owns child entities, including command and event routing, single vs. collection children, and custom routing strategies.

Entity inheritance

How the event sourcing handlers declared on an entity class and its supertypes run: overrides, separate handlers, immutable chaining, and changing the concrete type.

Polymorphic entities

How to model multiple concrete entity types sharing a common abstract parent, with type selection at creation time.

Entity identifier resolution

How Axon resolves the entity identifier from a command: the built-in resolvers, custom resolvers, and the EntityIdResolverDefinition.

Entity-specific command handler interceptors

How to derive an interceptor that interceptors a command before it enters a specific entity, supporting interceptor tasks using that entity.