Package io.fluxcapacitor.javaclient.modeling

Annotation Interface Aggregate

@Documented @Target(TYPE) @Retention(RUNTIME) @Inherited @Searchable public @interface Aggregate
Marks a class as the root of an aggregate in the domain model.

Aggregates are the primary consistency boundaries in Flux. They may consist of a root entity (the annotated class) and any number of nested child entities, which are registered using the @Member annotation.

This annotation also allows fine-grained configuration of event sourcing, caching, snapshotting, and automatic indexing in Flux’s document store.

Usage


 @Aggregate
 public class Project {
     @EntityId String projectId;

     @Member List<Task> tasks;
 }

Loading and Modifying Aggregates

Aggregates can be loaded using methods like FluxCapacitor.loadAggregate(io.fluxcapacitor.javaclient.modeling.Id<T>). Updates are applied via @Apply methods, and legality checks can be enforced using @AssertLegal.

Child Entities

Use Member to define child, grandchild, or other descendant entities in the aggregate. These entities can independently handle updates and be targeted via their EntityId.
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    cached
    Whether the aggregate should be cached after updates (enabled by default).
    int
    cachingDepth
    Controls how many versions of the aggregate should be retained in the cache.
    int
    checkpointPeriod
    Sets the event checkpointing frequency for intermediate aggregate states.
    String
    collection
    Name of the collection to index the aggregate into.
    boolean
    commitInBatch
    Whether changes to the aggregate should be committed at the end of a message batch (enabled by default).
    String
    endPath
    Optional path to extract an end timestamp for search indexing.
    EventPublication
    eventPublication
    Controls whether updates that don’t change the aggregate result in events.
    boolean
    eventSourced
    Whether the aggregate should use event sourcing (enabled by default).
    boolean
    ignoreUnknownEvents
    Whether to ignore unknown events during event sourcing (disabled by default).
    EventPublicationStrategy
    publicationStrategy
    Strategy that determines how applied updates are persisted and/or published.
    boolean
    searchable
    Whether the aggregate should be indexed in Flux’s document store (disabled by default).
    int
    snapshotPeriod
    Enables snapshotting after a certain number of applied updates.
    String
    timestampPath
    Path to extract the main timestamp used in search indexing.

  • Element Details

    • eventSourced

      boolean eventSourced
      Whether the aggregate should use event sourcing (enabled by default).

      When enabled, applied updates are stored in the event store and used to reconstruct the aggregate state.

      Disabling event sourcing may be useful for read-heavy aggregates or reference data that seldom changes. Apply methods still work even when event sourcing is disabled, but updates will not be stored.

      Default:
      true

    • ignoreUnknownEvents

      boolean ignoreUnknownEvents
      Whether to ignore unknown events during event sourcing (disabled by default).

      If disabled and an unknown event is encountered, an error will occur when the aggregate is loaded.

      Default:
      false

    • snapshotPeriod

      int snapshotPeriod
      Enables snapshotting after a certain number of applied updates.

      Default is 0 (disabled). Use a positive value (e.g., 1000) to trigger snapshotting every n events.

      Useful for aggregates with many events or large event payloads.

      Default:
      0

    • cached

      boolean cached
      Whether the aggregate should be cached after updates (enabled by default).

      Aggregates are always cached thread-locally before being committed. This setting controls whether the latest version is stored in the shared application cache.

      Default:
      true

    • cachingDepth

      int cachingDepth
      Controls how many versions of the aggregate should be retained in the cache.

      A value of -1 (default) means all versions are cached.

      Use 0 to only cache the latest version. Values > 0 retain older versions, enabling use of Entity.previous().

      Default:
      -1

    • checkpointPeriod

      int checkpointPeriod
      Sets the event checkpointing frequency for intermediate aggregate states.

      Only applies to event-sourced aggregates with a positive cachingDepth().

      Default:
      100

    • commitInBatch

      boolean commitInBatch
      Whether changes to the aggregate should be committed at the end of a message batch (enabled by default).

      Set to false to commit updates immediately after each message.

      Default:
      true

    • eventPublication

      EventPublication eventPublication
      Controls whether updates that don’t change the aggregate result in events.

      Use EventPublication.IF_MODIFIED to automatically skip events if nothing changes.

      This setting is evaluated before publicationStrategy().

      Default:
      DEFAULT

    • publicationStrategy

      EventPublicationStrategy publicationStrategy
      Strategy that determines how applied updates are persisted and/or published.

      The default strategy is EventPublicationStrategy.STORE_AND_PUBLISH, unless overridden.

      Default:
      DEFAULT

    • searchable

      boolean searchable
      Whether the aggregate should be indexed in Flux’s document store (disabled by default).
      Default:
      false

    • collection

      String collection
      Name of the collection to index the aggregate into. Only relevant if searchable() is true.

      Defaults to the class name if left blank.

      See Also:
      Default:
      ""

    • timestampPath

      String timestampPath
      Path to extract the main timestamp used in search indexing. Only relevant if searchable() is true.

      If endPath() is not specified, this will be used as both start and end time.

      Useful for time-based search queries (e.g., validity or activity windows).

      See Also:
      Default:
      ""

    • endPath

      String endPath
      Optional path to extract an end timestamp for search indexing. Only relevant if searchable() is true.

      If omitted, the start timestamp will also be used as the end timestamp.

      See Also:
      Default:
      ""