Package io.fluxcapacitor.javaclient.tracking.client

Interface TrackingClient

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
CachingTrackingClient, LocalEventStoreClient, LocalSchedulingClient, LocalTrackingClient, WebsocketTrackingClient
public interface TrackingClient extends AutoCloseable
Low-level client interface for tracking and consuming messages from a message log.

A TrackingClient is responsible for retrieving message batches, claiming processing segments, and managing tracking positions for a named consumer. Implementations typically include:

  • An in-memory version for testing scenarios
  • A WebSocket-backed implementation for connecting to the Flux Capacitor platform

Each message type (e.g., command, event, query) is backed by its own TrackingClient instance, allowing independent consumption streams and tracking state.

See Also:

  • Method Details

    • readAndWait

      default MessageBatch readAndWait(String trackerId, Long lastIndex, ConsumerConfiguration configuration)
      Reads the next available MessageBatch for the given tracker and blocks until messages are available.

      This is a convenience method that synchronously waits for read(java.lang.String, java.lang.Long, io.fluxcapacitor.javaclient.tracking.ConsumerConfiguration) to complete.

      Parameters:
      trackerId - the unique identifier of the tracker requesting messages
      lastIndex - the last successfully processed index
      configuration - the consumer configuration that determines segment, filters, and batch settings
      Returns:
      the next available message batch (may be empty if disconnected)

    • read

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

    • readFromIndex

      List<SerializedMessage> readFromIndex(long minIndex, int maxSize)
      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.

      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

      CompletableFuture<ClaimSegmentResult> claimSegment(String trackerId, Long lastIndex, ConsumerConfiguration config)
      Claims a processing segment for the given tracker.

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

      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

      default CompletableFuture<Void> storePosition(String consumer, int[] segment, long lastIndex)
      Stores the last successfully processed position for a consumer.

      Default implementation uses Guarantee.STORED as the delivery guarantee.

      Parameters:
      consumer - the name of the consumer
      segment - the segment the tracker is processing
      lastIndex - the index up to which messages have been handled
      Returns:
      a future indicating completion

    • storePosition

      CompletableFuture<Void> storePosition(String consumer, int[] segment, long lastIndex, Guarantee guarantee)
      Stores the last successfully processed position for a consumer with a specific delivery guarantee.
      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

      default CompletableFuture<Void> resetPosition(String consumer, long lastIndex)
      Resets the consumer's tracking position to a given index.

      This is often used for replay, diagnostics, or recovery scenarios. Uses Guarantee.STORED by default.

      Parameters:
      consumer - the name of the consumer
      lastIndex - the new index to start from
      Returns:
      a future indicating completion

    • resetPosition

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

    • getPosition

      Position getPosition(String consumer)
      Returns the current committed tracking position for the given consumer.
      Parameters:
      consumer - the name of the consumer
      Returns:
      the last known committed position

    • disconnectTracker

      default CompletableFuture<Void> disconnectTracker(String consumer, String trackerId, boolean sendFinalEmptyBatch)
      Disconnects the specified tracker from its segment and optionally sends an empty final batch.

      Default implementation uses Guarantee.SENT.

      Parameters:
      consumer - the name of the consumer group
      trackerId - the ID of the tracker thread being disconnected
      sendFinalEmptyBatch - whether to send an empty batch to flush tracking state
      Returns:
      a future indicating disconnection

    • disconnectTracker

      CompletableFuture<Void> disconnectTracker(String consumer, String trackerId, boolean sendFinalEmptyBatch, Guarantee guarantee)
      Disconnects the specified tracker from its segment with the specified delivery guarantee.
      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

    • getMessageType

      MessageType getMessageType()
      Returns the MessageType (e.g., COMMAND, EVENT, QUERY) associated with this tracking client.
      Returns:
      the message type

    • getTopic

      String getTopic()
      Returns the topic associated with this tracking client.

      This is applicable only when getMessageType() is MessageType.DOCUMENT or MessageType.CUSTOM, where messages are organized into named topics beyond the standard type-based categorization.

      For other MessageTypes (e.g., COMMAND, EVENT), the concept of a topic is implicit and not required for tracking.

      Returns:
      the topic name, or null if not applicable for the message type

    • close

      void close()
      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