Polish

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -21,10 +21,8 @@ import java.util.Arrays;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * Assists with the creation of a {@link CorsConfiguration} instance mapped to
- * a path pattern. By default all origins, headers, and credentials for
- * {@code GET}, {@code HEAD}, and {@code POST} requests are allowed while the
- * max age is set to 30 minutes.
+ * Assists with the creation of a {@link CorsConfiguration} instance for a given
+ * URL path pattern.
  *
  * @author Sebastien Deleuze
  * @author Rossen Stoyanchev
@@ -40,14 +38,6 @@ public class CorsRegistration {
 	private final CorsConfiguration config;
 
 
-	/**
-	 * Create a new {@link CorsRegistration} that allows all origins, headers, and
-	 * credentials for {@code GET}, {@code HEAD}, and {@code POST} requests with
-	 * max age set to 1800 seconds (30 minutes) for the specified path.
-	 * @param pathPattern the path that the CORS configuration should apply to;
-	 * exact path mapping URIs (such as {@code "/admin"}) are supported as well
-	 * as Ant-style path patterns (such as {@code "/admin/**"}).
-	 */
 	public CorsRegistration(String pathPattern) {
 		this.pathPattern = pathPattern;
 		// Same implicit default values as the @CrossOrigin annotation + allows simple methods
@@ -56,8 +46,10 @@ public class CorsRegistration {
 
 
 	/**
-	 * Set the origins to allow, e.g. {@code "http://domain1.com"}.
-	 * <p>The special value {@code "*"} allows all domains.
+	 * The list of allowed origins that be specific origins, e.g.
+	 * {@code "http://domain1.com"}, or {@code "*"} for all origins.
+	 * <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
+	 * response header of preflight actual CORS requests.
 	 * <p>By default, all origins are allowed.
 	 */
 	public CorsRegistration allowedOrigins(String... origins) {
@@ -68,9 +60,9 @@ public class CorsRegistration {
 
 	/**
 	 * Set the HTTP methods to allow, e.g. {@code "GET"}, {@code "POST"}, etc.
-	 * <p>The special value {@code "*"} allows all methods.
-	 * <p>By default "simple" methods {@code GET}, {@code HEAD}, and {@code POST}
-	 * are allowed.
+	 * The special value {@code "*"} allows all methods.
+	 * <p>By default "simple" methods, i.e. {@code GET}, {@code HEAD}, and
+	 * {@code POST} are allowed.
 	 */
 	public CorsRegistration allowedMethods(String... methods) {
 		this.config.setAllowedMethods(Arrays.asList(methods));
@@ -78,9 +70,9 @@ public class CorsRegistration {
 	}
 
 	/**
-	 * Set the list of headers that a pre-flight request can list as allowed
-	 * for use during an actual request.
-	 * <p>The special value {@code "*"} may be used to allow all headers.
+	 * Set the list of headers that a preflight request can list as allowed
+	 * for use during an actual request. The special value {@code "*"} may be
+	 * used to allow all headers.
 	 * <p>A header name is not required to be listed if it is one of:
 	 * {@code Cache-Control}, {@code Content-Language}, {@code Expires},
 	 * {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
@@ -104,6 +96,24 @@ public class CorsRegistration {
 		return this;
 	}
 
+	/**
+	 * Whether the browser should send credentials, such as cookies along with
+	 * cross domain requests, to the annotated endpoint. The configured value is
+	 * set on the {@code Access-Control-Allow-Credentials} response header of
+	 * preflight requests.
+	 * <p><strong>NOTE:</strong> Be aware that this option establishes a high
+	 * level of trust with the configured domains and also increases the surface
+	 * attack of the web application by exposing sensitive user-specific
+	 * information such as cookies and CSRF tokens.
+	 * <p>By default this is not set in which case the
+	 * {@code Access-Control-Allow-Credentials} header is also not set and
+	 * credentials are therefore not allowed.
+	 */
+	public CorsRegistration allowCredentials(boolean allowCredentials) {
+		this.config.setAllowCredentials(allowCredentials);
+		return this;
+	}
+
 	/**
 	 * Configure how long in seconds the response from a pre-flight request
 	 * can be cached by clients.
@@ -114,17 +124,6 @@ public class CorsRegistration {
 		return this;
 	}
 
-	/**
-	 * Whether user credentials are supported. Be aware that enabling this option
-	 * could increase the surface attack of the web application (for example via
-	 * exposing sensitive user-specific information like CSRF tokens).
-	 * <p>By default credentials are not allowed.
-	 */
-	public CorsRegistration allowCredentials(boolean allowCredentials) {
-		this.config.setAllowCredentials(allowCredentials);
-		return this;
-	}
-
 	protected String getPathPattern() {
 		return this.pathPattern;
 	}

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java

@@ -24,10 +24,11 @@ import java.util.Map;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
- * mapped to a path pattern.
+ * Assists with the registration of global, URL pattern based
+ * {@link CorsConfiguration} mappings.
  *
  * @author Sebastien Deleuze
+ * @author Rossen Stoyanchev
  * @since 4.2
  * @see CorsRegistration
  */
@@ -38,14 +39,20 @@ public class CorsRegistry {
 
 	/**
 	 * Enable cross-origin request handling for the specified path pattern.
+	 *
 	 * <p>Exact path mapping URIs (such as {@code "/admin"}) are supported as
 	 * well as Ant-style path patterns (such as {@code "/admin/**"}).
 	 * <p>By default, all origins, all headers, credentials and {@code GET},
 	 * {@code HEAD}, and {@code POST} methods are allowed, and the max age
 	 * is set to 30 minutes.
-	 * @param pathPattern the path pattern to enable CORS handling for
-	 * @return CorsRegistration the corresponding registration object,
-	 * allowing for further fine-tuning
+	 *
+	 * <p>The following defaults are applied to the {@link CorsRegistration}:
+	 * <ul>
+	 *     <li>Allow all origins.</li>
+	 *     <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
+	 *     <li>Allow all headers.</li>
+	 *     <li>Set max age to 1800 seconds (30 minutes).</li>
+	 * </ul>
 	 */
 	public CorsRegistration addMapping(String pathPattern) {
 		CorsRegistration registration = new CorsRegistration(pathPattern);