org.springframework.web.servlet.support.WebContentGenerator.java Source code

Java tutorial

Introduction

Here is the source code for org.springframework.web.servlet.support.WebContentGenerator.java

Source

/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.servlet.support;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.Set;
import java.util.concurrent.TimeUnit;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.http.CacheControl;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.lang.Nullable;
import org.springframework.util.ObjectUtils;
import org.springframework.util.StringUtils;
import org.springframework.web.HttpRequestMethodNotSupportedException;
import org.springframework.web.HttpSessionRequiredException;
import org.springframework.web.context.support.WebApplicationObjectSupport;

/**
 * Convenient superclass for any kind of web content generator,
 * like {@link org.springframework.web.servlet.mvc.AbstractController}
 * and {@link org.springframework.web.servlet.mvc.WebContentInterceptor}.
 * Can also be used for custom handlers that have their own
 * {@link org.springframework.web.servlet.HandlerAdapter}.
 *
 * <p>Supports HTTP cache control options. The usage of corresponding HTTP
 * headers can be controlled via the {@link #setCacheSeconds "cacheSeconds"}
 * and {@link #setCacheControl "cacheControl"} properties.
 *
 * <p><b>NOTE:</b> As of Spring 4.2, this generator's default behavior changed when
 * using only {@link #setCacheSeconds}, 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 {@link #setUseExpiresHeader}, {@link #setUseCacheControlHeader},
 * {@link #setUseCacheControlNoStore} or {@link #setAlwaysMustRevalidate}.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @author Brian Clozel
 * @author Rossen Stoyanchev
 * @see #setCacheSeconds
 * @see #setCacheControl
 * @see #setRequireSession
 */
public abstract class WebContentGenerator extends WebApplicationObjectSupport {

    /** HTTP method "GET". */
    public static final String METHOD_GET = "GET";

    /** HTTP method "HEAD". */
    public static final String METHOD_HEAD = "HEAD";

    /** HTTP method "POST". */
    public static final String METHOD_POST = "POST";

    private static final String HEADER_PRAGMA = "Pragma";

    private static final String HEADER_EXPIRES = "Expires";

    protected static final String HEADER_CACHE_CONTROL = "Cache-Control";

    /** Set of supported HTTP methods. */
    @Nullable
    private Set<String> supportedMethods;

    @Nullable
    private String allowHeader;

    private boolean requireSession = false;

    @Nullable
    private CacheControl cacheControl;

    private int cacheSeconds = -1;

    @Nullable
    private String[] varyByRequestHeaders;

    // deprecated fields

    /** Use HTTP 1.0 expires header? */
    private boolean useExpiresHeader = false;

    /** Use HTTP 1.1 cache-control header? */
    private boolean useCacheControlHeader = true;

    /** Use HTTP 1.1 cache-control header value "no-store"? */
    private boolean useCacheControlNoStore = true;

    private boolean alwaysMustRevalidate = false;

    /**
     * Create a new WebContentGenerator which supports
     * HTTP methods GET, HEAD and POST by default.
     */
    public WebContentGenerator() {
        this(true);
    }

    /**
     * Create a new WebContentGenerator.
     * @param restrictDefaultSupportedMethods {@code true} if this
     * generator should support HTTP methods GET, HEAD and POST by default,
     * or {@code false} if it should be unrestricted
     */
    public WebContentGenerator(boolean restrictDefaultSupportedMethods) {
        if (restrictDefaultSupportedMethods) {
            this.supportedMethods = new LinkedHashSet<>(4);
            this.supportedMethods.add(METHOD_GET);
            this.supportedMethods.add(METHOD_HEAD);
            this.supportedMethods.add(METHOD_POST);
        }
        initAllowHeader();
    }

    /**
     * Create a new WebContentGenerator.
     * @param supportedMethods the supported HTTP methods for this content generator
     */
    public WebContentGenerator(String... supportedMethods) {
        setSupportedMethods(supportedMethods);
    }

