io.netty.handler.codec.http.cors

Class CorsConfigBuilder

java.lang.Object

io.netty.handler.codec.http.cors.CorsConfigBuilder

public final class CorsConfigBuilder
extends Object

Builder used to configure and build a CorsConfig instance.

Method Summary

Modifier and Type	Method and Description
CorsConfigBuilder	allowCredentials() By default cookies are not included in CORS requests, but this method will enable cookies to be added to CORS requests.
CorsConfigBuilder	allowedRequestHeaders(CharSequence... headers) Specifies the if headers that should be returned in the CORS 'Access-Control-Allow-Headers' response header.
CorsConfigBuilder	allowedRequestHeaders(String... headers) Specifies the if headers that should be returned in the CORS 'Access-Control-Allow-Headers' response header.
CorsConfigBuilder	allowedRequestMethods(HttpMethod... methods) Specifies the allowed set of HTTP Request Methods that should be returned in the CORS 'Access-Control-Request-Method' response header.
CorsConfigBuilder	allowNullOrigin() Web browsers may set the 'Origin' request header to 'null' if a resource is loaded from the local file system.
CorsConfig	build() Builds a CorsConfig with settings specified by previous method calls.
CorsConfigBuilder	disable() Disables CORS support.
CorsConfigBuilder	exposeHeaders(CharSequence... headers) Specifies the headers to be exposed to calling clients.
CorsConfigBuilder	exposeHeaders(String... headers) Specifies the headers to be exposed to calling clients.
static CorsConfigBuilder	forAnyOrigin() Creates a Builder instance with it's origin set to '*'.
static CorsConfigBuilder	forOrigin(String origin) Creates a CorsConfigBuilder instance with the specified origin.
static CorsConfigBuilder	forOrigins(String... origins) Creates a CorsConfigBuilder instance with the specified origins.
CorsConfigBuilder	maxAge(long max) When making a preflight request the client has to perform two request with can be inefficient.
CorsConfigBuilder	noPreflightResponseHeaders() Specifies that no preflight response headers should be added to a preflight response.
<T> CorsConfigBuilder	preflightResponseHeader(CharSequence name, Callable<T> valueGenerator) Returns HTTP response headers that should be added to a CORS preflight response.
<T> CorsConfigBuilder	preflightResponseHeader(CharSequence name, Iterable<T> value) Returns HTTP response headers that should be added to a CORS preflight response.
CorsConfigBuilder	preflightResponseHeader(CharSequence name, Object... values) Returns HTTP response headers that should be added to a CORS preflight response.
CorsConfigBuilder	shortCircuit() Specifies that a CORS request should be rejected if it's invalid before being further processing.

Methods inherited from class java.lang.Object

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

Method Detail

forAnyOrigin

public static CorsConfigBuilder forAnyOrigin()

Creates a Builder instance with it's origin set to '*'.

Returns:

Builder to support method chaining.

forOrigin

public static CorsConfigBuilder forOrigin(String origin)

Creates a CorsConfigBuilder instance with the specified origin.

Returns:

CorsConfigBuilder to support method chaining.

forOrigins

public static CorsConfigBuilder forOrigins(String... origins)

Creates a CorsConfigBuilder instance with the specified origins.

Returns:

CorsConfigBuilder to support method chaining.

allowNullOrigin

public CorsConfigBuilder allowNullOrigin()

Web browsers may set the 'Origin' request header to 'null' if a resource is loaded from the local file system. Calling this method will enable a successful CORS response with a "null" value for the the CORS response header 'Access-Control-Allow-Origin'.

Returns:

CorsConfigBuilder to support method chaining.

disable

public CorsConfigBuilder disable()

Disables CORS support.

Returns:

CorsConfigBuilder to support method chaining.

exposeHeaders

public CorsConfigBuilder exposeHeaders(String... headers)

Specifies the headers to be exposed to calling clients. During a simple CORS request, only certain response headers are made available by the browser, for example using:

 xhr.getResponseHeader("Content-Type");
 

The headers that are available by default are:

• Cache-Control
• Content-Language
• Content-Type
• Expires
• Last-Modified
• Pragma

To expose other headers they need to be specified which is what this method enables by adding the headers to the CORS 'Access-Control-Expose-Headers' response header.

Parameters:

headers - the values to be added to the 'Access-Control-Expose-Headers' response header

Returns:

CorsConfigBuilder to support method chaining.

exposeHeaders

public CorsConfigBuilder exposeHeaders(CharSequence... headers)

Specifies the headers to be exposed to calling clients. During a simple CORS request, only certain response headers are made available by the browser, for example using:

 xhr.getResponseHeader(HttpHeaderNames.CONTENT_TYPE);
 

The headers that are available by default are:

• Cache-Control
• Content-Language
• Content-Type
• Expires
• Last-Modified
• Pragma

To expose other headers they need to be specified which is what this method enables by adding the headers to the CORS 'Access-Control-Expose-Headers' response header.

Parameters:

headers - the values to be added to the 'Access-Control-Expose-Headers' response header

Returns:

