Package com.linecorp.armeria.server.cors

Class CorsPolicyBuilder

java.lang.Object
com.linecorp.armeria.server.cors.CorsPolicyBuilder
public final class CorsPolicyBuilder extends Object
Builds a new CorsPolicy.

Example


 CorsPolicyBuilder cb = CorsPolicy.builder("http://example.com");
 cb.allowRequestMethods(HttpMethod.POST, HttpMethod.GET)
   .allowRequestHeaders("allow_request_header")
   .exposeHeaders("expose_header_1", "expose_header_2")
   .preflightResponseHeader("x-preflight-cors", "Hello CORS");
 CorsPolicy policy = cb.build();

  • Method Details

    • build

      public CorsPolicy build()
      Returns a newly-created CorsPolicy based on the properties of this builder.

    • route

      public CorsPolicyBuilder route(String pathPattern)
      Adds a path pattern that this policy is supposed to be applied to.
      Parameters:
      pathPattern - the path pattern that this policy is supposed to be applied to
      Returns:
      this to support method chaining.

    • allowNullOrigin

      public CorsPolicyBuilder allowNullOrigin()
      Enables a successful CORS response with a "null" value for the CORS response header "Access-Control-Allow-Origin". Web browsers may set the "Origin" request header to "null" if a resource is loaded from the local file system.
      Returns:
      this to support method chaining.

    • allowCredentials

      public CorsPolicyBuilder allowCredentials()
      Enables cookies to be added to CORS requests. Calling this method will set the CORS "Access-Control-Allow-Credentials" response header to true. By default, cookies are not included in CORS requests.

      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 include cookies in cross origin requests.

      Returns:
      this to support method chaining.

    • maxAge

      public CorsPolicyBuilder maxAge(long maxAge)
      Sets 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:
      maxAge - the maximum time, in seconds, that the preflight response may be cached.
      Returns:
      this to support method chaining.

    • exposeHeaders

      public CorsPolicyBuilder 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("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:
      this to support method chaining.

    • exposeHeaders

      public CorsPolicyBuilder exposeHeaders(Iterable<? extends 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("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:
      this to support method chaining.

    • allowRequestMethods

      public CorsPolicyBuilder allowRequestMethods(HttpMethod... methods)
      Specifies the allowed set of HTTP request methods that should be returned in the CORS "Access-Control-Allow-Methods" response header.
      Parameters:
      methods - the HttpMethods that should be allowed.
      Returns:
      this to support method chaining.

    • allowRequestMethods

      public CorsPolicyBuilder allowRequestMethods(Iterable<HttpMethod> methods)
      Specifies the allowed set of HTTP request methods that should be returned in the CORS "Access-Control-Allow-Methods" response header.
      Parameters:
      methods - the HttpMethods that should be allowed.
      Returns:
      this to support method chaining.

    • allowAllRequestHeaders

      public CorsPolicyBuilder allowAllRequestHeaders(boolean allowAllRequestHeaders)
      Sets whether to allow all HTTP headers in the CORS "Access-Control-Request-Headers" request header.

      The server will set the CORS "Access-Control-Allow-Headers" to be as same as the CORS "Access-Control-Request-Headers" header in the request if this property is true. The default value of this property is false.

      Returns:
      this to support method chaining.

    • allowRequestHeaders

      public CorsPolicyBuilder allowRequestHeaders(CharSequence... headers)
      Specifies the 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 allows a request).
      Parameters:
      headers - the headers to be added to the preflight "Access-Control-Allow-Headers" response header.
      Returns:
      this to support method chaining.

    • allowRequestHeaders

      public CorsPolicyBuilder allowRequestHeaders(Iterable<? extends CharSequence> headers)
      Specifies the 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 allows a request).
      Parameters:
      headers - the headers to be added to the preflight "Access-Control-Allow-Headers" response header.
      Returns:
      this to support method chaining.

    • preflightResponseHeader

      public CorsPolicyBuilder preflightResponseHeader(CharSequence name, Object... values)
      Specifies 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:
      this to support method chaining.

    • preflightResponseHeader

      public CorsPolicyBuilder preflightResponseHeader(CharSequence name, Iterable<?> values)
      Specifies 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:
      this to support method chaining.

    • preflightResponseHeader

      public CorsPolicyBuilder preflightResponseHeader(CharSequence name, Supplier<?> valueSupplier)
      Specifies 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 Supplier which will have its Supplier.get() method invoked when the HTTP response is created.

      Parameters:
      name - the name of the HTTP header.
      valueSupplier - a Supplier which will be invoked at HTTP response creation.
      Returns:
      this to support method chaining.

    • disablePreflightResponseHeaders

      public CorsPolicyBuilder disablePreflightResponseHeaders()
      Specifies that no preflight response headers should be added to a preflight response.
      Returns:
      this to support method chaining.

    • toString

      public String toString()
      Overrides:
      toString in class Object