    /**
     * Set the HTTP methods that this content generator should support.
     * <p>Default is GET, HEAD and POST for simple form controller types;
     * unrestricted for general controllers and interceptors.
     */
    public final void setSupportedMethods(@Nullable String... methods) {
        if (!ObjectUtils.isEmpty(methods)) {
            this.supportedMethods = new LinkedHashSet<>(Arrays.asList(methods));
        } else {
            this.supportedMethods = null;
        }
        initAllowHeader();
    }

    /**
     * Return the HTTP methods that this content generator supports.
     */
    @Nullable
    public final String[] getSupportedMethods() {
        return (this.supportedMethods != null ? StringUtils.toStringArray(this.supportedMethods) : null);
    }

    private void initAllowHeader() {
        Collection<String> allowedMethods;
        if (this.supportedMethods == null) {
            allowedMethods = new ArrayList<>(HttpMethod.values().length - 1);
            for (HttpMethod method : HttpMethod.values()) {
                if (method != HttpMethod.TRACE) {
                    allowedMethods.add(method.name());
                }
            }
        } else if (this.supportedMethods.contains(HttpMethod.OPTIONS.name())) {
            allowedMethods = this.supportedMethods;
        } else {
            allowedMethods = new ArrayList<>(this.supportedMethods);
            allowedMethods.add(HttpMethod.OPTIONS.name());

        }
        this.allowHeader = StringUtils.collectionToCommaDelimitedString(allowedMethods);
    }

    /**
     * Return the "Allow" header value to use in response to an HTTP OPTIONS request
     * based on the configured {@link #setSupportedMethods 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 {@link #checkRequest(HttpServletRequest)}.
     * @since 4.3
     */
    @Nullable
    protected String getAllowHeader() {
        return this.allowHeader;
    }

    /**
     * Set whether a session should be required to handle requests.
     */
    public final void setRequireSession(boolean requireSession) {
        this.requireSession = requireSession;
    }

    /**
     * Return whether a session is required to handle requests.
     */
    public final boolean isRequireSession() {
        return this.requireSession;
    }

    /**
     * Set the {@link org.springframework.http.CacheControl} instance to build
     * the Cache-Control HTTP response header.
     * @since 4.2
     */
    public final void setCacheControl(@Nullable CacheControl cacheControl) {
        this.cacheControl = cacheControl;
    }

    /**
     * Get the {@link org.springframework.http.CacheControl} instance
     * that builds the Cache-Control HTTP response header.
     * @since 4.2
     */
    @Nullable
    public final CacheControl getCacheControl() {
        return this.cacheControl;
    }

    /**
     * Cache content for the given number of seconds, by writing
     * cache-related HTTP headers to the response:
     * <ul>
     * <li>seconds == -1 (default value): no generation cache-related headers</li>
     * <li>seconds == 0: "Cache-Control: no-store" will prevent caching</li>
     * <li>seconds > 0: "Cache-Control: max-age=seconds" will ask to cache content</li>
     * </ul>
     * <p>For more specific needs, a custom {@link org.springframework.http.CacheControl}
     * should be used.
     * @see #setCacheControl
     */
    public final void setCacheSeconds(int seconds) {
        this.cacheSeconds = seconds;
    }

    /**
     * Return the number of seconds that content is cached.
     */
    public final int getCacheSeconds() {
        return this.cacheSeconds;
    }

    /**
     * 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.
     * @param varyByRequestHeaders one or more request header names
     * @since 4.3
     */
    public final void setVaryByRequestHeaders(@Nullable String... varyByRequestHeaders) {
        this.varyByRequestHeaders = varyByRequestHeaders;
    }

    /**
     * Return the configured request header names for the "Vary" response header.
     * @since 4.3
     */
    @Nullable
    public final String[] getVaryByRequestHeaders() {
        return this.varyByRequestHeaders;
    }

