Package com.shri.restinpeace.cache

Class CachedResponse

java.lang.Object
com.shri.restinpeace.cache.CachedResponse
public final class CachedResponse extends Object
A stored GET response, as handed to and returned from a Cache implementation. Immutable - a revalidated or newly-stored entry is always a new instance, never a mutation of an existing one.

  • Constructor Details

    • CachedResponse

      public CachedResponse(int status, Map<String,List<String>> headers, String body, long freshUntilEpochMillis)
      Creates a cached entry with no Vary header - equivalent to CachedResponse(int, Map, String, long, Map) with an empty map.
      Parameters:
      status - the original response's HTTP status code
      headers - the original response's headers, keyed case-insensitively
      body - the original response body
      freshUntilEpochMillis - the epoch millisecond after which this entry is stale and must be revalidated (or re-fetched) before being served again - already in the past for an entry that's only cached for revalidation (e.g. Cache-Control: no-cache, or a response with an ETag/ Last-Modified but no max-age)

    • CachedResponse

      public CachedResponse(int status, Map<String,List<String>> headers, String body, long freshUntilEpochMillis, Map<String,String> varyRequestHeaders)
      Creates a cached entry, snapshotting the request header values its response's own Vary header named - so a later request whose values for those same headers differ is never served this entry. Equivalent to CachedResponse(int, Map, String, long, Map, long) with freshUntilEpochMillis as the stale-while-revalidate deadline too - i.e. no stale-while-revalidate window at all, this class's original behavior.
      Parameters:
      status - the original response's HTTP status code
      headers - the original response's headers, keyed case-insensitively
      body - the original response body
      freshUntilEpochMillis - the epoch millisecond after which this entry is stale and must be revalidated (or re-fetched) before being served again
      varyRequestHeaders - the request header values named by this response's own Vary header, at the time this entry was stored - empty if the response had no Vary header (this entry then matches any request)

    • CachedResponse

      public CachedResponse(int status, Map<String,List<String>> headers, String body, long freshUntilEpochMillis, Map<String,String> varyRequestHeaders, long staleWhileRevalidateUntilEpochMillis)
      Creates a cached entry with an explicit stale-while-revalidate deadline - a Cache-Control: stale-while-revalidate=N response may still be served, stale, up until this epoch millisecond, while a background revalidation refreshes the entry for the next call (see isWithinStaleWhileRevalidateWindow()).
      Parameters:
      status - the original response's HTTP status code
      headers - the original response's headers, keyed case-insensitively
      body - the original response body
      freshUntilEpochMillis - the epoch millisecond after which this entry is stale and must be revalidated (or re-fetched) before being served again
      varyRequestHeaders - the request header values named by this response's own Vary header, at the time this entry was stored - empty if the response had no Vary header
      staleWhileRevalidateUntilEpochMillis - the epoch millisecond up to which this entry may still be served stale while revalidating in the background - equal to freshUntilEpochMillis (no window) if the response named no stale-while-revalidate directive

  • Method Details

    • getStatus

      public int getStatus()
      Returns the original response's HTTP status code.
      Returns:
      the status code

    • getHeaders

      public Map<String,List<String>> getHeaders()
      Returns the original response's headers, keyed case-insensitively.
      Returns:
      the headers

    • getHeader

      public String getHeader(String name)
      Returns the first value of a response header, matched case-insensitively.
      Parameters:
      name - the header name
      Returns:
      the header's first value, or null if it wasn't sent

    • getBody

      public String getBody()
      Returns the original response body.
      Returns:
      the response body

    • getFreshUntilEpochMillis

      public long getFreshUntilEpochMillis()
      Returns the epoch millisecond after which this entry is stale.
      Returns:
      the freshness deadline, in epoch milliseconds

    • isFresh

      public boolean isFresh()
      Whether this entry can still be served without revalidating against the origin server.
      Returns:
      true if this entry is still fresh

    • getStaleWhileRevalidateUntilEpochMillis

      public long getStaleWhileRevalidateUntilEpochMillis()
      Returns the epoch millisecond up to which this entry may still be served stale while a background revalidation refreshes it, per a Cache-Control: stale-while-revalidate=N response - equal to getFreshUntilEpochMillis() (no window at all) for an entry whose response named no such directive.
      Returns:
      the stale-while-revalidate deadline, in epoch milliseconds

    • isWithinStaleWhileRevalidateWindow

      public boolean isWithinStaleWhileRevalidateWindow()
      Whether this entry is stale (isFresh() is false) but still within its stale-while-revalidate window - safe to serve immediately while a background revalidation refreshes it, rather than blocking the caller on a synchronous revalidation round trip.
      Returns:
      true if this entry is stale but still stale-while-revalidate-eligible

    • getVaryRequestHeaders

      public Map<String,String> getVaryRequestHeaders()
      Returns the request header values this entry's Vary header named, snapshotted at storage time.
      Returns:
      the vary snapshot, keyed by header name - empty if the response had no Vary header

    • getStoredAtEpochMillis

      public long getStoredAtEpochMillis()
      Returns when this entry was constructed - at initial storage, or the moment a stale entry was last successfully revalidated (a fresh CachedResponse instance is created either way; this class is immutable). A distinct notion of time from getFreshUntilEpochMillis(): this is "how long has RIP been holding onto this at all" (what a Cache implementation wanting to bound its own memory use, like InMemoryCache's optional max-entry-age, would check), not "is it still safe to serve without asking the server" - an entry stored for revalidation only (e.g. Cache-Control: no-cache) is stale from the moment it's stored, by design, but its stored time still starts counting fresh here.
      Returns:
      the epoch millisecond this entry was created