Class WebSocketEventStoreClient

java.lang.Object
io.fluxzero.sdk.common.websocket.AbstractWebsocketClient
io.fluxzero.sdk.persisting.eventsourcing.client.WebSocketEventStoreClient
All Implemented Interfaces:
WebsocketEndpoint, EventStoreClient, ModelCommitBatchingClient, AutoCloseable
public class WebSocketEventStoreClient extends AbstractWebsocketClient implements EventStoreClient, ModelCommitBatchingClient
WebSocket-based implementation of the EventStoreClient, enabling interaction with the Fluxzero Runtime's event store via a persistent WebSocket connection.

This implementation supports:

  • Storing events for event-sourced aggregates
  • Efficient, paginated retrieval of aggregate event streams
  • Deleting aggregate event streams
  • Maintaining aggregate/entity relationships

The fetchBatchSize setting controls how many events are fetched per paginated request when loading an aggregate's event history. This ensures efficient memory usage while still supporting large aggregates.

End users rarely interact with this client directly. Instead, they typically use higher-level abstractions such as EventStore or AggregateRepository.

See Also:

  • Constructor Details

    • WebSocketEventStoreClient

      public WebSocketEventStoreClient(String endPointUrl, WebSocketClient client)
      Creates a new WebSocketEventStoreClient with a default batch size of 8192.
      Parameters:
      endPointUrl - The URL to the Fluxzero Runtime event sourcing endpoint.
      client - The WebSocket client instance.

    • WebSocketEventStoreClient

      public WebSocketEventStoreClient(URI endPointUri, int fetchBatchSize, WebSocketClient client)
      Creates a new WebSocketEventStoreClient with a specified batch size.
      Parameters:
      endPointUri - The URI to the event store endpoint.
      fetchBatchSize - Maximum number of events to retrieve per page.
      client - The WebSocket client.

    • WebSocketEventStoreClient

      public WebSocketEventStoreClient(URI endPointUri, int fetchBatchSize, WebSocketClient client, boolean sendMetrics)
      Constructs the WebSocket client with full customization.
      Parameters:
      endPointUri - URI of the event sourcing endpoint.
      fetchBatchSize - The size of event batches fetched from the server.
      client - The WebSocket client.
      sendMetrics - Whether to send metrics to the Fluxzero Runtime.

  • Method Details

    • payloadCodecs

      protected List<? extends io.fluxzero.common.websocket.WebSocketPayloadCodec> payloadCodecs()
      Description copied from class: AbstractWebsocketClient
      Returns compact payload codecs owned by this concrete protocol client.
      Overrides:
      payloadCodecs in class AbstractWebsocketClient

    • maxRequestBatchSize

      protected int maxRequestBatchSize(List<io.fluxzero.common.api.Request> requests)
      Description copied from class: AbstractWebsocketClient
      Returns the maximum transport chunk for the supplied requests.
      Overrides:
      maxRequestBatchSize in class AbstractWebsocketClient

    • startRequestBatchEvent

      protected io.fluxzero.common.jfr.FluxzeroJfr.Batch startRequestBatchEvent(List<io.fluxzero.common.api.Request> requests)
      Description copied from class: AbstractWebsocketClient
      Starts an optional request-batch event owned by the concrete protocol client.
      Overrides:
      startRequestBatchEvent in class AbstractWebsocketClient

    • jfrResultType

      protected String jfrResultType(List<io.fluxzero.common.api.RequestResult> results)
      Description copied from class: AbstractWebsocketClient
      Classifies decoded results for optional protocol-specific JFR diagnostics.
      Overrides:
      jfrResultType in class AbstractWebsocketClient

    • storeEvents

      public CompletableFuture<Void> storeEvents(String aggregateId, List<io.fluxzero.common.api.SerializedMessage> events, boolean storeOnly, io.fluxzero.common.Guarantee guarantee)
      Stores events for a specific aggregate, with control over store-only mode and delivery guarantee.
      Specified by:
      storeEvents in interface EventStoreClient
      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.

    • commitModels

      public CompletableFuture<io.fluxzero.common.api.modeling.CommitModelsResult> commitModels(io.fluxzero.common.api.modeling.CommitModels commit)
      Commits an independent-model commit and retains the positions returned by the runtime.
      Specified by:
      commitModels in interface EventStoreClient
      Parameters:
      commit - complete model commit with its durable idempotency key
      Returns:
      durable result containing the positions assigned by the event store

    • beginModelCommitBatch

      public ModelCommitBatchingClient.ModelCommitBatch beginModelCommitBatch(int capacity)
      Specified by:
      beginModelCommitBatch in interface ModelCommitBatchingClient

    • beginReadyModelCommitBatch

      public ModelCommitBatchingClient.ModelCommitBatch beginReadyModelCommitBatch()
      Description copied from interface: ModelCommitBatchingClient
      Begins a transport batch for commits that become ready independently during handler execution.

      Unlike ModelCommitBatchingClient.beginModelCommitBatch(int), this batch does not imply that commit execution waits for the batch boundary. Implementations may release bounded full chunks immediately and use ModelCommitBatchingClient.ModelCommitBatch.flush() only to release the remaining tail. Returning null retains individual commit transport.

      Specified by:
      beginReadyModelCommitBatch in interface ModelCommitBatchingClient

    • prepareResults

      protected CompletableFuture<Void> prepareResults(List<io.fluxzero.common.api.RequestResult> results, List<Object> requestContexts)
      Description copied from class: AbstractWebsocketClient
      Allows a specialized client to complete request-owned work for a decoded result group before individual request futures are released.
      Overrides:
      prepareResults in class AbstractWebsocketClient

    • restoreResultContext

      protected List<io.fluxzero.common.api.RequestResult> restoreResultContext(List<io.fluxzero.common.api.RequestResult> results)
      Description copied from class: AbstractWebsocketClient
      Restores request-owned context that a specialized compact response deliberately omits from the wire.
      Overrides:
      restoreResultContext in class AbstractWebsocketClient

    • getModelEvents

      public io.fluxzero.common.api.modeling.GetModelEventsResult getModelEvents(io.fluxzero.common.api.modeling.GetModelEvents request)
      Description copied from interface: EventStoreClient
      Batch-loads independent model heads and event memberships at one pinned state boundary.
      Specified by:
      getModelEvents in interface EventStoreClient

    • trackModelUpdates

      public CompletableFuture<io.fluxzero.common.api.modeling.TrackModelUpdatesResult> trackModelUpdates(io.fluxzero.common.api.modeling.TrackModelUpdates request)
      Description copied from interface: EventStoreClient
      Long-polls committed independent-model commit substeps after a client-controlled state cursor.
      Specified by:
      trackModelUpdates in interface EventStoreClient

    • getModelGraph

      public io.fluxzero.common.api.modeling.GetModelGraphResult getModelGraph(io.fluxzero.common.api.modeling.GetModelGraph request)
      Description copied from interface: EventStoreClient
      Loads one bounded temporal model graph and an optional first page of its grouped model streams.
      Specified by:
      getModelGraph in interface EventStoreClient

    • getModelChange

      public io.fluxzero.common.api.modeling.GetModelChangeResult getModelChange(io.fluxzero.common.api.modeling.GetModelChange request)
      Description copied from interface: EventStoreClient
      Resolves the durable targets of one model-commit substep.
      Specified by:
      getModelChange in interface EventStoreClient

    • registerModelGraphProjection

      public CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus> registerModelGraphProjection(io.fluxzero.common.api.modeling.RegisterModelGraphProjection request)
      Description copied from interface: EventStoreClient
      Idempotently registers an asynchronous materialized model-graph projection.
      Specified by:
      registerModelGraphProjection in interface EventStoreClient

    • getModelGraphProjectionStatus

      public io.fluxzero.common.api.modeling.ModelGraphProjectionStatus getModelGraphProjectionStatus(io.fluxzero.common.api.modeling.GetModelGraphProjectionStatus request)
      Description copied from interface: EventStoreClient
      Returns the current high-watermark and backlog for one materialized graph projection.
      Specified by:
      getModelGraphProjectionStatus in interface EventStoreClient

    • awaitModelGraphProjection

      public CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus> awaitModelGraphProjection(io.fluxzero.common.api.modeling.AwaitModelGraphProjection request)
      Description copied from interface: EventStoreClient
      Completes after every affected root in a graph projection has crossed the requested committed state boundary.
      Specified by:
      awaitModelGraphProjection in interface EventStoreClient

    • planModelDeletion

      public io.fluxzero.common.api.modeling.ModelDeletionPlan planModelDeletion(io.fluxzero.common.api.modeling.PlanModelDeletion request)
      Description copied from interface: EventStoreClient
      Creates a bounded, non-mutating plan for an explicit independent-model hard deletion.
      Specified by:
      planModelDeletion in interface EventStoreClient

    • deleteModel

      public CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult> deleteModel(io.fluxzero.common.api.modeling.DeleteModel request)
      Description copied from interface: EventStoreClient
      Executes or resumes an idempotent independent-model hard deletion.
      Specified by:
      deleteModel in interface EventStoreClient

    • getEvents

      public AggregateEventStream<io.fluxzero.common.api.SerializedMessage> getEvents(String aggregateId, long lastSequenceNumber, int maxSize)
      Retrieves events for a specific aggregate starting after a given sequence number, optionally limiting the result size.
      Specified by:
      getEvents in interface EventStoreClient
      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.

    • updateRelationships

      public CompletableFuture<Void> updateRelationships(io.fluxzero.common.api.modeling.UpdateRelationships request)
      Sends a request to update the relationships of an entity or aggregate.
      Specified by:
      updateRelationships in interface EventStoreClient
      Parameters:
      request - The update request.
      Returns:
      A future that completes when the operation is acknowledged.

    • repairRelationships

      public CompletableFuture<Void> repairRelationships(io.fluxzero.common.api.modeling.RepairRelationships request)
      Sends a request to repair relationships for a specific entity.
      Specified by:
      repairRelationships in interface EventStoreClient
      Parameters:
      request - The repair request.
      Returns:
      A future that completes when the repair is done.

    • getAggregateIds

      public Map<String,String> getAggregateIds(io.fluxzero.common.api.modeling.GetAggregateIds request)
      Retrieves a map of aggregate IDs associated with a given entity, using a GetAggregateIds request.
      Specified by:
      getAggregateIds in interface EventStoreClient
      Parameters:
      request - The request containing filtering options.
      Returns:
      A map of aggregate IDs referencing the target entity.

    • getRelationships

      public List<io.fluxzero.common.api.modeling.Relationship> getRelationships(io.fluxzero.common.api.modeling.GetRelationships request)
      Retrieves all relationships for a given entity, using a GetRelationships request.
      Specified by:
      getRelationships in interface EventStoreClient
      Parameters:
      request - The request containing filter parameters.
      Returns:
      A list of matching relationships.

    • deleteEvents

      public CompletableFuture<Void> deleteEvents(String aggregateId, io.fluxzero.common.Guarantee guarantee)
      Sends a delete command for the event stream of the specified aggregate.
      Specified by:
      deleteEvents in interface EventStoreClient
      Parameters:
      aggregateId - The aggregate ID.
      guarantee - The guarantee to apply.
      Returns:
      A future that completes when deletion is acknowledged.