    /**
     * Set whether to use the HTTP 1.0 expires header. Default is "false",
     * as of 4.2.
     * <p>Note: Cache headers will only get applied if caching is enabled
     * (or explicitly prevented) for the current request.
     * @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
     */
    @Deprecated
    public final void setUseExpiresHeader(boolean useExpiresHeader) {
        this.useExpiresHeader = useExpiresHeader;
    }

    /**
     * Return whether the HTTP 1.0 expires header is used.
     * @deprecated as of 4.2, in favor of {@link #getCacheControl()}
     */
    @Deprecated
    public final boolean isUseExpiresHeader() {
        return this.useExpiresHeader;
    }

    /**
     * Set whether to use the HTTP 1.1 cache-control header. Default is "true".
     * <p>Note: Cache headers will only get applied if caching is enabled
     * (or explicitly prevented) for the current request.
     * @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
     */
    @Deprecated
    public final void setUseCacheControlHeader(boolean useCacheControlHeader) {
        this.useCacheControlHeader = useCacheControlHeader;
    }

    /**
     * Return whether the HTTP 1.1 cache-control header is used.
     * @deprecated as of 4.2, in favor of {@link #getCacheControl()}
     */
    @Deprecated
    public final boolean isUseCacheControlHeader() {
        return this.useCacheControlHeader;
    }

    /**
     * Set whether to use the HTTP 1.1 cache-control header value "no-store"
     * when preventing caching. Default is "true".
     * @deprecated as of 4.2, in favor of {@link #setCacheControl}
     */
    @Deprecated
    public final void setUseCacheControlNoStore(boolean useCacheControlNoStore) {
        this.useCacheControlNoStore = useCacheControlNoStore;
    }

    /**
     * Return whether the HTTP 1.1 cache-control header value "no-store" is used.
     * @deprecated as of 4.2, in favor of {@link #getCacheControl()}
     */
    @Deprecated
    public final boolean isUseCacheControlNoStore() {
        return this.useCacheControlNoStore;
    }

    /**
     * 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
     * {@link org.springframework.web.context.request.WebRequest#checkNotModified(long)}.
     * <p>Default is "false".
     * @deprecated as of 4.2, in favor of {@link #setCacheControl}
     */
    @Deprecated
    public final void setAlwaysMustRevalidate(boolean mustRevalidate) {
        this.alwaysMustRevalidate = mustRevalidate;
    }

    /**
     * Return whether 'must-revalidate' is added to every Cache-Control header.
     * @deprecated as of 4.2, in favor of {@link #getCacheControl()}
     */
    @Deprecated
    public final boolean isAlwaysMustRevalidate() {
        return this.alwaysMustRevalidate;
    }

    /**
     * Check the given request for supported methods and a required session, if any.
     * @param request current HTTP request
     * @throws ServletException if the request cannot be handled because a check failed
     * @since 4.2
     */
    protected final void checkRequest(HttpServletRequest request) throws ServletException {
        // Check whether we should support the request method.
        String method = request.getMethod();
        if (this.supportedMethods != null && !this.supportedMethods.contains(method)) {
            throw new HttpRequestMethodNotSupportedException(method, this.supportedMethods);
        }

        // Check whether a session is required.
        if (this.requireSession && request.getSession(false) == null) {
            throw new HttpSessionRequiredException("Pre-existing session required but none found");
        }
    }

    /**
     * Prepare the given response according to the settings of this generator.
     * Applies the number of cache seconds specified for this generator.
     * @param response current HTTP response
     * @since 4.2
     */
    protected final void prepareResponse(HttpServletResponse response) {
        if (this.cacheControl != null) {
            applyCacheControl(response, this.cacheControl);
        } else {
            applyCacheSeconds(response, this.cacheSeconds);
        }
        if (this.varyByRequestHeaders != null) {
            for (String value : getVaryRequestHeadersToAdd(response, this.varyByRequestHeaders)) {
                response.addHeader("Vary", value);
            }
        }
    }

