Apache Tomcat 7.0.54

org.apache.catalina.filters
Class CorsFilter

java.lang.Object
  extended by org.apache.catalina.filters.CorsFilter
All Implemented Interfaces:
Filter

public final class CorsFilter
extends Object
implements Filter

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.

See Also:
CORS specification

Nested Class Summary
protected static class CorsFilter.CORSRequestType
          Enumerates varies types of CORS requests.
 
Field Summary
static Collection<String> COMPLEX_HTTP_METHODS
          Collection of non-simple HTTP methods.
static 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 String DEFAULT_ALLOWED_HTTP_METHODS
          By default, following methods are supported: GET, POST, HEAD and OPTIONS.
static String DEFAULT_ALLOWED_ORIGINS
          By default, all origins are allowed to make requests.
static String DEFAULT_DECORATE_REQUEST
          By default, request is decorated with CORS attributes.
static String DEFAULT_EXPOSED_HEADERS
          By default, none of the headers are exposed in response.
static String DEFAULT_PREFLIGHT_MAXAGE
          By default, time duration to cache pre-flight response is 30 mins.
static String DEFAULT_SUPPORTS_CREDENTIALS
          By default, support credentials is turned on.
static Collection<String> HTTP_METHODS
          Collection of HTTP methods.
static String HTTP_REQUEST_ATTRIBUTE_IS_CORS_REQUEST
          Boolean value, suggesting if the request is a CORS request or not.
static String HTTP_REQUEST_ATTRIBUTE_ORIGIN
          Attribute that contains the origin of the request.
static String HTTP_REQUEST_ATTRIBUTE_PREFIX
          The prefix to a CORS request attribute.
static String HTTP_REQUEST_ATTRIBUTE_REQUEST_HEADERS
          Request headers sent as 'Access-Control-Request-Headers' header, for pre-flight request.
static String HTTP_REQUEST_ATTRIBUTE_REQUEST_TYPE
          Type of CORS request, of type CorsFilter.CORSRequestType.
static String PARAM_CORS_ALLOWED_HEADERS
          Key to retrieve allowed headers from FilterConfig.
static String PARAM_CORS_ALLOWED_METHODS
          Key to retrieve allowed methods from FilterConfig.
static String PARAM_CORS_ALLOWED_ORIGINS
          Key to retrieve allowed origins from FilterConfig.
static String PARAM_CORS_EXPOSED_HEADERS
          Key to retrieve exposed headers from FilterConfig.
static String PARAM_CORS_PREFLIGHT_MAXAGE
          Key to retrieve preflight max age from FilterConfig.
static String PARAM_CORS_REQUEST_DECORATE
          Key to determine if request should be decorated.
static String PARAM_CORS_SUPPORT_CREDENTIALS
          Key to retrieve support credentials from FilterConfig.
static 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 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 String REQUEST_HEADER_ORIGIN
          The Origin header indicates where the cross-origin request or preflight request originates from.
static 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 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 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 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 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 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 Collection<String> SIMPLE_HTTP_METHODS
          Collection of Simple HTTP methods.
static Collection<String> SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES
          Collection of Simple HTTP request headers.
static Collection<String> SIMPLE_HTTP_REQUEST_HEADERS
          Collection of Simple HTTP request headers.
static Collection<String> SIMPLE_HTTP_RESPONSE_HEADERS
          Collection of Simple HTTP request headers.
 
Constructor Summary
CorsFilter()
           
 
Method Summary
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 destroy()
          Called by the web container to indicate to a filter that it is being taken out of service.
 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()
          Returns a Set of headers that should be exposed by browser.
 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(FilterConfig filterConfig)
          Called by the web container to indicate to a filter that it is being placed into service.
 boolean isAnyOriginAllowed()
          Determines if any origin is allowed to make CORS request.
 boolean isSupportsCredentials()
          Determines is supports credentials is enabled.
protected static boolean isValidOrigin(String origin)
          Checks if a given origin is valid or not.
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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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_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

HTTP_METHODS

public static final Collection<String> HTTP_METHODS
Collection of HTTP methods. Case sensitive.

See Also:
http://tools.ietf.org/html/rfc2616#section-5.1.1

COMPLEX_HTTP_METHODS

public static final Collection<String> COMPLEX_HTTP_METHODS
Collection of non-simple HTTP methods. Case sensitive.


SIMPLE_HTTP_METHODS

public static final Collection<String> SIMPLE_HTTP_METHODS
Collection of Simple HTTP methods. Case sensitive.

See Also:
http://www.w3.org/TR/cors/#terminology

SIMPLE_HTTP_REQUEST_HEADERS

public static final Collection<String> SIMPLE_HTTP_REQUEST_HEADERS
Collection of Simple HTTP request headers. Case in-sensitive.

See Also:
http://www.w3.org/TR/cors/#terminology

SIMPLE_HTTP_RESPONSE_HEADERS

public static final Collection<String> SIMPLE_HTTP_RESPONSE_HEADERS
Collection of Simple HTTP request headers. Case in-sensitive.

See Also:
http://www.w3.org/TR/cors/#terminology

SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES

public static final Collection<String> SIMPLE_HTTP_REQUEST_CONTENT_TYPE_VALUES
Collection of Simple HTTP request headers. Case in-sensitive.

See Also:
http://www.w3.org/TR/cors/#terminology

DEFAULT_ALLOWED_ORIGINS

public static final String DEFAULT_ALLOWED_ORIGINS
By default, all 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 turned on.

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 Detail

CorsFilter

public CorsFilter()
Method Detail

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.

Specified by:
doFilter in interface Filter
Throws:
IOException
ServletException

init

public void init(FilterConfig filterConfig)
          throws ServletException
Description copied from interface: javax.servlet.Filter
Called by the web container to indicate to a filter that it is being placed into service. The servlet container calls the init method exactly once after instantiating the filter. The init method must complete successfully before the filter is asked to do any filtering work.

The web container cannot place the filter into service if the init method either
1.Throws a ServletException
2.Does not return within a time period defined by the web container

Specified by:
init in interface Filter
Throws:
ServletException

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
ServletException
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
ServletException

destroy

public void destroy()
Description copied from interface: javax.servlet.Filter
Called by the web container to indicate to a filter that it is being taken out of service. This method is only called once all threads within the filter's doFilter method have exited or after a timeout period has passed. After the web container calls this method, it will not call the doFilter method again on this instance of the filter.

This method gives the filter an opportunity to clean up any resources that are being held (for example, memory, file handles, threads) and make sure that any persistent state is synchronized with the filter's current state in memory.

Specified by:
destroy in interface Filter

decorateCORSProperties

protected static void decorateCORSProperties(HttpServletRequest request,
                                             CorsFilter.CORSRequestType corsRequestType)
Decorates the HttpServletRequest, with CORS attributes.

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 -

isValidOrigin

protected static boolean isValidOrigin(String origin)
Checks if a given origin is valid or not. Criteria:

Parameters:
origin -
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()
Returns a Set of headers that should be exposed by browser.


isSupportsCredentials

public boolean isSupportsCredentials()
Determines is supports credentials is enabled.


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

Apache Tomcat 7.0.54

Copyright © 2000-2014 Apache Software Foundation. All Rights Reserved.