Package org.mcpjava.server.progress

Interface ProgressTracker

public interface ProgressTracker
Tracks progress updates and sends notifications to the client.

This interface provides a thread-safe, stateful way to track and report progress for long-running operations. It maintains the current progress value and can automatically send notifications to the client.

Implementations must be thread-safe and may be used concurrently.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    ProgressTracker.Builder
    Builder for creating progress trackers.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    advance(BigDecimal value)
    Advances the progress by the specified value and sends a notification asynchronously.
    default void
    advanceAndForget()
    Advances the progress by the default step and sends a notification without waiting.
    default void
    advanceAndForget(double value)
    Advances the progress by the specified value and sends a notification without waiting.
    default void
    advanceAndForget(long value)
    Advances the progress by the specified value and sends a notification without waiting.
    void
    advanceAndForget(BigDecimal value)
    Advances the progress by the specified value and sends a notification without waiting.
    BigDecimal
    progress()
    Gets the current progress value.
    BigDecimal
    step()
    Gets the default step value used by advanceAndForget().
    ProgressToken
    token()
    Gets the original progress token from the request.
    Optional<BigDecimal>
    total()
    Gets the expected total value.

  • Method Details

    • token

      ProgressToken token()
      Gets the original progress token from the request.
      Returns:
      the progress token

    • advanceAndForget

      void advanceAndForget(BigDecimal value)
      Advances the progress by the specified value and sends a notification without waiting.

      This is a fire-and-forget operation that can be called from any thread.

      Parameters:
      value - the amount to advance
      Throws:
      IllegalStateException - if the total has been set and the progress would exceed it

    • advance

      <T> T advance(BigDecimal value)
      Advances the progress by the specified value and sends a notification asynchronously.

      Framework implementations should return their native reactive type:

      • Quarkus: Uni<Void>
      • Spring: Mono<Void>
      • Standard Java: CompletableFuture<Void>
      Type Parameters:
      T - the framework-specific reactive type
      Parameters:
      value - the amount to advance
      Returns:
      a reactive result that completes when the notification is sent

    • advanceAndForget

      default void advanceAndForget()
      Advances the progress by the default step and sends a notification without waiting.
      Throws:
      IllegalStateException - if the total has been set and the progress would exceed it
      See Also:

    • advanceAndForget

      default void advanceAndForget(long value)
      Advances the progress by the specified value and sends a notification without waiting.
      Parameters:
      value - the amount to advance
      Throws:
      IllegalStateException - if the total has been set and the progress would exceed it

    • advanceAndForget

      default void advanceAndForget(double value)
      Advances the progress by the specified value and sends a notification without waiting.
      Parameters:
      value - the amount to advance
      Throws:
      IllegalStateException - if the total has been set and the progress would exceed it

    • progress

      BigDecimal progress()
      Gets the current progress value.
      Returns:
      the current progress

    • total

      Optional<BigDecimal> total()
      Gets the expected total value.
      Returns:
      the total value, or an empty Optional if not set

    • step

      BigDecimal step()
      Gets the default step value used by advanceAndForget().
      Returns:
      the default step