org.springframework.web.servlet.support

## Class WebContentGenerator

- java.lang.Object
- - org.springframework.context.support.ApplicationObjectSupport
  - - org.springframework.web.context.support.WebApplicationObjectSupport
    - - org.springframework.web.servlet.support.WebContentGenerator

- All Implemented Interfaces:
    Aware, ApplicationContextAware, ServletContextAware
  Direct Known Subclasses:
    AbstractController, AbstractHandlerMethodAdapter, ResourceHttpRequestHandler, WebContentInterceptor

      public abstract class WebContentGenerator
      extends WebApplicationObjectSupport

  Convenient superclass for any kind of web content generator, like `AbstractController` and `WebContentInterceptor`. Can also be used for custom handlers that have their own `HandlerAdapter`.

  Supports HTTP cache control options. The usage of corresponding HTTP headers can be controlled via the `"cacheSeconds"` and `"cacheControl"` properties.

  NOTE: As of Spring 4.2, this generator's default behavior changed when using only `setCacheSeconds(int)`, sending HTTP response headers that are in line with current browsers and proxies implementations (i.e. no HTTP 1.0 headers anymore) Reverting to the previous behavior can be easily done by using one of the newly deprecated methods `setUseExpiresHeader(boolean)`, `setUseCacheControlHeader(boolean)`, `setUseCacheControlNoStore(boolean)` or `setAlwaysMustRevalidate(boolean)`.

  Author:
    Rod Johnson, Juergen Hoeller, Brian Clozel, Rossen Stoyanchev
  See Also:
    `setCacheSeconds(int)`, `setCacheControl(org.springframework.http.CacheControl)`, `setRequireSession(boolean)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String` | `HEADER_CACHE_CONTROL`
    `static String` | `METHOD_GET` HTTP method "GET".
    `static String` | `METHOD_HEAD` HTTP method "HEAD".
    `static String` | `METHOD_POST` HTTP method "POST".

    - ### Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WebContentGenerator()` Create a new WebContentGenerator which supports HTTP methods GET, HEAD and POST by default.
    `WebContentGenerator(boolean restrictDefaultSupportedMethods)` Create a new WebContentGenerator.
    `WebContentGenerator(String... supportedMethods)` Create a new WebContentGenerator.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `applyCacheControl(HttpServletResponse response, CacheControl cacheControl)` Set the HTTP Cache-Control header according to the given settings.
    `protected void` | `applyCacheSeconds(HttpServletResponse response, int cacheSeconds)` Apply the given cache seconds and generate corresponding HTTP headers, i.e.
    `protected void` | `applyCacheSeconds(HttpServletResponse response, int cacheSeconds, boolean mustRevalidate)` Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
    `protected void` | `cacheForSeconds(HttpServletResponse response, int seconds)` Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
    `protected void` | `cacheForSeconds(HttpServletResponse response, int seconds, boolean mustRevalidate)` Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
    `protected void` | `checkAndPrepare(HttpServletRequest request, HttpServletResponse response, boolean lastModified)` Deprecated. as of 4.2, since the `lastModified` flag is effectively ignored, with a must-revalidate header only generated if explicitly configured
    `protected void` | `checkAndPrepare(HttpServletRequest request, HttpServletResponse response, int cacheSeconds, boolean lastModified)` Deprecated. as of 4.2, since the `lastModified` flag is effectively ignored, with a must-revalidate header only generated if explicitly configured
    `protected void` | `checkRequest(HttpServletRequest request)` Check the given request for supported methods and a required session, if any.
    `protected String` | `getAllowHeader()` Return the "Allow" header value to use in response to an HTTP OPTIONS request based on the configured `supported methods` also automatically adding "OPTIONS" to the list even if not present as a supported method.
    `CacheControl` | `getCacheControl()` Get the `CacheControl` instance that builds the Cache-Control HTTP response header.
    `int` | `getCacheSeconds()` Return the number of seconds that content is cached.
    `String[]` | `getSupportedMethods()` Return the HTTP methods that this content generator supports.
    `String[]` | `getVaryByRequestHeaders()` Return the configured request header names for the "Vary" response header.
    `boolean` | `isAlwaysMustRevalidate()` Deprecated. as of 4.2, in favor of `getCacheControl()`
    `boolean` | `isRequireSession()` Return whether a session is required to handle requests.
    `boolean` | `isUseCacheControlHeader()` Deprecated. as of 4.2, in favor of `getCacheControl()`
    `boolean` | `isUseCacheControlNoStore()` Deprecated. as of 4.2, in favor of `getCacheControl()`
    `boolean` | `isUseExpiresHeader()` Deprecated. as of 4.2, in favor of `getCacheControl()`
    `protected void` | `prepareResponse(HttpServletResponse response)` Prepare the given response according to the settings of this generator.
    `protected void` | `preventCaching(HttpServletResponse response)` Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
    `void` | `setAlwaysMustRevalidate(boolean mustRevalidate)` Deprecated. as of 4.2, in favor of `setCacheControl(org.springframework.http.CacheControl)`
    `void` | `setCacheControl(CacheControl cacheControl)` Set the `CacheControl` instance to build the Cache-Control HTTP response header.
    `void` | `setCacheSeconds(int seconds)` Cache content for the given number of seconds, by writing cache-related HTTP headers to the response: seconds == -1 (default value): no generation cache-related headers seconds == 0: "Cache-Control: no-store" will prevent caching seconds > 0: "Cache-Control: max-age=seconds" will ask to cache content
    `void` | `setRequireSession(boolean requireSession)` Set whether a session should be required to handle requests.
    `void` | `setSupportedMethods(String... methods)` Set the HTTP methods that this content generator should support.
    `void` | `setUseCacheControlHeader(boolean useCacheControlHeader)` Deprecated. as of 4.2, since going forward, the HTTP 1.1 cache-control header will be required, with the HTTP 1.0 headers disappearing
    `void` | `setUseCacheControlNoStore(boolean useCacheControlNoStore)` Deprecated. as of 4.2, in favor of `setCacheControl(org.springframework.http.CacheControl)`
    `void` | `setUseExpiresHeader(boolean useExpiresHeader)` Deprecated. as of 4.2, since going forward, the HTTP 1.1 cache-control header will be required, with the HTTP 1.0 headers disappearing
    `void` | `setVaryByRequestHeaders(String... varyByRequestHeaders)` Configure one or more request header names (e.g.

    - ### Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

      `getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

    - ### Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

      `getApplicationContext, getMessageSourceAccessor, initApplicationContext, obtainApplicationContext, requiredContextClass, setApplicationContext`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### METHOD_GET

          public static final String METHOD_GET

      HTTP method "GET".
      See Also:
        Constant Field Values

    - #### METHOD_HEAD

          public static final String METHOD_HEAD

      HTTP method "HEAD".
      See Also:
        Constant Field Values

    - #### METHOD_POST

          public static final String METHOD_POST

      HTTP method "POST".
      See Also:
        Constant Field Values

    - #### HEADER_CACHE_CONTROL

          protected static final String HEADER_CACHE_CONTROL

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### WebContentGenerator

          public WebContentGenerator()

      Create a new WebContentGenerator which supports HTTP methods GET, HEAD and POST by default.

    - #### WebContentGenerator

          public WebContentGenerator(boolean restrictDefaultSupportedMethods)

      Create a new WebContentGenerator.
      Parameters:
        `restrictDefaultSupportedMethods` - `true` if this generator should support HTTP methods GET, HEAD and POST by default, or `false` if it should be unrestricted

    - #### WebContentGenerator

          public WebContentGenerator(String... supportedMethods)

      Create a new WebContentGenerator.
      Parameters:
        `supportedMethods` - the supported HTTP methods for this content generator

  - ### Method Detail

    - #### setSupportedMethods

          public final void setSupportedMethods(@Nullable
                                                String... methods)

      Set the HTTP methods that this content generator should support.

      Default is GET, HEAD and POST for simple form controller types; unrestricted for general controllers and interceptors.

    - #### getSupportedMethods

          @Nullable
          public final String[] getSupportedMethods()

      Return the HTTP methods that this content generator supports.

    - #### getAllowHeader

          @Nullable
          protected String getAllowHeader()

      Return the "Allow" header value to use in response to an HTTP OPTIONS request based on the configured `supported methods` also automatically adding "OPTIONS" to the list even if not present as a supported method. This means subclasses don't have to explicitly list "OPTIONS" as a supported method as long as HTTP OPTIONS requests are handled before making a call to `checkRequest(HttpServletRequest)`.
      Since:
        4.3

    - #### setRequireSession

          public final void setRequireSession(boolean requireSession)

      Set whether a session should be required to handle requests.

    - #### isRequireSession

          public final boolean isRequireSession()

      Return whether a session is required to handle requests.

    - #### setCacheControl

          public final void setCacheControl(@Nullable
                                            CacheControl cacheControl)

      Set the `CacheControl` instance to build the Cache-Control HTTP response header.
      Since:
        4.2

    - #### getCacheControl

          @Nullable
          public final CacheControl getCacheControl()

      Get the `CacheControl` instance that builds the Cache-Control HTTP response header.
      Since:
        4.2

    - #### setCacheSeconds

          public final void setCacheSeconds(int seconds)

      Cache content for the given number of seconds, by writing cache-related HTTP headers to the response:
      - seconds == -1 (default value): no generation cache-related headers
      - seconds == 0: "Cache-Control: no-store" will prevent caching
      - seconds > 0: "Cache-Control: max-age=seconds" will ask to cache content

      For more specific needs, a custom `CacheControl` should be used.

      See Also:
        `setCacheControl(org.springframework.http.CacheControl)`

    - #### getCacheSeconds

          public final int getCacheSeconds()

      Return the number of seconds that content is cached.

    - #### setVaryByRequestHeaders

          public final void setVaryByRequestHeaders(@Nullable
                                                    String... varyByRequestHeaders)

      Configure one or more request header names (e.g. "Accept-Language") to add to the "Vary" response header to inform clients that the response is subject to content negotiation and variances based on the value of the given request headers. The configured request header names are added only if not already present in the response "Vary" header.
      Parameters:
        `varyByRequestHeaders` - one or more request header names
      Since:
        4.3

    - #### getVaryByRequestHeaders

          @Nullable
          public final String[] getVaryByRequestHeaders()

      Return the configured request header names for the "Vary" response header.
      Since:
        4.3

    - #### setUseExpiresHeader

          @Deprecated
          public final void setUseExpiresHeader(boolean useExpiresHeader)

      Deprecated. as of 4.2, since going forward, the HTTP 1.1 cache-control header will be required, with the HTTP 1.0 headers disappearing
      Set whether to use the HTTP 1.0 expires header. Default is "false", as of 4.2.

      Note: Cache headers will only get applied if caching is enabled (or explicitly prevented) for the current request.

    - #### isUseExpiresHeader

          @Deprecated
          public final boolean isUseExpiresHeader()

      Deprecated. as of 4.2, in favor of `getCacheControl()`
      Return whether the HTTP 1.0 expires header is used.

    - #### setUseCacheControlHeader

          @Deprecated
          public final void setUseCacheControlHeader(boolean useCacheControlHeader)

      Deprecated. as of 4.2, since going forward, the HTTP 1.1 cache-control header will be required, with the HTTP 1.0 headers disappearing
      Set whether to use the HTTP 1.1 cache-control header. Default is "true".

      Note: Cache headers will only get applied if caching is enabled (or explicitly prevented) for the current request.

    - #### isUseCacheControlHeader

          @Deprecated
          public final boolean isUseCacheControlHeader()

      Deprecated. as of 4.2, in favor of `getCacheControl()`
      Return whether the HTTP 1.1 cache-control header is used.

    - #### setUseCacheControlNoStore

          @Deprecated
          public final void setUseCacheControlNoStore(boolean useCacheControlNoStore)

      Deprecated. as of 4.2, in favor of `setCacheControl(org.springframework.http.CacheControl)`
      Set whether to use the HTTP 1.1 cache-control header value "no-store" when preventing caching. Default is "true".

    - #### isUseCacheControlNoStore

          @Deprecated
          public final boolean isUseCacheControlNoStore()

      Deprecated. as of 4.2, in favor of `getCacheControl()`
      Return whether the HTTP 1.1 cache-control header value "no-store" is used.

    - #### setAlwaysMustRevalidate

          @Deprecated
          public final void setAlwaysMustRevalidate(boolean mustRevalidate)

      Deprecated. as of 4.2, in favor of `setCacheControl(org.springframework.http.CacheControl)`
      An option to add 'must-revalidate' to every Cache-Control header. This may be useful with annotated controller methods, which can programmatically do a last-modified calculation as described in `WebRequest.checkNotModified(long)`.

      Default is "false".

    - #### isAlwaysMustRevalidate

          @Deprecated
          public final boolean isAlwaysMustRevalidate()

      Deprecated. as of 4.2, in favor of `getCacheControl()`
      Return whether 'must-revalidate' is added to every Cache-Control header.

    - #### checkRequest

          protected final void checkRequest(HttpServletRequest request)
                                     throws ServletException

      Check the given request for supported methods and a required session, if any.
      Parameters:
        `request` - current HTTP request
      Throws:
        `ServletException` - if the request cannot be handled because a check failed
      Since:
        4.2

    - #### prepareResponse

          protected final void prepareResponse(HttpServletResponse response)

      Prepare the given response according to the settings of this generator. Applies the number of cache seconds specified for this generator.
      Parameters:
        `response` - current HTTP response
      Since:
        4.2

    - #### applyCacheControl

          protected final void applyCacheControl(HttpServletResponse response,
                                                 CacheControl cacheControl)

      Set the HTTP Cache-Control header according to the given settings.
      Parameters:
        `response` - current HTTP response
        `cacheControl` - the pre-configured cache control settings
      Since:
        4.2

    - #### applyCacheSeconds

          protected final void applyCacheSeconds(HttpServletResponse response,
                                                 int cacheSeconds)

      Apply the given cache seconds and generate corresponding HTTP headers, i.e. allow caching for the given number of seconds in case of a positive value, prevent caching if given a 0 value, do nothing else. Does not tell the browser to revalidate the resource.
      Parameters:
        `response` - current HTTP response
        `cacheSeconds` - positive number of seconds into the future that the response should be cacheable for, 0 to prevent caching

    - #### checkAndPrepare

          @Deprecated
          protected final void checkAndPrepare(HttpServletRequest request,
                                                           HttpServletResponse response,
                                                           boolean lastModified)
                                                    throws ServletException

      Deprecated. as of 4.2, since the `lastModified` flag is effectively ignored, with a must-revalidate header only generated if explicitly configured
      Check and prepare the given request and response according to the settings of this generator.
      Throws:
        `ServletException`
      See Also:
        `checkRequest(HttpServletRequest)`, `prepareResponse(HttpServletResponse)`

    - #### checkAndPrepare

          @Deprecated
          protected final void checkAndPrepare(HttpServletRequest request,
                                                           HttpServletResponse response,
                                                           int cacheSeconds,
                                                           boolean lastModified)
                                                    throws ServletException

      Deprecated. as of 4.2, since the `lastModified` flag is effectively ignored, with a must-revalidate header only generated if explicitly configured
      Check and prepare the given request and response according to the settings of this generator.
      Throws:
        `ServletException`
      See Also:
        `checkRequest(HttpServletRequest)`, `applyCacheSeconds(HttpServletResponse, int)`

    - #### applyCacheSeconds

          @Deprecated
          protected final void applyCacheSeconds(HttpServletResponse response,
                                                             int cacheSeconds,
                                                             boolean mustRevalidate)

      Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
      Apply the given cache seconds and generate respective HTTP headers.

      That is, allow caching for the given number of seconds in the case of a positive value, prevent caching if given a 0 value, else do nothing (i.e. leave caching to the client).

      Parameters:
        `response` - the current HTTP response
        `cacheSeconds` - the (positive) number of seconds into the future that the response should be cacheable for; 0 to prevent caching; and a negative value to leave caching to the client.
        `mustRevalidate` - whether the client should revalidate the resource (typically only necessary for controllers with last-modified support)

    - #### cacheForSeconds

          @Deprecated
          protected final void cacheForSeconds(HttpServletResponse response,
                                                           int seconds)

      Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
      Set HTTP headers to allow caching for the given number of seconds. Does not tell the browser to revalidate the resource.
      Parameters:
        `response` - current HTTP response
        `seconds` - number of seconds into the future that the response should be cacheable for

    - #### cacheForSeconds

          @Deprecated
          protected final void cacheForSeconds(HttpServletResponse response,
                                                           int seconds,
                                                           boolean mustRevalidate)

      Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
      Set HTTP headers to allow caching for the given number of seconds. Tells the browser to revalidate the resource if mustRevalidate is `true`.
      Parameters:
        `response` - the current HTTP response
        `seconds` - number of seconds into the future that the response should be cacheable for
        `mustRevalidate` - whether the client should revalidate the resource (typically only necessary for controllers with last-modified support)

    - #### preventCaching

          @Deprecated
          protected final void preventCaching(HttpServletResponse response)

      Deprecated. as of 4.2, in favor of `applyCacheControl(javax.servlet.http.HttpServletResponse, org.springframework.http.CacheControl)`
      Prevent the response from being cached. Only called in HTTP 1.0 compatibility mode.

      See `https://www.mnot.net/cache_docs`.