CorsFilter (Apache Tomcat 9.0.111 API Documentation)
Description: declaration: package: org.apache.catalina.filters, class: CorsFilter

# Class CorsFilter

java.lang.Object
javax.servlet.GenericFilter
org.apache.catalina.filters.CorsFilter

All Implemented Interfaces:
  `Serializable, Filter, FilterConfig`

public class CorsFilter extends GenericFilter

A `Filter` that enable client-side cross-origin requests by implementing W3C's CORS (Cross-Origin Resource Sharing) specification for resources. Each `HttpServletRequest` request is inspected as per specification, and appropriate response headers are added to `HttpServletResponse`.

By default, it also sets following request attributes, that help to determine the nature of the request downstream.

- cors.isCorsRequest: Flag to determine if the request is a CORS request. Set to `true` if a CORS request; `false` otherwise.
- cors.request.origin: The Origin URL, i.e. the URL of the page from where the request is originated.
- cors.request.type: Type of request. Possible values:
  - SIMPLE: A request which is not preceded by a pre-flight request.
  - ACTUAL: A request which is preceded by a pre-flight request.
  - PRE_FLIGHT: A pre-flight request.
  - NOT_CORS: A normal same-origin request.
  - INVALID_CORS: A cross-origin request which is invalid.
- cors.request.headers: Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.

If you extend this class and override one or more of the getXxx() methods, consider whether you also need to override `doFilter(ServletRequest, ServletResponse, FilterChain)` and add appropriate locking so that the `doFilter()` method executes with a consistent configuration.

