Package com.oorian.security

Class CacheControl

java.lang.Object
com.oorian.security.CacheControl
public class CacheControl extends Object
A fluent builder for constructing HTTP Cache-Control header values.

The Cache-Control header controls how browsers and intermediate caches store and serve HTTP responses. This class provides a type-safe, discoverable API for building cache directives without manually constructing raw header strings.

Usage:


 // Build a custom cache policy
 CacheControl cache = new CacheControl();
 cache.setPublic();
 cache.setMaxAge(86400);
 cache.mustRevalidate();
 response.setHeader("Cache-Control", cache.toString());
 // "public, max-age=86400, must-revalidate"

 // Or use static factory methods for common patterns
 response.setHeader("Cache-Control", CacheControl.staticResources().toString());
 // "public, max-age=31536000, immutable"
Since:
2.0
Version:
1.0
Author:
Marvin P. Warble Jr.

  • Constructor Details

    • CacheControl

      public CacheControl()
      Creates a new empty Cache-Control builder.

  • Method Details

    • setPublic

      public CacheControl setPublic()
      Sets the public directive.

      Indicates that the response may be cached by any cache, including shared caches such as CDNs and proxy servers.

      Returns:
      this instance for method chaining

    • setPrivate

      public CacheControl setPrivate()
      Sets the private directive.

      Indicates that the response is intended for a single user and must not be stored by shared caches. A private cache (such as the browser cache) may store the response.

      Returns:
      this instance for method chaining

    • noCache

      public CacheControl noCache()
      Sets the no-cache directive.

      Indicates that caches must revalidate the response with the origin server before each use, even if the cached response has not expired. The response may still be stored by caches.

      Returns:
      this instance for method chaining

    • noStore

      public CacheControl noStore()
      Sets the no-store directive.

      Indicates that no cache of any kind (private or shared) should store the response. This is the strongest cache prevention directive.

      Returns:
      this instance for method chaining

    • noTransform

      public CacheControl noTransform()
      Sets the no-transform directive.

      Indicates that intermediary caches or proxies must not modify the response body, Content-Encoding, Content-Range, or Content-Type headers.

      Returns:
      this instance for method chaining

    • mustRevalidate

      public CacheControl mustRevalidate()
      Sets the must-revalidate directive.

      Indicates that once a cached response becomes stale, it must not be used without successful revalidation with the origin server.

      Returns:
      this instance for method chaining

    • proxyRevalidate

      public CacheControl proxyRevalidate()
      Sets the proxy-revalidate directive.

      Similar to must-revalidate, but applies only to shared caches (such as proxies and CDNs). Private caches may continue to use stale responses.

      Returns:
      this instance for method chaining

    • immutable

      public CacheControl immutable()
      Sets the immutable directive.

      Indicates that the response body will not change over time. This prevents browsers from sending conditional revalidation requests (e.g., If-None-Match) during the freshness lifetime. Best used with long max-age values for versioned static resources.

      Returns:
      this instance for method chaining

    • setMaxAge

      public CacheControl setMaxAge(int seconds)
      Sets the max-age directive.

      Specifies the maximum amount of time in seconds that a response is considered fresh. After this time elapses, the cache must revalidate the response with the origin server.

      Parameters:
      seconds - the maximum age in seconds (e.g., 86400 for one day, 31536000 for one year)
      Returns:
      this instance for method chaining

    • setSMaxAge

      public CacheControl setSMaxAge(int seconds)
      Sets the s-maxage directive.

      Specifies the maximum age for shared caches (CDNs and proxies), overriding the max-age directive for those caches. Private caches still use max-age.

      Parameters:
      seconds - the shared cache maximum age in seconds
      Returns:
      this instance for method chaining

    • setStaleWhileRevalidate

      public CacheControl setStaleWhileRevalidate(int seconds)
      Sets the stale-while-revalidate directive.

      Indicates that the cache may serve a stale response while it revalidates the response in the background. The value specifies how many seconds past the max-age the cache may continue serving the stale response.

      Parameters:
      seconds - the stale-while-revalidate window in seconds
      Returns:
      this instance for method chaining

    • setStaleIfError

      public CacheControl setStaleIfError(int seconds)
      Sets the stale-if-error directive.

      Indicates that the cache may serve a stale response if the origin server responds with an error (5xx status). The value specifies how many seconds past the max-age the stale response may be used when errors occur.

      Parameters:
      seconds - the stale-if-error window in seconds
      Returns:
      this instance for method chaining

    • staticResources

      public static CacheControl staticResources()
      Creates a CacheControl configured for long-lived static resources.

      Returns a policy of public, max-age=31536000, immutable which is suitable for versioned static assets such as CSS files, JavaScript bundles, and images whose URLs change when the content changes (via cache-busting query parameters or hashed filenames).

      Returns:
      a new CacheControl instance configured for static resources

    • preventCaching

      public static CacheControl preventCaching()
      Creates a CacheControl configured to prevent caching entirely.

      Returns a policy of no-store which prevents any cache from storing the response. Use this for sensitive data that should never be cached.

      Returns:
      a new CacheControl instance configured to prevent all caching

    • revalidate

      public static CacheControl revalidate()
      Creates a CacheControl configured to require revalidation on every use.

      Returns a policy of no-cache which allows caches to store the response but requires revalidation with the origin server before each use.

      Returns:
      a new CacheControl instance configured to require revalidation

    • toString

      public String toString()
      Returns the Cache-Control header value as a formatted string.

      Produces a comma-separated string of all configured directives, suitable for use as the value of a Cache-Control HTTP response header.

      Overrides:
      toString in class Object
      Returns:
      the Cache-Control header value string