    /**
     * Set the HTTP Cache-Control header according to the given settings.
     * @param response current HTTP response
     * @param cacheControl the pre-configured cache control settings
     * @since 4.2
     */
    protected final void applyCacheControl(HttpServletResponse response, CacheControl cacheControl) {
        String ccValue = cacheControl.getHeaderValue();
        if (ccValue != null) {
            // Set computed HTTP 1.1 Cache-Control header
            response.setHeader(HEADER_CACHE_CONTROL, ccValue);

            if (response.containsHeader(HEADER_PRAGMA)) {
                // Reset HTTP 1.0 Pragma header if present
                response.setHeader(HEADER_PRAGMA, "");
            }
            if (response.containsHeader(HEADER_EXPIRES)) {
                // Reset HTTP 1.0 Expires header if present
                response.setHeader(HEADER_EXPIRES, "");
            }
        }
    }

    /**
     * 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.
     * @param response current HTTP response
     * @param cacheSeconds positive number of seconds into the future that the
     * response should be cacheable for, 0 to prevent caching
     */
    @SuppressWarnings("deprecation")
    protected final void applyCacheSeconds(HttpServletResponse response, int cacheSeconds) {
        if (this.useExpiresHeader || !this.useCacheControlHeader) {
            // Deprecated HTTP 1.0 cache behavior, as in previous Spring versions
            if (cacheSeconds > 0) {
                cacheForSeconds(response, cacheSeconds);
            } else if (cacheSeconds == 0) {
                preventCaching(response);
            }
        } else {
            CacheControl cControl;
            if (cacheSeconds > 0) {
                cControl = CacheControl.maxAge(cacheSeconds, TimeUnit.SECONDS);
                if (this.alwaysMustRevalidate) {
                    cControl = cControl.mustRevalidate();
                }
            } else if (cacheSeconds == 0) {
                cControl = (this.useCacheControlNoStore ? CacheControl.noStore() : CacheControl.noCache());
            } else {
                cControl = CacheControl.empty();
            }
            applyCacheControl(response, cControl);
        }
    }

    /**
     * Check and prepare the given request and response according to the settings
     * of this generator.
     * @see #checkRequest(HttpServletRequest)
     * @see #prepareResponse(HttpServletResponse)
     * @deprecated as of 4.2, since the {@code lastModified} flag is effectively ignored,
     * with a must-revalidate header only generated if explicitly configured
     */
    @Deprecated
    protected final void checkAndPrepare(HttpServletRequest request, HttpServletResponse response,
            boolean lastModified) throws ServletException {

        checkRequest(request);
        prepareResponse(response);
    }

    /**
     * Check and prepare the given request and response according to the settings
     * of this generator.
     * @see #checkRequest(HttpServletRequest)
     * @see #applyCacheSeconds(HttpServletResponse, int)
     * @deprecated as of 4.2, since the {@code lastModified} flag is effectively ignored,
     * with a must-revalidate header only generated if explicitly configured
     */
    @Deprecated
    protected final void checkAndPrepare(HttpServletRequest request, HttpServletResponse response, int cacheSeconds,
            boolean lastModified) throws ServletException {

        checkRequest(request);
        applyCacheSeconds(response, cacheSeconds);
    }

    /**
     * Apply the given cache seconds and generate respective HTTP headers.
     * <p>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).
     * @param response the current HTTP response
     * @param 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.
     * @param mustRevalidate whether the client should revalidate the resource
     * (typically only necessary for controllers with last-modified support)
     * @deprecated as of 4.2, in favor of {@link #applyCacheControl}
     */
    @Deprecated
    protected final void applyCacheSeconds(HttpServletResponse response, int cacheSeconds, boolean mustRevalidate) {
        if (cacheSeconds > 0) {
            cacheForSeconds(response, cacheSeconds, mustRevalidate);
        } else if (cacheSeconds == 0) {
            preventCaching(response);
        }
    }

