Package io.fluxcapacitor.javaclient.persisting.repository

Class CachingAggregateRepository

java.lang.Object
io.fluxcapacitor.javaclient.persisting.repository.CachingAggregateRepository
All Implemented Interfaces:
AggregateRepository
public class CachingAggregateRepository extends Object implements AggregateRepository
A wrapper around a delegate AggregateRepository that ensures cached aggregates stay in sync with the event log.

This repository starts an internal TrackingClient that tails the global event log. It deserializes received events and applies them to any corresponding aggregate in the cache, thereby ensuring that all cached aggregates reflect the latest known state.

This design makes it possible to load up-to-date aggregates within event and notification handlers, allowing these types of handlers to rely on the event model as a read model. This enables event-sourced read models without requiring the developer to maintain separate query-oriented state.

Specifically, when an event handler loads an aggregate, the repository first ensures that all events up to and including the event being handled have been processed by the tracker and applied to the cache. This prevents race conditions and stale reads.

If a cache miss occurs, the aggregate is loaded from the delegate repository and cached for future access.

Features

  • Transparent event replay on cached aggregates.
  • Ensures correct ordering and consistency during event handling via index synchronization.
  • Relationship metadata is kept up to date using Relationship updates.
  • Configurable slow-tracking detection via slowTrackingThreshold (default 10 seconds).

This caching repository is enabled by default in all Flux Capacitor applications to support aggregate access during event processing. If needed, it can be disabled using FluxCapacitorBuilder.disableAutomaticAggregateCaching(), in which case aggregate state will not be tracked or kept in sync automatically, and developers are expected to manage consistency manually.

See Also:

  • Field Details

    • slowTrackingThreshold

      public static Duration slowTrackingThreshold

  • Constructor Details

    • CachingAggregateRepository

      public CachingAggregateRepository()

  • Method Details

    • load

      public <T> Entity<T> load(@NonNull @NonNull Object aggregateId, Class<T> type)
      Description copied from interface: AggregateRepository
      Load an aggregate by its identifier and type.
      Specified by:
      load in interface AggregateRepository
      Type Parameters:
      T - the aggregate type.
      Parameters:
      aggregateId - the aggregate identifier.
      type - the expected class type.
      Returns:
      the loaded aggregate wrapped in an Entity.

    • loadFor

      public <T> Entity<T> loadFor(@NonNull @NonNull Object entityId, Class<?> defaultType)
      Description copied from interface: AggregateRepository
      Load the aggregate that owns the specified entity.

      If no ownership is found in the relationship index, this method may fall back to loading the entity as if it were an aggregate itself.

      Specified by:
      loadFor in interface AggregateRepository
      Type Parameters:
      T - the aggregate type.
      Parameters:
      entityId - the child or nested entity.
      defaultType - fallback type to use when no aggregate mapping is available.
      Returns:
      the loaded aggregate as an Entity.

    • asEntity

      public <T> Entity<T> asEntity(T entityId)
      Description copied from interface: AggregateRepository
      Wrap an existing aggregate instance into an Entity, initializing tracking and identity information.
      Specified by:
      asEntity in interface AggregateRepository
      Type Parameters:
      T - the aggregate type.
      Parameters:
      entityId - the aggregate instance.
      Returns:
      the entity wrapper.

    • repairRelationships

      public CompletableFuture<Void> repairRelationships(Entity<?> aggregate)
      Description copied from interface: AggregateRepository
      Repairs the internal relationship model for a loaded aggregate.

      This is useful when refactoring entity hierarchies or recovering from inconsistent relationship state.

      Specified by:
      repairRelationships in interface AggregateRepository
      Parameters:
      aggregate - the aggregate to inspect.
      Returns:
      a future that completes when the relationships are updated.

    • getAggregatesFor

      public Map<String,Class<?>> getAggregatesFor(Object entityId)
      Description copied from interface: AggregateRepository
      Returns a map of aggregate IDs and their types that are associated with a given entity ID.
      Specified by:
      getAggregatesFor in interface AggregateRepository
      Parameters:
      entityId - the child or nested entity.
      Returns:
      a map of aggregate IDs to class names.

    • deleteAggregate

      public CompletableFuture<Void> deleteAggregate(Object aggregateId)
      Description copied from interface: AggregateRepository
      Deletes the persisted state for an aggregate, including its events or document and relationships.
      Specified by:
      deleteAggregate in interface AggregateRepository
      Parameters:
      aggregateId - the ID of the aggregate to delete.
      Returns:
      a future that completes when deletion has been confirmed.

    • handleEvents

      protected void handleEvents(List<SerializedMessage> messages)

    • updateRelationships

      protected void updateRelationships(Entity<?> before, Entity<?> after)

    • catchUpIfNeeded

      protected void catchUpIfNeeded()

    • startTrackerIfNeeded

      protected void startTrackerIfNeeded()