Annotation Interface Aggregate

@Deprecated(forRemoval=true) @Documented @Target(TYPE) @Retention(RUNTIME) @Inherited @Searchable public @interface Aggregate
Deprecated, for removal: This API element is subject to removal in a future version.
Scheduled for removal in Fluxzero 3.0. Use @Model for new domain state. Existing aggregate data requires a deliberate migration; changing this annotation alone does not migrate it. See the upgrade and migration guide.
Marks a class as the root of a legacy aggregate in the domain model.

Use independent @Model types for new domain state, connected through @Parent. Their histories and relationships can evolve without expanding a shared persistence root. A model can still own embedded @Member entities when they deliberately share its entire lifecycle.

This legacy API remains supported in Fluxzero 2.x for existing applications and incremental migration, but is scheduled for removal in Fluxzero 3.0. An SDK upgrade does not migrate aggregate data; replacing this annotation with Model alone does not migrate streams, snapshots, or embedded children. See the 2.x upgrade and migration guide. Member remains supported and is not deprecated.

Legacy aggregates consist of a root entity (the annotated class) and any number of nested child entities registered using @Member.

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

Legacy usage

@Aggregate
public class Project {
    @EntityId String projectId;

    @Member List<Task> tasks;
}

Loading and Modifying Aggregates

Aggregates can be loaded using methods like Fluxzero.loadAggregate(Id). 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
    Deprecated, for removal: This API element is subject to removal in a future version.
    Whether the aggregate should be cached after updates (enabled by default).
    int
    cachingDepth
    Deprecated, for removal: This API element is subject to removal in a future version.
    Controls how many versions of the aggregate should be retained in the cache.
    int
    checkpointPeriod
    Deprecated, for removal: This API element is subject to removal in a future version.
    Sets the event checkpointing frequency for intermediate aggregate states.
    String
    collection
    Deprecated, for removal: This API element is subject to removal in a future version.
    Name of the collection to index the aggregate into.
    AggregateCommitPolicy
    commitPolicy
    Deprecated, for removal: This API element is subject to removal in a future version.
    Controls when aggregate changes are committed and whether multiple commits in the same completion phase may run concurrently.
    String
    endPath
    Deprecated, for removal: This API element is subject to removal in a future version.
    Optional path to extract an end timestamp for search indexing.
    EventPublication
    eventPublication
    Deprecated, for removal: This API element is subject to removal in a future version.
    Controls whether updates that don’t change the aggregate result in events.
    AggregateEventRouting
    eventRouting
    Deprecated, for removal: This API element is subject to removal in a future version.
    Controls how events published from this aggregate are assigned to a message segment.
    boolean
    eventSourced
    Deprecated, for removal: This API element is subject to removal in a future version.
    Whether the aggregate should use event sourcing (enabled by default).
    boolean
    ignoreUnknownEvents
    Deprecated, for removal: This API element is subject to removal in a future version.
    Whether to ignore unknown events during event sourcing (disabled by default).
    int
    maxSnapshotCount
    Deprecated, for removal: This API element is subject to removal in a future version.
    Maximum number of snapshots to retain for this aggregate.
    EventPublicationStrategy
    publicationStrategy
    Deprecated, for removal: This API element is subject to removal in a future version.
    Strategy that determines how applied updates are persisted and/or published, and whether publish-only updates advance aggregate state for this aggregate type.
    boolean
    searchable
    Deprecated, for removal: This API element is subject to removal in a future version.
    Whether the aggregate should be indexed in Fluxzero's document store (disabled by default).
    int
    snapshotPeriod
    Deprecated, for removal: This API element is subject to removal in a future version.
    Enables snapshotting after a certain number of applied updates.
    String
    timestampPath
    Deprecated, for removal: This API element is subject to removal in a future version.
    Path to extract the main timestamp used in search indexing.

  • Element Details

    • eventSourced

      boolean eventSourced
      Deprecated, for removal: This API element is subject to removal in a future version.
      Whether the aggregate should use event sourcing (enabled by default).

      When enabled, the aggregate is reconstructed from its stored event stream, optionally starting at a snapshot.

      Disabling event sourcing changes the normal load path to current stored state (the searchable document when the aggregate is searchable, otherwise its snapshot). It does not by itself suppress storing or publishing events produced by Apply methods. Event storage and publication remain controlled by eventPublication(), publicationStrategy(), and per-apply overrides.

      Default:
      true

    • ignoreUnknownEvents

      boolean ignoreUnknownEvents
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

    • maxSnapshotCount

      int maxSnapshotCount
      Deprecated, for removal: This API element is subject to removal in a future version.
      Maximum number of snapshots to retain for this aggregate.

      Defaults to 1, which preserves the current behavior of keeping only the most recent snapshot. Use a value greater than 1 to retain older snapshots for historical loading via Entity.previous().

      Values smaller than 1 are treated as 1.

      Default:
      1

    • cached

      boolean cached
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      Sets the event checkpointing frequency for intermediate aggregate states.

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

      Default:
      100

    • commitPolicy

      AggregateCommitPolicy commitPolicy
      Deprecated, for removal: This API element is subject to removal in a future version.
      Controls when aggregate changes are committed and whether multiple commits in the same completion phase may run concurrently.

      The default value resolves from fluxzero.aggregate.commitPolicy when present, then from the active Fluxzero defaults version, and otherwise falls back to AggregateCommitPolicy.SYNC_AFTER_BATCH.

      Default:
      DEFAULT

    • eventPublication

      EventPublication eventPublication
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      Strategy that determines how applied updates are persisted and/or published, and whether publish-only updates advance aggregate state for this aggregate type.

      The default strategy is EventPublicationStrategy.STORE_AND_PUBLISH, unless overridden.

      Default:
      DEFAULT

    • eventRouting

      AggregateEventRouting eventRouting
      Deprecated, for removal: This API element is subject to removal in a future version.
      Controls how events published from this aggregate are assigned to a message segment.

      The default preserves the regular @RoutingKey-based message routing behavior. Use AggregateEventRouting.AGGREGATE_ID to keep all published events for the same aggregate on the segment derived from the aggregate id.

      Default:
      MESSAGE_ROUTING_KEY

    • searchable

      boolean searchable
      Deprecated, for removal: This API element is subject to removal in a future version.
      Whether the aggregate should be indexed in Fluxzero's document store (disabled by default).
      Default:
      false

    • collection

      String collection
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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:
      ""