Package com.shri.restinpeace.cache

Interface Cache

All Known Implementing Classes:
InMemoryCache
public interface Cache
A pluggable store for GET response caching, attached via RipClientConfig.Builder.cache(Cache) (one client) or RIP.setCache(Cache) (the shared default for every client without its own). RIP honors whatever the server actually says via Cache-Control/ETag/Last-Modified - a Cache implementation is purely storage, not a policy decision; see InMemoryCache for the default, in-memory implementation (which also supports an optional, opt-in max entry age - "eviction on the basis of time" as an automatic background concern, distinct from the manual eviction described below).

Keyed by key(HTTPMethod, String) - "<HTTP method> <request URL>" (e.g. "GET https://api.example.com/items?page=2") - a single slot per key, the newest variant replacing the previous one, rather than storing every Vary-distinguished variant at once. A response naming a Vary header is still never served to a request whose current value for that header differs from the one snapshotted when it was stored (see CachedResponse.getVaryRequestHeaders()) - this affects only how many variants stay cached at once, not correctness.

By default the key's URL includes the query string, so /items?page=1 and /items?page=2 are cached separately - this can be turned off per client (see RipClientConfig.Builder.cacheKeyIncludesQueryString(boolean)) or as a shared default (see RIP.setCacheKeyIncludesQueryString(boolean)) for an endpoint whose query params don't affect the response (e.g. an analytics/tracking param), trading that precision for a higher hit rate - every query-string variant of the same path then shares one entry.

Manual eviction: a consumer holding a reference to the same Cache instance RIP is using (since they're the one who constructed and attached it) can force one specific call's cached response gone at any time - myCache.evict(Cache.key(HTTPMethod.GET, "https://api.example.com/items/42")) - e.g. right after some other action they know invalidates it server-side, or clear() for everything at once. Deliberately manual only: RIP itself never inspects a POST/PUT/DELETE call to guess which cached GETs it might have invalidated - a URL-matching heuristic at best, wrong in either direction (a write to a different resource that happens to share a path prefix; a write that invalidates a completely different endpoint's cached list view) - so that decision is left to whoever actually knows their own API's real read/write relationships.

Implementations must be safe for concurrent use - a shared Cache (or the RIP.setCache(Cache) default) can be read and written from multiple calls at once.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Removes every stored entry.
    void
    evict(String key)
    Removes the entry for key, if any - e.g. after a mutating call (a POST/PUT/DELETE) that's known to invalidate a previously-cached GET.
    CachedResponse
    get(String key)
    Returns the entry stored for key, whether or not it's still fresh - a stale entry may still be usable for revalidation (see CachedResponse.isFresh()).
    static String
    key(HTTPMethod httpMethod, String url)
    Computes the cache key RIP itself uses internally for a call to url - the same formula get/put/evict are keyed by for that exact call, so this is the value to pass to evict(java.lang.String) to manually invalidate one specific cached response.
    void
    put(String key, CachedResponse response)
    Stores (or replaces) the entry for key.

  • Method Details

    • key

      static String key(HTTPMethod httpMethod, String url)
      Computes the cache key RIP itself uses internally for a call to url - the same formula get/put/evict are keyed by for that exact call, so this is the value to pass to evict(java.lang.String) to manually invalidate one specific cached response.

      By default, url must be the exact absolute URL as sent on the wire, query string included in the same order/encoding RIP itself would produce (e.g. from @QueryParam/@QueryMap applied in method-declaration order) - a mismatched query string computes a different key and silently won't evict anything. For a method with no query parameters at all, this is simply the interface method's resolved URL. If the relevant client has cacheKeyIncludesQueryString set to false (see the class javadoc above), pass the URL without its query string instead, since that's what RIP itself keyed the entry by.

      Parameters:
      httpMethod - the call's HTTP method - always GET in practice, since only GET responses are ever cached, but accepted generally so this formula has exactly one implementation
      url - the exact request URL RIP keyed this entry by - the full URL with its query string by default, or without one if cacheKeyIncludesQueryString is turned off for the relevant client
      Returns:
      the cache key for that call

    • get

      CachedResponse get(String key)
      Returns the entry stored for key, whether or not it's still fresh - a stale entry may still be usable for revalidation (see CachedResponse.isFresh()).
      Parameters:
      key - the cache key
      Returns:
      the stored entry, or null if nothing is cached for it

    • put

      void put(String key, CachedResponse response)
      Stores (or replaces) the entry for key.
      Parameters:
      key - the cache key
      response - the entry to store

    • evict

      void evict(String key)
      Removes the entry for key, if any - e.g. after a mutating call (a POST/PUT/DELETE) that's known to invalidate a previously-cached GET.
      Parameters:
      key - the cache key to remove

    • clear

      void clear()
      Removes every stored entry.