Package org.axonframework.eventsourcing

Interface EventSourcedEntityFactory<ID,E>

Type Parameters:
ID - The type of the identifier of the entity to create.
E - The type of the entity to create.
All Known Implementing Classes:
AnnotationBasedEventSourcedEntityFactory
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface EventSourcedEntityFactory<ID,E>
Defines how an EventSourcingRepository should construct an entity of type E.

When sourcing an entity, the state is initially null. The first event will initialize the entity through create(Object, EventMessage, ProcessingContext).

If no events are found during sourcing, the repository will return null for the entity if EventSourcingRepository.load(Object, ProcessingContext) was used. However, if EventSourcingRepository.loadOrCreate(Object, ProcessingContext) was used, the repository will return an empty entity through calling create(Object, EventMessage, ProcessingContext) with a null firstEventMessage. This may return null in case the entity should be created with the first event message only. For example, when it is immutable.

Depending on the type of entity, the factory should be created differently. The following types of entities are supported:

  • Mutable entities: these entities are created with a no-argument constructor. All command handlers of the entity should be instance command handlers. Use fromNoArgument(Supplier) to create a factory for this type of entity.
  • Mutable entities with non-null identifier: these entities are created with a constructor that takes the identifier as parameter. All command handlers of the entity should be instance command handlers. Use fromIdentifier(Function) to create a factory for this type of entity.
  • Immutable entities, or entities with non-nullable parameters: these entities are created with a constructor that takes the identifier and the event message as parameters. The entity should have a combination of creational command handlers to create the entity if no events exist for it, and instance command handlers to handle commands when it does exist. If a command could potentially handle both cases, it would need to be registered as both a creational and instance command handler. Use fromEventMessage(BiFunction) to create a factory for this type of entity.

Implementations should be thread-safe.

Since:
5.0.0
Author:
Mitchell Herrijgers

  • Method Details

    • create

      @Nullable E create(@Nonnull ID id, @Nullable EventMessage firstEventMessage, @Nonnull ProcessingContext context)
      Creates an entity of type E with the given identifier. The identifier is guaranteed to be non-null. The supplied firstEventMessage is the first event message that is present in the stream of the entity. If no event messages are present, this method will be called with a null firstEventMessage to get an initial state when calling EventSourcingRepository.loadOrCreate(Object, ProcessingContext). Using EventSourcingRepository.load(Object, ProcessingContext) would never call this method with a null firstEventMessage.

      Invocations with a non-null firstEventMessage must always return a non-null entity, while invocations with a null firstEventMessage may return null.

      Whether to return null from a null firstEventMessage invocation depends on the type of command handler which should be invoked when the entity does not exist. If this is a creational command handler, this should return null. If this is a instance command handler, this should return the non-null initial state of the entity. For example, using the no-argument constructor of the entity, or a constructor that takes the identifier as a parameter.

      It is recommended to use fromNoArgument(Supplier), fromIdentifier(Function) or fromEventMessage(BiFunction) to create a factory that creates the entity based on the constructor of the entity. This will ensure that the right factory is created.

      Parameters:
      id - The identifier of the entity to create. This is guaranteed to be non-null.
      firstEventMessage - The first event message that is present in the stream of the entity. This may be null if no event messages are present.
      context - The processing context.
      Returns:
      The entity to create. This may be null if no entity should be created.

    • fromNoArgument

      static <ID, E> EventSourcedEntityFactory<ID,E> fromNoArgument(@Nonnull Supplier<E> creator)
      Creates a factory for an entity of type EventSourcedEntityFactory using a specified no-argument constructor.

      Should be used when your entity is mutable, and you want to create it with a no-argument constructor. All command handlers of your entity should be instance command handler. If you would like the identifier to be passed to the constructor, use fromIdentifier(Function) instead.

      Type Parameters:
      ID - The type of the identifier of the entity.
      E - The type of the entity.
      Parameters:
      creator - A Supplier that creates the entity. This should be a no-argument constructor.
      Returns:
      A factory that creates the entity using the no-argument constructor.

    • fromIdentifier

      static <ID, E> EventSourcedEntityFactory<ID,E> fromIdentifier(@Nonnull Function<ID,E> creator)
      Creates a factory for an entity of type EventSourcedEntityFactory using a specified constructor with the identifier as parameter.

      Should be used when your entity is mutable, and you want to create it with a constructor that takes the identifier as parameter. All command handlers of your entity should be instance command handler.

      Type Parameters:
      ID - The type of the identifier of the entity.
      E - The type of the entity.
      Parameters:
      creator - A Function that creates the entity. This should be a constructor with the identifier as parameter.
      Returns:
      A factory that creates the entity using the constructor with the identifier as parameter.

    • fromEventMessage

      static <ID, E> EventSourcedEntityFactory<ID,E> fromEventMessage(@Nonnull BiFunction<ID,EventMessage,E> creator)
      Creates a factory for an entity of type EventSourcedEntityFactory using a specified constructor with the identifier and the event message as parameters.

      Should be used if your entity is immutable, and/or you want to create it with a constructor that takes the identifier and the event message as parameters to set non-nullable parameters on it. Your entity should have a combination of creational command handlers to create the entity if no events exist for it, and instance command handlers to handle commands when it does exist. If a command could potentially handle both cases, it would need to be registered as both a creational and instance command handler.

      Type Parameters:
      ID - The type of the identifier of the entity.
      E - The type of the entity.
      Parameters:
      creator - A BiFunction that creates the entity. This should be a constructor with the identifier and the event as parameters.
      Returns:
      A factory that creates the entity using the constructor with the identifier and the event message as parameters.