Interface Tracker

All Superinterfaces:
Comparable<Tracker>
All Known Implementing Classes:
SimpleTracker, WebSocketTracker

public interface Tracker extends Comparable<Tracker>
A Tracker represents an active consumer of messages for a particular ConsumerConfiguration.

Trackers are responsible for handling a range of message segments and coordinating how and when messages are delivered from the MessageStore or other sources. They are typically managed by a TrackingStrategy.

Each tracker identifies a specific consumer (via getConsumerName()) and client instance (via getClientId()), and may support additional filtering by message type or target.

Responsibilities

A Tracker is responsible for:
  • Receiving batches of messages via send(MessageBatch)
  • Declaring the range of segments it is responsible for
  • Filtering messages by type, target, and segment hash
  • Tracking its last consumed index and activity deadline

Trackers may also participate in client-controlled index tracking, message purging, and deadline-based disconnection.

  • Field Details

    • comparator

      static final Comparator<Tracker> comparator
      Default comparator based on consumer name and tracker ID.
  • Method Details

    • getConsumerName

      String getConsumerName()
      Returns:
      the logical name of the consumer this tracker belongs to.
    • getClientId

      String getClientId()
      Returns:
      the unique ID of the client, typically one per client application instance.
    • getTrackerId

      String getTrackerId()
      Returns:
      the unique ID of this tracker instance.
    • getLastTrackerIndex

      Long getLastTrackerIndex()
      Returns:
      the index of the last successfully consumed message, or null if uninitialized.
    • getMaxSize

      int getMaxSize()
      Returns:
      the maximum number of messages this tracker wants to consume in a single batch.
    • getDeadline

      long getDeadline()
      Returns:
      the system deadline (epoch millis) by which this tracker expects a new batch. If this deadline is missed, the tracker should be given an empty batch.
    • maxTimeout

      long maxTimeout()
      Returns:
      the maximum time window (in millis) after which a batch should be delivered even if no messages are available.
    • getPurgeDelay

      Long getPurgeDelay()
      Returns:
      the optional duration (in milliseconds) after which this tracker may be purged if it is actively processing messages (i.e., not idle or waiting).

      This mechanism ensures that stale trackers are eventually cleaned up, particularly in scenarios where graceful disconnection is not guaranteed. This is especially relevant for external trackers — such as non-Java applications or clients not using Flux’s built-in client — which may not send an explicit disconnect.

      In normal Flux client usage, purging should rarely occur, as disconnection is managed by the client.

    • isFilterMessageTarget

      default boolean isFilterMessageTarget()
      Returns:
      true if the tracker should only receive messages that explicitly target its client ID.

      When enabled, this filter ensures that only messages with a target matching getClientId() are considered valid. This can be useful for isolating messages meant for a specific client.

      When disabled (the default), all messages in the segment range are considered, regardless of their target.

    • ignoreSegment

      boolean ignoreSegment()
      Returns:
      true if this tracker ignores segment-based filtering (i.e. processes all segments).
    • clientControlledIndex

      boolean clientControlledIndex()
      Returns:
      true if this tracker uses client-controlled index tracking (instead of store-side indexing).
    • singleTracker

      default boolean singleTracker()
      Returns:
      true if this tracker is the only one allowed to handle messages for its consumer. This is useful for single-tracker consumer configurations.
    • getTypeFilter

      default Predicate<String> getTypeFilter()
      Returns a predicate for filtering messages based on their type (class name).
      Returns:
      a type filter predicate. By default, allows all types.
    • send

      void send(MessageBatch batch)
      Sends a batch of messages to this tracker.
      Parameters:
      batch - the batch to deliver
    • sendEmptyBatch

      default void sendEmptyBatch(MessageBatch batch)
      Sends an empty batch (typically used to signal idle or shutdown). Default implementation forwards to send(MessageBatch).
      Parameters:
      batch - an empty batch instance
    • withLastTrackerIndex

      Tracker withLastTrackerIndex(Long lastTrackerIndex)
      Returns a copy of this tracker with its last index updated.
      Parameters:
      lastTrackerIndex - the new index value
      Returns:
      a modified tracker instance
    • canHandle

      default boolean canHandle(SerializedMessage message, int[] segmentRange)
      Checks if the given message can be handled by this tracker based on segment range and type filtering.
      Parameters:
      message - the message to check
      segmentRange - the range of segments this tracker is assigned to
      Returns:
      true if the message is valid for this tracker
    • hasMissedDeadline

      default boolean hasMissedDeadline()
      Returns:
      true if this tracker has missed its deadline.
    • compareTo

      default int compareTo(Tracker o)
      Compares trackers based on consumer and tracker IDs for stable sorting.
      Specified by:
      compareTo in interface Comparable<Tracker>