Package org.axonframework.eventsourcing.annotation

Annotation Interface EventSourcedEntity

@Target(TYPE)
@Retention(RUNTIME)
public @interface EventSourcedEntity

Annotation to configure several aspects of an event-sourced entity. This annotation is required to construct an annotation-based entity through the EventSourcedEntityModule.autodetected(Class, Class).

Event Criteria

While loading the entity from the EventSourcingRepository, the provided id needs to be translated to an EventCriteria instance to load the correct events. Unless overridden, this translation is done by the AnnotationBasedEventCriteriaResolver. The EventCriteria will be resolved in the following order:

1. Using the custom criteriaResolverDefinition(). The definition should return a CriteriaResolver, implement the CriteriaResolverDefinition interface, and have a no-arg constructor.
2. By defining a static method in the entity class annotated with EventCriteriaBuilder which returns an EventCriteria and accepts the id as a parameter. This method should be static and return an EventCriteria. Multiple methods can be defined with different id types, and the first matching method will be used. Optionally, you can define MessageTypeResolver as a second parameter to resolve the type of the message. Other arguments are not supported.
3. If no matching EventCriteriaBuilder is found, the tagKey() will be used as the tag key, and the Object.toString() of the id will be used as value.
4. If the tagKey() is empty, the Class.getSimpleName() of the entity will be used as the key, and the Object.toString() of the id will be used as value.

Entity Factory

Event-sourced entities need to be instantiated before they can be evolved based on past events. The EventSourcedEntityFactory is responsible for creating a new instance of the entity. By default, this is done based on constructors or static methods annotated with EntityCreator. These creators can take the payload or message of the first event, or the entity id as a parameter. For more information, see the examples in the Javadoc of the annotation.

Command handling

Entities can declare CommandHandler-annotated methods to execute a command on the entity. When a command targets an entity, the following steps are taken:

1. The EntityCommandHandlingComponent will use the EntityIdResolverDefinition to resolve the entity id from the command message.
2. The entity id is used to resolve the EventCriteria for the entity, as described above.
3. The EventSourcedEntityFactory is used to create a new instance of the entity by the EventSourcingRepository.
4. Existing events for the entity are used to evolve the entity.
5. The command is called on the entity in case of a instance command handler, or on the creational command handler if it did not exist.

By default, the id is resolved using the AnnotationBasedEntityIdResolver, which resolves the id based on the TargetEntityId annotation on a field or method of the command payload. You can customize this behavior by providing a custom entityIdResolverDefinition().

Polymorphic entities

Polymorphic entities are entities that can have multiple concrete types, and the type of the entity is determined by the payload of the first event. In this case, the concreteTypes() should be specified with the concrete types of the entity.

Since:

5.0.0

Author:

Mitchell Herrijgers

See Also:

• EntityCreator
• EventCriteriaBuilder
• AnnotationBasedEventCriteriaResolver
• EventCriteriaBuilder
• EventSourcedEntityFactory

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<?>[]	concreteTypes	If the entity is a polymorphic entity, any subclasses that should be considered concrete types of the entity should be specified here.
Class<? extends CriteriaResolverDefinition>	criteriaResolverDefinition	The definition of the CriteriaResolver to use to resolve the EventCriteria for the entity.
Class<? extends EventSourcedEntityFactoryDefinition>	entityFactoryDefinition	The definition of the EventSourcedEntityFactory to use to create a new instance of the entity.
Class<? extends EntityIdResolverDefinition>	entityIdResolverDefinition	The definition of the EntityIdResolverDefinition to use to resolve the entity id from a command message.
String	tagKey	The tag name to use when resolving the EventCriteria for the entity.

Element Details

tagKey

String tagKey

The tag name to use when resolving the EventCriteria for the entity. If empty, the simple name of the entity class will be used.

This value does not take effect if a matching EventCriteriaBuilder is found, or a custom criteriaResolverDefinition() is provided.

Returns:

The tag name to use when resolving the EventCriteria for the entity.

Default:

""

concreteTypes

Class<?>[] concreteTypes

If the entity is a polymorphic entity, any subclasses that should be considered concrete types of the entity should be specified here. Classes that are not specified here will not be scanned.

Returns:

The concrete types of the entity that should be considered when building the AnnotatedEntityMetamodel.

Default:

{}

criteriaResolverDefinition

Class<? extends CriteriaResolverDefinition> criteriaResolverDefinition

The definition of the CriteriaResolver to use to resolve the EventCriteria for the entity. A custom definition can be provided to override the default behavior of the AnnotationBasedEventCriteriaResolver.

Returns:

The definition to construct a CriteriaResolverDefinition.

Default:

org.axonframework.eventsourcing.annotation.AnnotationBasedEventCriteriaResolverDefinition.class

entityFactoryDefinition

Class<? extends EventSourcedEntityFactoryDefinition> entityFactoryDefinition

The definition of the EventSourcedEntityFactory to use to create a new instance of the entity. A custom definition can be provided to override the default behavior of the AnnotationBasedEventSourcedEntityFactoryDefinition.

Returns:

The definition to construct an EventSourcedEntityFactory.

Default:

org.axonframework.eventsourcing.annotation.reflection.AnnotationBasedEventSourcedEntityFactoryDefinition.class

entityIdResolverDefinition

Class<? extends EntityIdResolverDefinition> entityIdResolverDefinition

The definition of the EntityIdResolverDefinition to use to resolve the entity id from a command message. Defaults to the AnnotatedEntityIdResolverDefinition, which resolves the entity id based on the TargetEntityId annotation on a payload field or method, after converting the payload to the representation wanted by the entity.

Returns:

The definition to construct an EntityIdResolverDefinition.

Default:

org.axonframework.modelling.entity.annotation.AnnotatedEntityIdResolverDefinition.class