Class LocalTrackingClient

java.lang.Object
io.fluxzero.sdk.tracking.client.LocalTrackingClient
All Implemented Interfaces:
Monitored<List<SerializedMessage>>, HasMessageStore, GatewayClient, TrackingClient, AutoCloseable
Direct Known Subclasses:
LocalEventStoreClient, LocalSchedulingClient
public class LocalTrackingClient extends Object implements TrackingClient, GatewayClient, HasMessageStore
In-memory implementation of the TrackingClient and GatewayClient interfaces, designed for local-only or test-time usage.

This client simulates message tracking behavior without requiring a live Fluxzero backend. It uses local data structures to emulate:

Use Cases

  • Unit tests or integration tests involving command/event/query handling
  • Local development without using Fluxzero Runtime as a backend
  • Custom tooling that simulates tracking or playback behavior

Behavior

  • Messages are stored in memory and may be optionally expired using messageExpiration if configured
  • Tracks per-consumer positions independently via an in-memory position store
  • Implements segment claiming and disconnection logic to simulate parallel consumer behavior
  • Supports custom topics for MessageType.CUSTOM or MessageType.DOCUMENT

Example

TrackingClient testClient = new LocalTrackingClient(MessageType.EVENT, "test-topic", Duration.ofMinutes(10));
See Also:

  • Constructor Details

  • Method Details

    • registerMonitor

      public Registration registerMonitor(Consumer<List<SerializedMessage>> monitor)
      Description copied from interface: Monitored
      Registers a monitor that will be notified when an activity of type T occurs.
      Specified by:
      registerMonitor in interface Monitored<List<SerializedMessage>>
      Parameters:
      monitor - the callback to invoke with each observed value
      Returns:
      a Registration that can be used to cancel the monitoring

    • append

      public CompletableFuture<Void> append(Guarantee guarantee, SerializedMessage... messages)
      Description copied from interface: GatewayClient
      Append the given messages to the gateway, applying the given delivery Guarantee.
      Specified by:
      append in interface GatewayClient
      Parameters:
      guarantee - the delivery guarantee that should be respected (e.g. at-most-once, at-least-once)
      messages - one or more serialized messages to append
      Returns:
      a CompletableFuture that completes when the append operation is successful or fails if delivery fails

    • setRetentionTime

      public CompletableFuture<Void> setRetentionTime(Duration duration, Guarantee guarantee)
      Description copied from interface: GatewayClient
      Set a new retention duration for the underlying gateway's message log.

      The retention setting determines how long messages in this log are retained by the system, after which they may be evicted or deleted depending on the platform policy.

      Specified by:
      setRetentionTime in interface GatewayClient
      Parameters:
      duration - the new retention duration
      guarantee - the delivery guarantee to apply to the update operation
      Returns:
      a CompletableFuture that completes once the retention setting is updated

    • read

      public CompletableFuture<MessageBatch> read(String trackerId, Long lastIndex, ConsumerConfiguration config)
      Description copied from interface: TrackingClient
      Asynchronously reads the next available MessageBatch for a given tracker.
      Specified by:
      read in interface TrackingClient
      Parameters:
      trackerId - the unique ID for the tracker thread requesting messages
      lastIndex - the last index successfully handled by this tracker
      config - the full configuration for the consumer
      Returns:
      a CompletableFuture that completes with the next batch of messages

    • readFromIndex

      public List<SerializedMessage> readFromIndex(long minIndex, int maxSize)
      Description copied from interface: TrackingClient
      Fetches messages starting from the given index up to the provided max size.

      This method bypasses consumer configurations and is primarily used for diagnostics or reprocessing.

      Specified by:
      readFromIndex in interface TrackingClient
      Parameters:
      minIndex - the starting index (inclusive)
      maxSize - the maximum number of messages to retrieve
      Returns:
      a list of serialized messages starting at the given index

    • claimSegment

      public CompletableFuture<ClaimSegmentResult> claimSegment(String trackerId, Long lastIndex, ConsumerConfiguration config)
      Description copied from interface: TrackingClient
      Claims a processing segment for the given tracker.

      Segments are used to partition the message log among multiple tracker threads for parallel processing.

      Specified by:
      claimSegment in interface TrackingClient
      Parameters:
      trackerId - the unique identifier of the tracker attempting to claim a segment
      lastIndex - the tracker's last successfully processed index
      config - the full consumer configuration
      Returns:
      a CompletableFuture resolving to the result of the claim

    • storePosition

      public CompletableFuture<Void> storePosition(String consumer, int[] segment, long lastIndex, Guarantee guarantee)
      Description copied from interface: TrackingClient
      Stores the last successfully processed position for a consumer with a specific delivery guarantee.
      Specified by:
      storePosition in interface TrackingClient
      Parameters:
      consumer - the name of the consumer
      segment - the segment the tracker is processing
      lastIndex - the last message index processed
      guarantee - delivery guarantee (e.g., STORED, SENT)
      Returns:
      a future indicating completion

    • resetPosition

      public CompletableFuture<Void> resetPosition(String consumer, long lastIndex, Guarantee guarantee)
      Description copied from interface: TrackingClient
      Resets the consumer's tracking position to a given index with a specific delivery guarantee.
      Specified by:
      resetPosition in interface TrackingClient
      Parameters:
      consumer - the name of the consumer
      lastIndex - the new index to start from
      guarantee - the delivery guarantee
      Returns:
      a future indicating completion

    • getPosition

      public Position getPosition(String consumer)
      Description copied from interface: TrackingClient
      Returns the current committed tracking position for the given consumer.
      Specified by:
      getPosition in interface TrackingClient
      Parameters:
      consumer - the name of the consumer
      Returns:
      the last known committed position

    • disconnectTracker

      public CompletableFuture<Void> disconnectTracker(String consumer, String trackerId, boolean sendFinalEmptyBatch, Guarantee guarantee)
      Description copied from interface: TrackingClient
      Disconnects the specified tracker from its segment with the specified delivery guarantee.
      Specified by:
      disconnectTracker in interface TrackingClient
      Parameters:
      consumer - the name of the consumer group
      trackerId - the ID of the tracker thread being disconnected
      sendFinalEmptyBatch - whether to send a final empty batch to commit state
      guarantee - the delivery guarantee to use
      Returns:
      a future indicating disconnection

    • close

      public void close()
      Description copied from interface: TrackingClient
      Closes any open resources associated with this client.

      Once closed, the client should no longer be used to fetch or commit tracking state.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface GatewayClient
      Specified by:
      close in interface TrackingClient