ResponseCache
Stores the decoded answer of a load for a bounded time and serves it to any number of concurrent callers from one load; failures are never stored.
The contract an implementation (the supplied JVM CaffeineResponseCache, ResponseCache.Disabled, a consumer's own cache or a fake) meets:
One load per key at a time. Concurrent calls for an equal CacheKey while a load is in flight join it and receive its outcome. A joining or hitting call's
policyandloaderare not used, so a shared load carries the first caller's loader.A Lookup.Found is stored for CachePolicy.ttl and a Lookup.Missing for CachePolicy.missTtl, measured from the load's completion. A zero TTL coalesces loads in flight and stores nothing. A failure is never stored.
maxAge: a stored entry whose age exceeds it is not served (an age at mostmaxAgeis served, as RFC 9111'smax-agerequest directive reads). The call loads, or joins a load already in flight, which counts as fresh. At most one reload per call.A loader's
Exceptionbecomes the call's failure, the same instance for every waiter. AnErroris rethrown to every waiter. A cancellation the loader throws, or returns insideResult.failure, while the coroutine running the loader is still active (the caller's for Disabled; the cache's own, until close, for a cache that loads in its own scope) becomesResult.failure(IllegalStateException(…, cause)); aCancellationExceptionis never put inside aResult.A caller's own cancellation is thrown as
CancellationExceptionand cancels only that caller. A caller that is already cancelled gets it even on a hit.After close, getOrLoad returns
Result.failure(HttpFailure.Closed("cache"))without running the loader, and a call waiting on a load when close runs returns the same. close is idempotent, non-suspending and never throws. Disabled, which stores nothing and is shared, ignores close.After invalidate, the next call for the key loads anew; a load in flight still completes for the calls already waiting and its result is not stored. invalidateAll is the same for every key. Both never throw and are no-ops after close.
stats is an immutable reading of four counts; the four are read separately, not as one atomic snapshot.
Every member may be called concurrently from any thread.
The key's type parameter is not part of its equality: one endpoint id serves one value type; a second type under the same id is a programming error.
A negative
maxAgeis a programmer error:IllegalArgumentException("maxAge must not be negative").
A loader must not wait for a load of its own key. A supplied loader runs in the cache's own scope, not in the caller's; Disabled runs it on the caller's coroutine.
Experimental (implement). Implementing or delegating to this interface needs @OptIn(ExperimentalForInheritanceWebToolsApi::class); calling it and passing it are Stable Core, and the supplied Disabled and the JVM's CaffeineResponseCache need no opt-in.
Inheritors
Types
Functions
getOrLoad accepting any live entry (maxAge is Duration.INFINITE).
Drops every stored or in-flight entry (contract point 7), as invalidate does for one key. Never throws; a no-op after close.
Reads the four counts (contract point 8).