Package org.apache.juneau.http.header

Class CacheControl.Builder

java.lang.Object
org.apache.juneau.http.header.CacheControl.Builder
Enclosing class:
CacheControl
public static class CacheControl.Builder extends Object
Fluent builder for assembling an HTTP Cache-Control header value.

Composes the directives defined by RFC 9111 §5.2 into the comma-separated wire format expected by the Cache-Control response header. Mutually exclusive cacheability directives (e.g. publicCache() vs privateCache()) overwrite one another; boolean directives (e.g. noStore()) are idempotent.

Example:

String value = CacheControl.create() .publicCache() .maxAge(3600) .mustRevalidate() .build(); // => "public, max-age=3600, must-revalidate"

See Also:
Since:
10.0.0

  • Constructor Details

  • Method Details

    • publicCache

      public CacheControl.Builder publicCache()
      Adds the public directive (responses may be cached by any cache).

      Clears any previously set private directive.

      Returns:
      This object.

    • privateCache

      public CacheControl.Builder privateCache()
      Adds the private directive (responses may only be cached by the originating client).

      Clears any previously set public directive.

      Returns:
      This object.

    • noCache

      public CacheControl.Builder noCache()
      Adds the no-cache directive.

      Forces caches to revalidate with the origin server before reusing a stored response.

      Returns:
      This object.

    • noStore

      public CacheControl.Builder noStore()
      Adds the no-store directive.

      Forbids caches from storing any part of the request or response.

      Returns:
      This object.

    • noTransform

      public CacheControl.Builder noTransform()
      Adds the no-transform directive.

      Forbids intermediaries from transforming the response payload.

      Returns:
      This object.

    • mustRevalidate

      public CacheControl.Builder mustRevalidate()
      Adds the must-revalidate directive.

      Forces caches to revalidate stale responses with the origin before serving them.

      Returns:
      This object.

    • proxyRevalidate

      public CacheControl.Builder proxyRevalidate()
      Adds the proxy-revalidate directive (must-revalidate for shared caches only).
      Returns:
      This object.

    • immutable

      public CacheControl.Builder immutable()
      Adds the immutable directive.

      Signals that the response body will not change for the duration of its freshness lifetime.

      Returns:
      This object.

    • maxAge

      public CacheControl.Builder maxAge(long seconds)
      Adds the max-age=N directive (seconds).
      Parameters:
      seconds - Maximum freshness lifetime in seconds. Must be non-negative.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If seconds is negative.

    • maxAge

      public CacheControl.Builder maxAge(Duration value)
      Adds the max-age=N directive from a Duration.
      Parameters:
      value - Maximum freshness lifetime. Must not be null or negative.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If value is null or negative.

    • sMaxAge

      public CacheControl.Builder sMaxAge(long seconds)
      Adds the s-maxage=N directive (shared-cache max-age in seconds).
      Parameters:
      seconds - Maximum freshness lifetime in seconds for shared caches. Must be non-negative.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If seconds is negative.

    • sMaxAge

      public CacheControl.Builder sMaxAge(Duration value)
      Adds the s-maxage=N directive from a Duration.
      Parameters:
      value - Maximum freshness lifetime for shared caches. Must not be null or negative.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If value is null or negative.

    • staleWhileRevalidate

      public CacheControl.Builder staleWhileRevalidate(long seconds)
      Adds the stale-while-revalidate=N directive (seconds).
      Parameters:
      seconds - Number of seconds a cache may serve a stale response while asynchronously revalidating.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If seconds is negative.

    • staleIfError

      public CacheControl.Builder staleIfError(long seconds)
      Adds the stale-if-error=N directive (seconds).
      Parameters:
      seconds - Number of seconds a cache may serve a stale response when the origin is unreachable.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If seconds is negative.

    • extension

      public CacheControl.Builder extension(String value)
      Adds an arbitrary cache-control extension directive (e.g. "community=\"UCI\"").

      Extensions are appended in registration order at the end of the directive list. The caller is responsible for supplying a token that conforms to the cache-directive grammar of RFC 9111 §5.2.3.

      Parameters:
      value - The extension token. Must not be null or blank.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If value is null or blank.

    • build

      public String build()
      Builds the comma-separated Cache-Control header value.

      Returns an empty string when no directives have been registered.

      Returns:
      The header value. Never null.

    • toHeader

      public CacheControl toHeader()
      Builds a CacheControl header bean directly from this builder.
      Returns:
      A CacheControl carrying build(). Never null.

    • toString

      public String toString()
      Overrides:
      toString in class Object