public class CacheControl extends Object
Adding Cache-Control directives to HTTP responses can significantly improve the client experience when interacting with a web application. This builder creates opinionated "Cache-Control" headers with response directives only, with several use cases in mind.
CacheControl cc = CacheControl.maxAge(1, TimeUnit.HOURS)
will result in Cache-Control: "max-age=3600"CacheControl cc = CacheControl.noStore()
will result in Cache-Control: "no-store"CacheControl cc = CacheControl.maxAge(1, TimeUnit.HOURS).noTransform().cachePublic()
will result in Cache-Control: "max-age=3600, no-transform, public"Note that to be efficient, Cache-Control headers should be written along HTTP validators such as "Last-Modified" or "ETag" headers.
| Modifier | Constructor and Description |
|---|---|
protected |
CacheControl()
Create an empty CacheControl instance.
|
| Modifier and Type | Method and Description |
|---|---|
CacheControl |
cachePrivate()
Add a "private" directive.
|
CacheControl |
cachePublic()
Add a "public" directive.
|
static CacheControl |
empty()
Return an empty directive.
|
String |
getHeaderValue()
Return the "Cache-Control" header value, if any.
|
static CacheControl |
maxAge(long maxAge,
TimeUnit unit)
Add a "max-age=" directive.
|
CacheControl |
mustRevalidate()
Add a "must-revalidate" directive.
|
static CacheControl |
noCache()
Add a "no-cache" directive.
|
static CacheControl |
noStore()
Add a "no-store" directive.
|
CacheControl |
noTransform()
Add a "no-transform" directive.
|
CacheControl |
proxyRevalidate()
Add a "proxy-revalidate" directive.
|
CacheControl |
sMaxAge(long sMaxAge,
TimeUnit unit)
Add an "s-maxage" directive.
|
CacheControl |
staleIfError(long staleIfError,
TimeUnit unit)
Add a "stale-if-error" directive.
|
CacheControl |
staleWhileRevalidate(long staleWhileRevalidate,
TimeUnit unit)
Add a "stale-while-revalidate" directive.
|
protected CacheControl()
empty()public static CacheControl empty()
This is well suited for using other optional directives without "max-age", "no-cache" or "no-store".
this, to facilitate method chainingpublic static CacheControl maxAge(long maxAge, TimeUnit unit)
This directive is well suited for publicly caching resources, knowing that
they won't change within the configured amount of time. Additional directives
can be also used, in case resources shouldn't be cached (cachePrivate())
or transformed (noTransform()) by shared caches.
In order to prevent caches to reuse the cached response even when it has
become stale (i.e. the "max-age" delay is passed), the "must-revalidate"
directive should be set (mustRevalidate()
maxAge - the maximum time the response should be cachedunit - the time unit of the maxAge argumentthis, to facilitate method chainingpublic static CacheControl noCache()
This directive is well suited for telling caches that the response can be reused only if the client revalidates it with the server. This directive won't disable cache altogether and may result with clients sending conditional requests (with "ETag", "If-Modified-Since" headers) and the server responding with "304 - Not Modified" status.
In order to disable caching and minimize requests/responses exchanges,
the noStore() directive should be used instead of #noCache().
this, to facilitate method chainingpublic static CacheControl noStore()
This directive is well suited for preventing caches (browsers and proxies) to cache the content of responses.
this, to facilitate method chainingpublic CacheControl mustRevalidate()
This directive indicates that once it has become stale, a cache MUST NOT use the response to satisfy subsequent requests without successful validation on the origin server.
this, to facilitate method chainingpublic CacheControl noTransform()
This directive indicates that intermediaries (caches and others) should not transform the response content. This can be useful to force caches and CDNs not to automatically gzip or optimize the response content.
this, to facilitate method chainingpublic CacheControl cachePublic()
This directive indicates that any cache MAY store the response, even if the response would normally be non-cacheable or cacheable only within a private cache.
this, to facilitate method chainingpublic CacheControl cachePrivate()
This directive indicates that the response message is intended for a single user and MUST NOT be stored by a shared cache.
this, to facilitate method chainingpublic CacheControl proxyRevalidate()
This directive has the same meaning as the "must-revalidate" directive, except that it does not apply to private caches (i.e. browsers, HTTP clients).
this, to facilitate method chainingpublic CacheControl sMaxAge(long sMaxAge, TimeUnit unit)
This directive indicates that, in shared caches, the maximum age specified by this directive overrides the maximum age specified by other directives.
sMaxAge - the maximum time the response should be cachedunit - the time unit of the sMaxAge argumentthis, to facilitate method chainingpublic CacheControl staleWhileRevalidate(long staleWhileRevalidate, TimeUnit unit)
This directive indicates that caches MAY serve the response in which it appears after it becomes stale, up to the indicated number of seconds. If a cached response is served stale due to the presence of this extension, the cache SHOULD attempt to revalidate it while still serving stale responses (i.e. without blocking).
staleWhileRevalidate - the maximum time the response should be used while being revalidatedunit - the time unit of the staleWhileRevalidate argumentthis, to facilitate method chainingpublic CacheControl staleIfError(long staleIfError, TimeUnit unit)
This directive indicates that when an error is encountered, a cached stale response MAY be used to satisfy the request, regardless of other freshness information.
staleIfError - the maximum time the response should be used when errors are encounteredunit - the time unit of the staleIfError argumentthis, to facilitate method chaining