    /**
     * Set HTTP headers to allow caching for the given number of seconds.
     * Does not tell the browser to revalidate the resource.
     * @param response current HTTP response
     * @param seconds number of seconds into the future that the response
     * should be cacheable for
     * @deprecated as of 4.2, in favor of {@link #applyCacheControl}
     */
    @Deprecated
    protected final void cacheForSeconds(HttpServletResponse response, int seconds) {
        cacheForSeconds(response, seconds, false);
    }

    /**
     * Set HTTP headers to allow caching for the given number of seconds.
     * Tells the browser to revalidate the resource if mustRevalidate is
     * {@code true}.
     * @param response the current HTTP response
     * @param seconds number of seconds into the future that the response
     * should be cacheable for
     * @param mustRevalidate whether the client should revalidate the resource
     * (typically only necessary for controllers with last-modified support)
     * @deprecated as of 4.2, in favor of {@link #applyCacheControl}
     */
    @Deprecated
    protected final void cacheForSeconds(HttpServletResponse response, int seconds, boolean mustRevalidate) {
        if (this.useExpiresHeader) {
            // HTTP 1.0 header
            response.setDateHeader(HEADER_EXPIRES, System.currentTimeMillis() + seconds * 1000L);
        } else if (response.containsHeader(HEADER_EXPIRES)) {
            // Reset HTTP 1.0 Expires header if present
            response.setHeader(HEADER_EXPIRES, "");
        }

        if (this.useCacheControlHeader) {
            // HTTP 1.1 header
            String headerValue = "max-age=" + seconds;
            if (mustRevalidate || this.alwaysMustRevalidate) {
                headerValue += ", must-revalidate";
            }
            response.setHeader(HEADER_CACHE_CONTROL, headerValue);
        }

        if (response.containsHeader(HEADER_PRAGMA)) {
            // Reset HTTP 1.0 Pragma header if present
            response.setHeader(HEADER_PRAGMA, "");
        }
    }

    /**
     * Prevent the response from being cached.
     * Only called in HTTP 1.0 compatibility mode.
     * <p>See {@code https://www.mnot.net/cache_docs}.
     * @deprecated as of 4.2, in favor of {@link #applyCacheControl}
     */
    @Deprecated
    protected final void preventCaching(HttpServletResponse response) {
        response.setHeader(HEADER_PRAGMA, "no-cache");

        if (this.useExpiresHeader) {
            // HTTP 1.0 Expires header
            response.setDateHeader(HEADER_EXPIRES, 1L);
        }

        if (this.useCacheControlHeader) {
            // HTTP 1.1 Cache-Control header: "no-cache" is the standard value,
            // "no-store" is necessary to prevent caching on Firefox.
            response.setHeader(HEADER_CACHE_CONTROL, "no-cache");
            if (this.useCacheControlNoStore) {
                response.addHeader(HEADER_CACHE_CONTROL, "no-store");
            }
        }
    }

    private Collection<String> getVaryRequestHeadersToAdd(HttpServletResponse response,
            String[] varyByRequestHeaders) {
        if (!response.containsHeader(HttpHeaders.VARY)) {
            return Arrays.asList(varyByRequestHeaders);
        }
        Collection<String> result = new ArrayList<>(varyByRequestHeaders.length);
        Collections.addAll(result, varyByRequestHeaders);
        for (String header : response.getHeaders(HttpHeaders.VARY)) {
            for (String existing : StringUtils.tokenizeToStringArray(header, ",")) {
                if ("*".equals(existing)) {
                    return Collections.emptyList();
                }
                for (String value : varyByRequestHeaders) {
                    if (value.equalsIgnoreCase(existing)) {
                        result.remove(value);
                    }
                }
            }
        }
        return result;
    }

}