Class McpLocalizationContext

java.lang.Object
com.soklet.McpLocalizationContext
@ThreadSafe public final class McpLocalizationContext extends Object
Immutable, node-local localization context for one admitted localization-capable MCP operation.

This is not a distributed session. It has no ID, is never serialized or recovered on another node, and requires no routing affinity. The context captures one locale and one immutable translation snapshot. A later request on another node creates a new context from portable request or continuation facts.

The context is not closeable and must not own resources whose correctness depends on an exact close callback. Its lookup must be safe for concurrent calls. Locale and revision remain equal for its full lifetime; equal localizable-text inputs must produce equal results independently of lookup order, including under concurrent calls.

This is a borrowed invocation-scoped feature. An application handler or interceptor must not retain it or its feature carrier after invocation termination. The lookup should capture only the minimum immutable snapshot and must not capture the request or application object graph. Every localization lookup must use that already-loaded snapshot and perform bounded, in-memory, nonblocking work without remote TMS/network I/O, lazy unbounded loading, or unbounded-executor dispatch.

Author:
Mark Allen

  • Method Details

    • withLocale

      public static @NonNull McpLocalizationContext.Builder withLocale(@NonNull Locale locale, @NonNull McpLocalizationLookup localizationLookup)
      Vends a context builder primed with its required construction values.
      Parameters:
      locale - canonical selected catalog locale
      localizationLookup - request-local immutable-snapshot lookup
      Returns:
      localization-context builder
      Throws:
      NullPointerException - if an argument is null
      IllegalArgumentException - if locale is not a canonical, non-root BCP 47 locale of at most 255 ASCII bytes

    • getLocale

      public @NonNull Locale getLocale()
      Returns:
      canonical selected catalog locale

    • getRevision

      public @NonNull Optional<@NonNull McpLocalizationRevision> getRevision()
      Returns optional non-secret identity for the captured catalog snapshot. Revisions are not MCP wire values or distributed-session identifiers.
      Returns:
      immutable snapshot revision, or empty

    • localize

      public @NonNull McpLocalizationResult localize(@NonNull McpLocalizableText text)
      Localizes one framework-owned source-text field against this context's captured snapshot. The lookup must be bounded, in-memory, and nonblocking; it must not perform remote I/O or unbounded loading.

      The localization lookup reports an unexpected failure with McpLocalizationResult.failure(); it must not throw to report an operational lookup failure. If an unchecked contract violation nevertheless escapes while Soklet invokes this callback, Soklet treats it as untrusted localization data and does not forward it through framework-owned lifecycle, simulation, logging, response-throwable, or cause surfaces. Direct application invocation is application-owned and has normal application failure semantics.

      Parameters:
      text - structured coordinate and canonical source text
      Returns:
      non-null localization result
      Throws:
      NullPointerException - if text is null or the configured lookup returns null

    • toString

      public @NonNull String toString()
      Overrides:
      toString in class Object
      Returns:
      redacted diagnostic rendering