Package org.apache.juneau.rest.client.mcp

Interface McpResponseCache

All Known Implementing Classes:
InMemoryMcpResponseCache
public interface McpResponseCache
An opt-in, off-by-default response cache for MCP client results.

Keyed by an opaque scope (a partition key — a revision-specific adapter defines its own scope wire vocabulary, e.g. the 2026-07-28 adapter's org.apache.juneau.bean.mcp.v20260728.McpCacheScope "private"/"public" cache-hint values; this neutral core treats the string as fully opaque and defines no scope constants of its own) plus a key (typically method + canonical params, computed by the caller).

Stored value shape: this SPI makes no assumption about what a cached value is — a caller may store the raw JSON-RPC result (e.g. via putResult(String, String, JsonRpcResponse, long)) or a typed result bean it has already re-marshaled (e.g. the 2026-07-28 client adapter, which caches the typed bean returned to its caller). Whatever shape a caller stores under a given key is exactly the shape it must expect back from get(String, String) for that same key — this interface does not normalize or re-marshal on either side.

Identity: implementations must return the exact value instance passed to put(String, String, Object, long) from a subsequent get(String, String) for the same partition/key (process-local implementations naturally satisfy this; an external/serializing store would not, and a caller layering one in must re-marshal on read to preserve this contract). Cached values may be handed out to more than one caller concurrently; callers must not mutate a returned value.

Implementations are free to be process-local (InMemoryMcpResponseCache, the built-in default) or backed by an external store; the SPI itself makes no assumption about storage.

Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Removes all cached entries across all scopes.
    Optional<Object>
    get(String scope, String key)
    Looks up a cached value.
    void
    put(String scope, String key, Object value, long ttlMs)
    Stores a value.
    default void
    putResult(String scope, String key, JsonRpcResponse response, long ttlMs)
    Convenience entry point for an adapter that wants to cache the raw JSON-RPC result straight off a JsonRpcResponse: stores it, or does nothing if the response is null, carries a JSON-RPC error, or has a null result.

  • Method Details

    • get

      Optional<Object> get(String scope, String key)
      Looks up a cached value.
      Parameters:
      scope - The cache-scope partition key. Must not be null.
      key - The cache key (typically method + canonical params). Must not be null.
      Returns:
      The cached value, or Optional.empty() if absent or expired.

    • put

      void put(String scope, String key, Object value, long ttlMs)
      Stores a value.
      Parameters:
      scope - The cache-scope partition key. Must not be null.
      key - The cache key (typically method + canonical params). Must not be null.
      value - The value to cache. Must not be null.
      ttlMs - The time-to-live in milliseconds. A value <= 0 means the entry never expires.

    • putResult

      default void putResult(String scope, String key, JsonRpcResponse response, long ttlMs)
      Convenience entry point for an adapter that wants to cache the raw JSON-RPC result straight off a JsonRpcResponse: stores it, or does nothing if the response is null, carries a JSON-RPC error, or has a null result.

      Callers never need to check for an error response themselves before caching, since this method never forwards one to put(String, String, Object, long). Note that this caches the raw wire result (e.g. a Map), not a typed result bean — an adapter that instead caches an already-re-marshaled typed bean (as the 2026-07-28 client adapter does) should call put(String, String, Object, long) directly instead of this method.

      Parameters:
      scope - The cache-scope partition key. Must not be null.
      key - The cache key (typically method + canonical params). Must not be null.
      response - The JSON-RPC response to conditionally cache. May be null.
      ttlMs - The time-to-live in milliseconds. A value <= 0 means the entry never expires.

    • clear

      void clear()
      Removes all cached entries across all scopes.