Interface EventStoreClient

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
InMemoryEventStore, LocalEventStoreClient, WebSocketEventStoreClient
public interface EventStoreClient extends AutoCloseable
Low-level client interface for interacting with the event store in Fluxzero.

This interface provides operations for storing, retrieving, and deleting event streams related to event-sourced aggregates, as well as managing entity relationships such as aggregate references and links.

Users rarely interact with this interface directly. Instead, they typically use higher-level abstractions such as:

This interface is backed either by:

  • a connection to the Fluxzero Runtime using a websocket-based implementation, or
  • an in-memory store used for testing or standalone development purposes.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus>
    awaitModelGraphProjection(io.fluxzero.common.api.modeling.AwaitModelGraphProjection request)
    Completes after every affected root in a graph projection has crossed the requested committed state boundary.
    void
    close()
    Closes the client and releases any open resources or connections.
    default CompletableFuture<io.fluxzero.common.api.modeling.CommitModelsResult>
    commitModels(io.fluxzero.common.api.modeling.CommitModels commit)
    Atomically commits the ordered state transitions of one independent-model commit.
    default CompletableFuture<Void>
    deleteEvents(String aggregateId)
    Deletes all events for a specific aggregate.
    CompletableFuture<Void>
    deleteEvents(String aggregateId, io.fluxzero.common.Guarantee guarantee)
    Deletes all events for a specific aggregate with a given delivery guarantee.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult>
    deleteModel(io.fluxzero.common.api.modeling.DeleteModel request)
    Executes or resumes an idempotent independent-model hard deletion.
    Map<String,String>
    getAggregateIds(io.fluxzero.common.api.modeling.GetAggregateIds request)
    Gets aggregate IDs based on a GetAggregateIds request.
    default Map<String,String>
    getAggregatesFor(String entityId)
    Gets a map of aggregate IDs that reference a given entity ID.
    default AggregateEventStream<io.fluxzero.common.api.SerializedMessage>
    getEvents(String aggregateId)
    Retrieves the full event stream for a given aggregate.
    default AggregateEventStream<io.fluxzero.common.api.SerializedMessage>
    getEvents(String aggregateId, long lastSequenceNumber)
    Retrieves the event stream for an aggregate starting after the given sequence number.
    AggregateEventStream<io.fluxzero.common.api.SerializedMessage>
    getEvents(String aggregateId, long lastSequenceNumber, int maxSize)
    Retrieves the event stream for an aggregate with control over size and offset.
    default io.fluxzero.common.api.modeling.GetModelChangeResult
    getModelChange(io.fluxzero.common.api.modeling.GetModelChange request)
    Resolves the durable targets of one model-commit substep.
    default io.fluxzero.common.api.modeling.GetModelEventsResult
    getModelEvents(io.fluxzero.common.api.modeling.GetModelEvents request)
    Batch-loads independent model heads and event memberships at one pinned state boundary.
    default io.fluxzero.common.api.modeling.GetModelGraphResult
    getModelGraph(io.fluxzero.common.api.modeling.GetModelGraph request)
    Loads one bounded temporal model graph and an optional first page of its grouped model streams.
    default io.fluxzero.common.api.modeling.ModelGraphProjectionStatus
    getModelGraphProjectionStatus(io.fluxzero.common.api.modeling.GetModelGraphProjectionStatus request)
    Returns the current high-watermark and backlog for one materialized graph projection.
    List<io.fluxzero.common.api.modeling.Relationship>
    getRelationships(io.fluxzero.common.api.modeling.GetRelationships request)
    Gets relationships based on a GetRelationships request.
    default List<io.fluxzero.common.api.modeling.Relationship>
    getRelationships(String entityId)
    Gets relationships for the given entity.
    default io.fluxzero.common.api.modeling.ModelDeletionPlan
    planModelDeletion(io.fluxzero.common.api.modeling.PlanModelDeletion request)
    Creates a bounded, non-mutating plan for an explicit independent-model hard deletion.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus>
    registerModelGraphProjection(io.fluxzero.common.api.modeling.RegisterModelGraphProjection request)
    Idempotently registers an asynchronous materialized model-graph projection.
    CompletableFuture<Void>
    repairRelationships(io.fluxzero.common.api.modeling.RepairRelationships request)
    Repairs entity relationships, e.g. by forcing re-evaluation of existing relationships.
    default CompletableFuture<Void>
    storeEvents(String aggregateId, List<io.fluxzero.common.api.SerializedMessage> events, boolean storeOnly)
    Stores a list of serialized events for a given aggregate identifier.
    CompletableFuture<Void>
    storeEvents(String aggregateId, List<io.fluxzero.common.api.SerializedMessage> events, boolean storeOnly, io.fluxzero.common.Guarantee guarantee)
    Stores events for a given aggregate with an explicit guarantee.
    default CompletableFuture<io.fluxzero.common.api.modeling.TrackModelUpdatesResult>
    trackModelUpdates(io.fluxzero.common.api.modeling.TrackModelUpdates request)
    Long-polls committed independent-model commit substeps after a client-controlled state cursor.
    CompletableFuture<Void>
    updateRelationships(io.fluxzero.common.api.modeling.UpdateRelationships request)
    Updates entity relationships in the event store (e.g. parent-child, references).

  • Method Details

    • commitModels

      default CompletableFuture<io.fluxzero.common.api.modeling.CommitModelsResult> commitModels(io.fluxzero.common.api.modeling.CommitModels commit)
      Atomically commits the ordered state transitions of one independent-model commit.

      Unlike aggregate event appends, this operation returns the runtime-assigned state, event, and per-model stream positions. Implementations predating independent models remain source-compatible and fail only when this capability is invoked.

      Parameters:
      commit - complete model commit with its durable idempotency key
      Returns:
      durable result containing the positions assigned by the event store

    • getModelEvents

      default io.fluxzero.common.api.modeling.GetModelEventsResult getModelEvents(io.fluxzero.common.api.modeling.GetModelEvents request)
      Batch-loads independent model heads and event memberships at one pinned state boundary.

    • trackModelUpdates

      default CompletableFuture<io.fluxzero.common.api.modeling.TrackModelUpdatesResult> trackModelUpdates(io.fluxzero.common.api.modeling.TrackModelUpdates request)
      Long-polls committed independent-model commit substeps after a client-controlled state cursor.

    • getModelGraph

      default io.fluxzero.common.api.modeling.GetModelGraphResult getModelGraph(io.fluxzero.common.api.modeling.GetModelGraph request)
      Loads one bounded temporal model graph and an optional first page of its grouped model streams.

    • getModelChange

      default io.fluxzero.common.api.modeling.GetModelChangeResult getModelChange(io.fluxzero.common.api.modeling.GetModelChange request)
      Resolves the durable targets of one model-commit substep.

    • registerModelGraphProjection

      default CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus> registerModelGraphProjection(io.fluxzero.common.api.modeling.RegisterModelGraphProjection request)
      Idempotently registers an asynchronous materialized model-graph projection.

    • getModelGraphProjectionStatus

      default io.fluxzero.common.api.modeling.ModelGraphProjectionStatus getModelGraphProjectionStatus(io.fluxzero.common.api.modeling.GetModelGraphProjectionStatus request)
      Returns the current high-watermark and backlog for one materialized graph projection.

    • awaitModelGraphProjection

      default CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus> awaitModelGraphProjection(io.fluxzero.common.api.modeling.AwaitModelGraphProjection request)
      Completes after every affected root in a graph projection has crossed the requested committed state boundary.

    • planModelDeletion

      default io.fluxzero.common.api.modeling.ModelDeletionPlan planModelDeletion(io.fluxzero.common.api.modeling.PlanModelDeletion request)
      Creates a bounded, non-mutating plan for an explicit independent-model hard deletion.

    • deleteModel

      default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult> deleteModel(io.fluxzero.common.api.modeling.DeleteModel request)
      Executes or resumes an idempotent independent-model hard deletion.

    • storeEvents

      default CompletableFuture<Void> storeEvents(String aggregateId, List<io.fluxzero.common.api.SerializedMessage> events, boolean storeOnly)
      Stores a list of serialized events for a given aggregate identifier.
      Parameters:
      aggregateId - The ID of the aggregate.
      events - The serialized events to store.
      storeOnly - Whether to store the events without publishing them.
      Returns:
      A future that completes when the operation is acknowledged.

    • storeEvents

      CompletableFuture<Void> storeEvents(String aggregateId, List<io.fluxzero.common.api.SerializedMessage> events, boolean storeOnly, io.fluxzero.common.Guarantee guarantee)
      Stores events for a given aggregate with an explicit guarantee.
      Parameters:
      aggregateId - The aggregate ID.
      events - Events to store.
      storeOnly - If true, events will not be published.
      guarantee - The guarantee level for this operation.
      Returns:
      A future representing completion of the store operation.

    • getEvents

      default AggregateEventStream<io.fluxzero.common.api.SerializedMessage> getEvents(String aggregateId)
      Retrieves the full event stream for a given aggregate.
      Parameters:
      aggregateId - The aggregate ID.
      Returns:
      A stream of serialized events.

    • getEvents

      default AggregateEventStream<io.fluxzero.common.api.SerializedMessage> getEvents(String aggregateId, long lastSequenceNumber)
      Retrieves the event stream for an aggregate starting after the given sequence number.
      Parameters:
      aggregateId - The aggregate ID.
      lastSequenceNumber - The sequence number to start from (exclusive).
      Returns:
      A stream of serialized events.

    • getEvents

      AggregateEventStream<io.fluxzero.common.api.SerializedMessage> getEvents(String aggregateId, long lastSequenceNumber, int maxSize)
      Retrieves the event stream for an aggregate with control over size and offset.
      Parameters:
      aggregateId - The aggregate ID.
      lastSequenceNumber - Sequence number to resume after.
      maxSize - Maximum number of events to return (or -1 for unlimited).
      Returns:
      A stream of serialized events.

    • deleteEvents

      default CompletableFuture<Void> deleteEvents(String aggregateId)
      Deletes all events for a specific aggregate.
      Parameters:
      aggregateId - The aggregate ID.
      Returns:
      A future that completes when deletion is acknowledged.

    • deleteEvents

      CompletableFuture<Void> deleteEvents(String aggregateId, io.fluxzero.common.Guarantee guarantee)
      Deletes all events for a specific aggregate with a given delivery guarantee.
      Parameters:
      aggregateId - The aggregate ID.
      guarantee - The guarantee to apply.
      Returns:
      A future that completes when deletion is acknowledged.

    • updateRelationships

      CompletableFuture<Void> updateRelationships(io.fluxzero.common.api.modeling.UpdateRelationships request)
      Updates entity relationships in the event store (e.g. parent-child, references).
      Parameters:
      request - The update request.
      Returns:
      A future that completes when the operation is acknowledged.

    • repairRelationships

      CompletableFuture<Void> repairRelationships(io.fluxzero.common.api.modeling.RepairRelationships request)
      Repairs entity relationships, e.g. by forcing re-evaluation of existing relationships.
      Parameters:
      request - The repair request.
      Returns:
      A future that completes when the repair is done.

    • getAggregatesFor

      default Map<String,String> getAggregatesFor(String entityId)
      Gets a map of aggregate IDs that reference a given entity ID.
      Parameters:
      entityId - The entity identifier.
      Returns:
      A map of aggregate IDs and corresponding reference names.

    • getAggregateIds

      Map<String,String> getAggregateIds(io.fluxzero.common.api.modeling.GetAggregateIds request)
      Gets aggregate IDs based on a GetAggregateIds request.
      Parameters:
      request - The request containing filtering options.
      Returns:
      A map of aggregate IDs referencing the target entity.

    • getRelationships

      default List<io.fluxzero.common.api.modeling.Relationship> getRelationships(String entityId)
      Gets relationships for the given entity.
      Parameters:
      entityId - The entity ID.
      Returns:
      A list of matching relationships.

    • getRelationships

      List<io.fluxzero.common.api.modeling.Relationship> getRelationships(io.fluxzero.common.api.modeling.GetRelationships request)
      Gets relationships based on a GetRelationships request.
      Parameters:
      request - The request containing filter parameters.
      Returns:
      A list of matching relationships.

    • close

      void close()
      Closes the client and releases any open resources or connections.
      Specified by:
      close in interface AutoCloseable