CorsConfigBuilder to support method chaining.

allowCredentials

public CorsConfigBuilder allowCredentials()

By default cookies are not included in CORS requests, but this method will enable cookies to be added to CORS requests. Calling this method will set the CORS 'Access-Control-Allow-Credentials' response header to true. Please note, that cookie support needs to be enabled on the client side as well. The client needs to opt-in to send cookies by calling:

 xhr.withCredentials = true;
 

The default value for 'withCredentials' is false in which case no cookies are sent. Setting this to true will included cookies in cross origin requests.

Returns:

CorsConfigBuilder to support method chaining.

maxAge

public CorsConfigBuilder maxAge(long max)

When making a preflight request the client has to perform two request with can be inefficient. This setting will set the CORS 'Access-Control-Max-Age' response header and enables the caching of the preflight response for the specified time. During this time no preflight request will be made.

Parameters:

max - the maximum time, in seconds, that the preflight response may be cached.

Returns:

CorsConfigBuilder to support method chaining.

allowedRequestMethods

public CorsConfigBuilder allowedRequestMethods(HttpMethod... methods)

Specifies the allowed set of HTTP Request Methods that should be returned in the CORS 'Access-Control-Request-Method' response header.

Parameters:

methods - the HttpMethods that should be allowed.

Returns:

CorsConfigBuilder to support method chaining.

allowedRequestHeaders

public CorsConfigBuilder allowedRequestHeaders(String... headers)

Specifies the if headers that should be returned in the CORS 'Access-Control-Allow-Headers' response header. If a client specifies headers on the request, for example by calling:

 xhr.setRequestHeader('My-Custom-Header', "SomeValue");
 

the server will receive the above header name in the 'Access-Control-Request-Headers' of the preflight request. The server will then decide if it allows this header to be sent for the real request (remember that a preflight is not the real request but a request asking the server if it allow a request).

Parameters:

headers - the headers to be added to the preflight 'Access-Control-Allow-Headers' response header.

Returns:

CorsConfigBuilder to support method chaining.

allowedRequestHeaders

public CorsConfigBuilder allowedRequestHeaders(CharSequence... headers)

Specifies the if headers that should be returned in the CORS 'Access-Control-Allow-Headers' response header. If a client specifies headers on the request, for example by calling:

 xhr.setRequestHeader('My-Custom-Header', "SomeValue");
 

the server will receive the above header name in the 'Access-Control-Request-Headers' of the preflight request. The server will then decide if it allows this header to be sent for the real request (remember that a preflight is not the real request but a request asking the server if it allow a request).

Parameters:

headers - the headers to be added to the preflight 'Access-Control-Allow-Headers' response header.

Returns:

CorsConfigBuilder to support method chaining.

preflightResponseHeader

public CorsConfigBuilder preflightResponseHeader(CharSequence name,
                                                 Object... values)

Returns HTTP response headers that should be added to a CORS preflight response. An intermediary like a load balancer might require that a CORS preflight request have certain headers set. This enables such headers to be added.

Parameters:

name - the name of the HTTP header.

values - the values for the HTTP header.

Returns:

CorsConfigBuilder to support method chaining.

preflightResponseHeader

public <T> CorsConfigBuilder preflightResponseHeader(CharSequence name,
                                                     Iterable<T> value)

Returns HTTP response headers that should be added to a CORS preflight response. An intermediary like a load balancer might require that a CORS preflight request have certain headers set. This enables such headers to be added.

Type Parameters:

T - the type of values that the Iterable contains.

Parameters:

name - the name of the HTTP header.

value - the values for the HTTP header.

Returns:

CorsConfigBuilder to support method chaining.

preflightResponseHeader

public <T> CorsConfigBuilder preflightResponseHeader(CharSequence name,
                                                     Callable<T> valueGenerator)

Returns HTTP response headers that should be added to a CORS preflight response. An intermediary like a load balancer might require that a CORS preflight request have certain headers set. This enables such headers to be added. Some values must be dynamically created when the HTTP response is created, for example the 'Date' response header. This can be accomplished by using a Callable which will have its 'call' method invoked when the HTTP response is created.

Type Parameters:

T - the type of the value that the Callable can return.

Parameters:

name - the name of the HTTP header.

valueGenerator - a Callable which will be invoked at HTTP response creation.

Returns:

CorsConfigBuilder to support method chaining.

noPreflightResponseHeaders

public CorsConfigBuilder noPreflightResponseHeaders()

Specifies that no preflight response headers should be added to a preflight response.

Returns:

CorsConfigBuilder to support method chaining.

shortCircuit

public CorsConfigBuilder shortCircuit()

Specifies that a CORS request should be rejected if it's invalid before being further processing. CORS headers are set after a request is processed. This may not always be desired and this setting will check that the Origin is valid and if it is not valid no further processing will take place, and a error will be returned to the calling client.

Returns:

CorsConfigBuilder to support method chaining.

build

public CorsConfig build()

Builds a CorsConfig with settings specified by previous method calls.

Returns:

CorsConfig the configured CorsConfig instance.