See Also:
  - CORS specification
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static enum`
  `CorsFilter.CORSRequestType`
  Enumerates varies types of CORS requests.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_ALLOWED_HTTP_HEADERS`
  By default, following headers are supported: Origin,Accept,X-Requested-With, Content-Type, Access-Control-Request-Method, and Access-Control-Request-Headers.
  `static final String`
  `DEFAULT_ALLOWED_HTTP_METHODS`
  By default, following methods are supported: GET, POST, HEAD and OPTIONS.
  `static final String`
  `DEFAULT_ALLOWED_ORIGINS`
  By default, no origins are allowed to make requests.
  `static final String`
  `DEFAULT_DECORATE_REQUEST`
  By default, request is decorated with CORS attributes.
  `static final String`
  `DEFAULT_EXPOSED_HEADERS`
  By default, none of the headers are exposed in response.
  `static final String`
  `DEFAULT_PREFLIGHT_MAXAGE`
  By default, time duration to cache pre-flight response is 30 mins.
  `static final String`
  `DEFAULT_SUPPORTS_CREDENTIALS`
  By default, support credentials is disabled.
  `static final String`
  `HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST`
  Boolean value, suggesting if the request is a CORS request or not.
  `static final String`
  `HTTP_REQUEST_ATTRIBUTE_ORIGIN`
  Attribute that contains the origin of the request.
  `static final String`
  `HTTP_REQUEST_ATTRIBUTE_PREFIX`
  The prefix to a CORS request attribute.
  `static final String`
  `HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS`
  Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.
  `static final String`
  `HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE`
  Type of CORS request, of type `CorsFilter.CORSRequestType`.
  `static final String`
  `PARAM_CORS_ALLOWED_HEADERS`
  Key to retrieve allowed headers from `FilterConfig`.
  `static final String`
  `PARAM_CORS_ALLOWED_METHODS`
  Key to retrieve allowed methods from `FilterConfig`.
  `static final String`
  `PARAM_CORS_ALLOWED_ORIGINS`
  Key to retrieve allowed origins from `FilterConfig`.
  `static final String`
  `PARAM_CORS_EXPOSED_HEADERS`
  Key to retrieve exposed headers from `FilterConfig`.
  `static final String`
  `PARAM_CORS_PREFLIGHT_MAXAGE`
  Key to retrieve preflight max age from `FilterConfig`.
  `static final String`
  `PARAM_CORS_REQUEST_DECORATE`
  Key to determine if request should be decorated.
  `static final String`
  `PARAM_CORS_SUPPORT_CREDENTIALS`
  Key to retrieve support credentials from `FilterConfig`.
  `static final String`
  `REQUEST_HEADER_ACCESS_CONTROL_REQUEST_HEADERS`
  The Access-Control-Request-Headers header indicates which headers will be used in the actual request as part of the preflight request.
  `static final String`
  `REQUEST_HEADER_ACCESS_CONTROL_REQUEST_METHOD`
  The Access-Control-Request-Method header indicates which method will be used in the actual request as part of the preflight request.
  `static final String`
  `REQUEST_HEADER_ORIGIN`
  The Origin header indicates where the cross-origin request or preflight request originates from.
  `static final String`
  `REQUEST_HEADER_VARY`
  Deprecated.
  Unused.
  `static final String`
  `RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS`
  The Access-Control-Allow-Credentials header indicates whether the response to request can be exposed when the omit credentials flag is unset.
  `static final String`
  `RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_HEADERS`
  The Access-Control-Allow-Headers header indicates, as part of the response to a preflight request, which header field names can be used during the actual request.
  `static final String`
  `RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_METHODS`
  The Access-Control-Allow-Methods header indicates, as part of the response to a preflight request, which methods can be used during the actual request.
  `static final String`
  `RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN`
  The Access-Control-Allow-Origin header indicates whether a resource can be shared based by returning the value of the Origin request header in the response.
  `static final String`
  `RESPONSE_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS`
  The Access-Control-Expose-Headers header indicates which headers are safe to expose to the API of a CORS API specification
  `static final String`
  `RESPONSE_HEADER_ACCESS_CONTROL_MAX_AGE`
  The Access-Control-Max-Age header indicates how long the results of a preflight request can be cached in a preflight result cache.
  `static final Collection<String>`
  `SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES`
  `Collection` of media type values for the Content-Type header that will be treated as 'simple'.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CorsFilter()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected CorsFilter.CORSRequestType`
  `checkRequestType(HttpServletRequest request)`
  Determines the request type.
  `protected static void`
  `decorateCORSProperties(HttpServletRequest request, CorsFilter.CORSRequestType corsRequestType)`
  Decorates the `HttpServletRequest`, with CORS attributes.
  `void`
  `doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)`
  The `doFilter` method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain.
  `Collection<String>`
  `getAllowedHttpHeaders()`
  Returns a `Set` of headers support by resource.
  `Collection<String>`
  `getAllowedHttpMethods()`
  Returns a `Set` of HTTP methods that are allowed to make requests.
  `Collection<String>`
  `getAllowedOrigins()`
  Returns the `Set` of allowed origins that are allowed to make requests.
  `Collection<String>`
  `getExposedHeaders()`
  Obtain the headers to expose.
  `long`
  `getPreflightMaxAge()`
  Returns the preflight response cache time in seconds.
  `protected void`
  `handlePreflightCORS(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)`
  Handles CORS pre-flight request.
  `protected void`
  `handleSimpleCORS(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)`
  Handles a CORS request of type `CorsFilter.CORSRequestType`.SIMPLE.
  `void`
  `init()`
  Convenience method for sub-classes to save them having to call `super.init(config)`.
  `boolean`
  `isAnyOriginAllowed()`
  Determines if any origin is allowed to make CORS request.
  `boolean`
  `isDecorateRequest()`
  Should CORS specific attributes be added to the request.
  `boolean`
  `isSupportsCredentials()`
  Determines is supports credentials is enabled.
  `protected static boolean`
  `isValidOrigin(String origin)`
  Deprecated.
  This will be removed in Tomcat 10 Use `RequestUtil.isValidOrigin(String)`
  `protected static String`
  `join(Collection<String> elements, String joinSeparator)`
  Joins elements of `Set` into a string, where each element is separated by the provided separator.

  ### Methods inherited from class GenericFilter

  `getFilterConfig, getFilterName, getInitParameter, getInitParameterNames, getServletContext, init`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface Filter

  `destroy`

- ## Field Details

  - ### RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN

    public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN
    The Access-Control-Allow-Origin header indicates whether a resource can be shared based by returning the value of the Origin request header in the response.
    See Also:
      - Constant Field Values

  - ### RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS

    public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS
    The Access-Control-Allow-Credentials header indicates whether the response to request can be exposed when the omit credentials flag is unset. When part of the response to a preflight request it indicates that the actual request can include user credentials.
    See Also:
      - Constant Field Values

  - ### RESPONSE_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS

    public static final String RESPONSE_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS
    The Access-Control-Expose-Headers header indicates which headers are safe to expose to the API of a CORS API specification
    See Also:
      - Constant Field Values

  - ### RESPONSE_HEADER_ACCESS_CONTROL_MAX_AGE

    public static final String RESPONSE_HEADER_ACCESS_CONTROL_MAX_AGE
    The Access-Control-Max-Age header indicates how long the results of a preflight request can be cached in a preflight result cache.
    See Also:
      - Constant Field Values

  - ### RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_METHODS

    public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_METHODS
    The Access-Control-Allow-Methods header indicates, as part of the response to a preflight request, which methods can be used during the actual request.
    See Also:
      - Constant Field Values

  - ### RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_HEADERS

    public static final String RESPONSE_HEADER_ACCESS_CONTROL_ALLOW_HEADERS
    The Access-Control-Allow-Headers header indicates, as part of the response to a preflight request, which header field names can be used during the actual request.
    See Also:
      - Constant Field Values

  - ### REQUEST_HEADER_VARY

    @Deprecated public static final String REQUEST_HEADER_VARY
    Deprecated.
    Unused. Will be removed in Tomcat 10
    The Vary header indicates allows disabling proxy caching by indicating the the response depends on the origin.
    See Also:
      - Constant Field Values

  - ### REQUEST_HEADER_ORIGIN

    public static final String REQUEST_HEADER_ORIGIN
    The Origin header indicates where the cross-origin request or preflight request originates from.
    See Also:
      - Constant Field Values

  - ### REQUEST_HEADER_ACCESS_CONTROL_REQUEST_METHOD

    public static final String REQUEST_HEADER_ACCESS_CONTROL_REQUEST_METHOD
    The Access-Control-Request-Method header indicates which method will be used in the actual request as part of the preflight request.
    See Also:
      - Constant Field Values

  - ### REQUEST_HEADER_ACCESS_CONTROL_REQUEST_HEADERS

    public static final String REQUEST_HEADER_ACCESS_CONTROL_REQUEST_HEADERS
    The Access-Control-Request-Headers header indicates which headers will be used in the actual request as part of the preflight request.
    See Also:
      - Constant Field Values

  - ### HTTP_REQUEST_ATTRIBUTE_PREFIX

    public static final String HTTP_REQUEST_ATTRIBUTE_PREFIX
    The prefix to a CORS request attribute.
    See Also:
      - Constant Field Values

  - ### HTTP_REQUEST_ATTRIBUTE_ORIGIN

    public static final String HTTP_REQUEST_ATTRIBUTE_ORIGIN
    Attribute that contains the origin of the request.
    See Also:
      - Constant Field Values

  - ### HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST

    public static final String HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST
    Boolean value, suggesting if the request is a CORS request or not.
    See Also:
      - Constant Field Values

  - ### HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE

    public static final String HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE
    Type of CORS request, of type `CorsFilter.CORSRequestType`.
    See Also:
      - Constant Field Values

  - ### HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS

    public static final String HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS
    Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.
    See Also:
      - Constant Field Values

  - ### SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES

    public static final Collection<String> SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES
    `Collection` of media type values for the Content-Type header that will be treated as 'simple'. Note media-type values are compared ignoring parameters and in a case-insensitive manner.
    See Also:
      - http://www.w3.org/TR/cors/#terminology

  - ### DEFAULT_ALLOWED_ORIGINS

    public static final String DEFAULT_ALLOWED_ORIGINS
    By default, no origins are allowed to make requests.
    See Also:
      - Constant Field Values

  - ### DEFAULT_ALLOWED_HTTP_METHODS

    public static final String DEFAULT_ALLOWED_HTTP_METHODS
    By default, following methods are supported: GET, POST, HEAD and OPTIONS.
    See Also:
      - Constant Field Values

  - ### DEFAULT_PREFLIGHT_MAXAGE

    public static final String DEFAULT_PREFLIGHT_MAXAGE
    By default, time duration to cache pre-flight response is 30 mins.
    See Also:
      - Constant Field Values

  - ### DEFAULT_SUPPORTS_CREDENTIALS

    public static final String DEFAULT_SUPPORTS_CREDENTIALS
    By default, support credentials is disabled.
    See Also:
      - Constant Field Values

  - ### DEFAULT_ALLOWED_HTTP_HEADERS

    public static final String DEFAULT_ALLOWED_HTTP_HEADERS
    By default, following headers are supported: Origin,Accept,X-Requested-With, Content-Type, Access-Control-Request-Method, and Access-Control-Request-Headers.
    See Also:
      - Constant Field Values

  - ### DEFAULT_EXPOSED_HEADERS

    public static final String DEFAULT_EXPOSED_HEADERS
    By default, none of the headers are exposed in response.
    See Also:
      - Constant Field Values

  - ### DEFAULT_DECORATE_REQUEST

    public static final String DEFAULT_DECORATE_REQUEST
    By default, request is decorated with CORS attributes.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_ALLOWED_ORIGINS

    public static final String PARAM_CORS_ALLOWED_ORIGINS
    Key to retrieve allowed origins from `FilterConfig`.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_SUPPORT_CREDENTIALS

    public static final String PARAM_CORS_SUPPORT_CREDENTIALS
    Key to retrieve support credentials from `FilterConfig`.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_EXPOSED_HEADERS

    public static final String PARAM_CORS_EXPOSED_HEADERS
    Key to retrieve exposed headers from `FilterConfig`.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_ALLOWED_HEADERS

    public static final String PARAM_CORS_ALLOWED_HEADERS
    Key to retrieve allowed headers from `FilterConfig`.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_ALLOWED_METHODS

    public static final String PARAM_CORS_ALLOWED_METHODS
    Key to retrieve allowed methods from `FilterConfig`.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_PREFLIGHT_MAXAGE

    public static final String PARAM_CORS_PREFLIGHT_MAXAGE
    Key to retrieve preflight max age from `FilterConfig`.
    See Also:
      - Constant Field Values

  - ### PARAM_CORS_REQUEST_DECORATE

    public static final String PARAM_CORS_REQUEST_DECORATE
    Key to determine if request should be decorated.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### CorsFilter

    public CorsFilter()

- ## Method Details

  - ### doFilter

    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException
    Description copied from interface: `javax.servlet.Filter`
    The `doFilter` method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain. The FilterChain passed in to this method allows the Filter to pass on the request and response to the next entity in the chain.

    A typical implementation of this method would follow the following pattern:-
    1. Examine the request
    2. Optionally wrap the request object with a custom implementation to filter content or headers for input filtering
    3. Optionally wrap the response object with a custom implementation to filter content or headers for output filtering
    4. a) Either invoke the next entity in the chain using the FilterChain object (`chain.doFilter()`),
    4. b) or not pass on the request/response pair to the next entity in the filter chain to block the request processing
    5. Directly set headers on the response after invocation of the next entity in the filter chain.

    Parameters:
      `servletRequest` - The request to process
      `servletResponse` - The response associated with the request
      `filterChain` - Provides access to the next filter in the chain for this filter to pass the request and response to for further processing
    Throws:
      `IOException` - if an I/O error occurs during this filter's processing of the request
      `ServletException` - if the processing fails for any other reason

  - ### init

    public void init() throws ServletException
    Description copied from class: `javax.servlet.GenericFilter`
    Convenience method for sub-classes to save them having to call `super.init(config)`. This is a NO-OP by default.
    Overrides:
      `init` in class `GenericFilter`
    Throws:
      `ServletException` - If an exception occurs that interrupts the Filter's normal operation

  - ### handleSimpleCORS

    protected void handleSimpleCORS(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws IOException, ServletException
    Handles a CORS request of type `CorsFilter.CORSRequestType`.SIMPLE.
    Parameters:
      `request` - The `HttpServletRequest` object.
      `response` - The `HttpServletResponse` object.
      `filterChain` - The `FilterChain` object.
    Throws:
      `IOException` - an IO error occurred
      `ServletException` - Servlet error propagation
    See Also:
      - Simple Cross-Origin Request, Actual Request, and Redirects

  - ### handlePreflightCORS

    protected void handlePreflightCORS(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws IOException, ServletException
    Handles CORS pre-flight request.
    Parameters:
      `request` - The `HttpServletRequest` object.
      `response` - The `HttpServletResponse` object.
      `filterChain` - The `FilterChain` object.
    Throws:
      `IOException` - an IO error occurred
      `ServletException` - Servlet error propagation

  - ### decorateCORSProperties

    protected static void decorateCORSProperties(HttpServletRequest request, CorsFilter.CORSRequestType corsRequestType)
    Decorates the `HttpServletRequest`, with CORS attributes.
    - cors.isCorsRequest: Flag to determine if request is a CORS request. Set to `true` if CORS request; `false` otherwise.
    - cors.request.origin: The Origin URL.
    - cors.request.type: Type of request. Values: `simple` or `preflight` or `not_cors` or `invalid_cors`
    - cors.request.headers: Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.
    Parameters:
      `request` - The `HttpServletRequest` object.
      `corsRequestType` - The `CorsFilter.CORSRequestType` object.

  - ### join

    protected static String join(Collection<String> elements, String joinSeparator)
    Joins elements of `Set` into a string, where each element is separated by the provided separator.
    Parameters:
      `elements` - The `Set` containing elements to join together.
      `joinSeparator` - The character to be used for separating elements.
    Returns:
      The joined `String`; `null` if elements `Set` is null.

  - ### checkRequestType

    protected CorsFilter.CORSRequestType checkRequestType(HttpServletRequest request)
    Determines the request type.
    Parameters:
      `request` - The HTTP Servlet request
    Returns:
      the CORS type

  - ### isValidOrigin

    @Deprecated protected static boolean isValidOrigin(String origin)
    Deprecated.
    This will be removed in Tomcat 10 Use `RequestUtil.isValidOrigin(String)`
    Checks if a given origin is valid or not. Criteria:
    - If an encoded character is present in origin, it's not valid.
    - If origin is "null", it's valid.
    - Origin should be a valid URI
    Parameters:
      `origin` - The origin URI
    Returns:
      `true` if the origin was valid
    See Also:
      - RFC952

  - ### isAnyOriginAllowed

    public boolean isAnyOriginAllowed()
    Determines if any origin is allowed to make CORS request.
    Returns:
      `true` if it's enabled; false otherwise.

  - ### getExposedHeaders

    public Collection<String> getExposedHeaders()
    Obtain the headers to expose.
    Returns:
      the headers that should be exposed by browser.

  - ### isSupportsCredentials

    public boolean isSupportsCredentials()
    Determines is supports credentials is enabled.
    Returns:
      `true` if the use of credentials is supported otherwise `false`

  - ### getPreflightMaxAge

    public long getPreflightMaxAge()
    Returns the preflight response cache time in seconds.
    Returns:
      Time to cache in seconds.

  - ### getAllowedOrigins

    public Collection<String> getAllowedOrigins()
    Returns the `Set` of allowed origins that are allowed to make requests.
    Returns:
      `Set`

  - ### getAllowedHttpMethods

    public Collection<String> getAllowedHttpMethods()
    Returns a `Set` of HTTP methods that are allowed to make requests.
    Returns:
      `Set`

  - ### getAllowedHttpHeaders

    public Collection<String> getAllowedHttpHeaders()
    Returns a `Set` of headers support by resource.
    Returns:
      `Set`

  - ### isDecorateRequest

    public boolean isDecorateRequest()
    Should CORS specific attributes be added to the request.
    Returns:
      `true` if the request should be decorated, otherwise `false`