Class ImmutableEntity<T>

java.lang.Object
io.fluxzero.sdk.modeling.ImmutableEntity<T>
Type Parameters:
T - the type of the underlying domain object represented by this entity
All Implemented Interfaces:
Entity<T>
Direct Known Subclasses:
ImmutableAggregateRoot
public class ImmutableEntity<T> extends Object implements Entity<T>
Immutable implementation of the Entity interface, representing a snapshot of a domain entity.

Unlike mutable entities, an ImmutableEntity is never changed in-place. Instead, updates such as event applications or transformations return a new, updated instance, preserving immutability and making it suitable for event-sourced state transitions, testing, and functional-style programming models.

This entity is typically wrapped by higher-level mutable structures such as ModifiableAggregateRoot, which manage lifecycle and mutation tracking.

Key Features

  • Supports event application via methods annotated with @Apply
  • Supports recursive validation using @AssertLegal
  • Automatically resolves child entities and aliases using @Member and @Alias annotations
  • Preserves immutability by returning a new instance after each update

Common Usage

ImmutableEntity<Order> orderEntity = ImmutableEntity.<Order>builder()
    .id("order123")
    .type(Order.class)
    .value(order)
    .entityHelper(entityHelper)
    .serializer(serializer)
    .build();

// Apply an event and receive a new version of the entity
orderEntity = orderEntity.apply(eventMessage);

The update(UnaryOperator) method applies a transformation to the entity value and automatically updates parent references when nested.

Event application is handled via the EntityHelper which dynamically locates appropriate handlers. If no direct handler is found, the event is propagated recursively to nested child entities.

See Also:

  • Constructor Details

    • ImmutableEntity

      public ImmutableEntity()

  • Method Details

    • type

      public Class<T> type()
      Description copied from interface: Entity
      Retrieves the type of the entity.
      Specified by:
      type in interface Entity<T>
      Returns:
      the class type of the entity, or null if the type has not been defined

    • withType

      public Entity<T> withType(Class<T> type)
      Description copied from interface: Entity
      Sets the type of the entity to the specified class and returns the updated entity.
      Specified by:
      withType in interface Entity<T>
      Parameters:
      type - the class representing the type to be set for the entity
      Returns:
      the updated entity with the specified type

    • get

      public T get()
      Description copied from interface: Entity
      Retrieves the current instance of the entity.
      Specified by:
      get in interface Entity<T>
      Returns:
      the current instance of the entity or null if not initialized

    • update

      public Entity<T> update(UnaryOperator<T> function)
      Description copied from interface: Entity
      Updates the current entity's value using the specified unary operator and returns a new entity containing the updated value.
      Specified by:
      update in interface Entity<T>
      Parameters:
      function - the unary operator to apply to the current entity's value
      Returns:
      a new entity containing the updated value after applying the function

    • apply

      public Entity<T> apply(Message message)
      Description copied from interface: Entity
      Applies the given message to the entity.
      Specified by:
      apply in interface Entity<T>
      Parameters:
      message - the message representing the event to be applied
      Returns:
      the updated or newly created Entity of type T

    • commit

      public Entity<T> commit()
      Description copied from interface: Entity
      Commits the current state of the entity, persisting any changes made to it. This method ensures that the modifications are saved. Typically, it is unnecessary to invoke this manually as it is automatically invoked after the current handler or consumer batch has completed.
      Specified by:
      commit in interface Entity<T>
      Returns:
      The updated entity after the commit operation is successfully completed.

    • assertLegal

      public <E extends Exception> Entity<T> assertLegal(Object update) throws E
      Description copied from interface: Entity
      Verifies that the provided update is legal given the current state of the aggregate. If so, the entity is returned; otherwise, it throws an appropriate exception.
      Specified by:
      assertLegal in interface Entity<T>
      Type Parameters:
      E - the type of exception expected if the update is not legal
      Parameters:
      update - the update to be validated for compliance with the required rules
      Returns:
      the entity if the update is legal
      Throws:
      E - if the update fails to meet legal requirements

    • apply

      public Entity<T> apply(DeserializingMessage message)
      Description copied from interface: Entity
      Applies the given deserializing message to the entity.
      Specified by:
      apply in interface Entity<T>
      Parameters:
      message - the deserializing message to process and convert into an entity
      Returns:
      the entity resulting from applying the given deserializing message

    • computeEntities

      protected Collection<? extends ImmutableEntity<?>> computeEntities()

    • computeAliases

      protected Collection<?> computeAliases()