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

    • readFromIndex

      public List<SerializedMessage> readFromIndex(long minIndex, int maxSize, long maxBytes)
      Description copied from interface: TrackingClient
      Fetches messages directly from the message log while limiting both message count and serialized payload bytes.

      If the first available message is larger than maxBytes, it is still returned so consumers can make progress. A maxBytes value of 0 disables the byte limit.

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

    • readRange

      public List<SerializedMessage> readRange(long minIndexInclusive, long maxIndexExclusive, int maxSize)
      Description copied from interface: TrackingClient
      Fetches messages in the range [minIndexInclusive, maxIndexExclusive) up to the provided max size.

      Implementations may override this to perform a bounded server-side range read. The default implementation keeps the wire protocol backward compatible by using TrackingClient.readFromIndex(long, int) and filtering locally.

      Specified by:
      readRange in interface TrackingClient
      Parameters:
      minIndexInclusive - the starting index (inclusive)
      maxIndexExclusive - the maximum index (exclusive)
      maxSize - the maximum number of messages to retrieve
      Returns:
      a list of serialized messages in the requested range

    • readRange

      public List<SerializedMessage> readRange(long minIndexInclusive, long maxIndexExclusive, int maxSize, long maxBytes)
      Description copied from interface: TrackingClient
      Fetches messages in the range [minIndexInclusive, maxIndexExclusive) while limiting both message count and serialized payload bytes.
      Specified by:
      readRange in interface TrackingClient
      Parameters:
      minIndexInclusive - the starting index (inclusive)
      maxIndexExclusive - the maximum index (exclusive)
      maxSize - the maximum number of messages to retrieve
      maxBytes - the maximum number of serialized payload bytes to retrieve
      Returns:
      a list of serialized messages in the requested range

    • 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

    • truncate

      public CompletableFuture<Void> truncate(Guarantee guarantee)
      Description copied from interface: GatewayClient
      Truncates the underlying gateway's message log and clears its tracking positions.
      Specified by:
      truncate in interface GatewayClient
      Parameters:
      guarantee - the delivery guarantee to apply to the truncate operation
      Returns:
      a CompletableFuture that completes once the log is truncated

    • 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