Polish

spring-webflux/src/main/java/org/springframework/web/reactive/config/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.
@@ -22,10 +22,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
@@ -39,15 +37,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;
 		this.config = new CorsConfiguration().applyPermitDefaultValues();
@@ -55,8 +44,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) {
@@ -102,6 +93,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.
@@ -112,17 +121,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-webflux/src/main/java/org/springframework/web/reactive/config/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 5.0
  */
 public class CorsRegistry {
@@ -41,9 +42,13 @@ public class CorsRegistry {
 	 * <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.
+	 * <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);