Update CORS Javadoc in spring-websocket

Closes gh-26753

spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 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.
@@ -46,10 +46,14 @@ public class CorsRegistration {
 
 
 	/**
-	 * A list of origins for which cross-origin requests are allowed. Please,
-	 * see {@link CorsConfiguration#setAllowedOrigins(List)} for details.
-	 * <p>By default all origins are allowed unless {@code originPatterns} is
-	 * also set in which case {@code originPatterns} is used instead.
+	 * Set the origins for which cross-origin requests are allowed from a browser.
+	 * Please, refer to {@link CorsConfiguration#setAllowedOrigins(List)} for
+	 * format details and other considerations.
+	 *
+	 * <p>By default, all origins are allowed, but if
+	 * {@link #allowedOriginPatterns(String...) allowedOriginPatterns} is also
+	 * set, then that takes precedence.
+	 * @see #allowedOriginPatterns(String...)
 	 */
 	public CorsRegistration allowedOrigins(String... origins) {
 		this.config.setAllowedOrigins(Arrays.asList(origins));
@@ -57,9 +61,11 @@ public class CorsRegistration {
 	}
 
 	/**
-	 * Alternative to {@link #allowCredentials} that supports origins declared
-	 * via wildcard patterns. Please, see
-	 * @link CorsConfiguration#setAllowedOriginPatterns(List)} for details.
+	 * Alternative to {@link #allowedOrigins(String...)} that supports more
+	 * flexible patterns for specifying the origins for which cross-origin
+	 * requests are allowed from a browser. Please, refer to
+	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for format
+	 * details and other considerations.
 	 * <p>By default this is not set.
 	 * @since 5.3
 	 */

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

@@ -47,10 +47,14 @@ public class CorsRegistration {
 
 
 	/**
-	 * A list of origins for which cross-origin requests are allowed. Please,
-	 * see {@link CorsConfiguration#setAllowedOrigins(List)} for details.
-	 * <p>By default all origins are allowed unless {@code originPatterns} is
-	 * also set in which case {@code originPatterns} is used instead.
+	 * Set the origins for which cross-origin requests are allowed from a browser.
+	 * Please, refer to {@link CorsConfiguration#setAllowedOrigins(List)} for
+	 * format details and other considerations.
+	 *
+	 * <p>By default, all origins are allowed, but if
+	 * {@link #allowedOriginPatterns(String...) allowedOriginPatterns} is also
+	 * set, then that takes precedence.
+	 * @see #allowedOriginPatterns(String...)
 	 */
 	public CorsRegistration allowedOrigins(String... origins) {
 		this.config.setAllowedOrigins(Arrays.asList(origins));
@@ -58,9 +62,11 @@ public class CorsRegistration {
 	}
 
 	/**
-	 * Alternative to {@link #allowCredentials} that supports origins declared
-	 * via wildcard patterns. Please, see
-	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for details.
+	 * Alternative to {@link #allowedOrigins(String...)} that supports more
+	 * flexible patterns for specifying the origins for which cross-origin
+	 * requests are allowed from a browser. Please, refer to
+	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for format
+	 * details and other considerations.
 	 * <p>By default this is not set.
 	 * @since 5.3
 	 */

spring-websocket/src/main/java/org/springframework/web/socket/config/annotation/StompWebSocketEndpointRegistration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 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.
@@ -16,6 +16,9 @@
 
 package org.springframework.web.socket.config.annotation;
 
+import java.util.List;
+
+import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.socket.server.HandshakeHandler;
 import org.springframework.web.socket.server.HandshakeInterceptor;
 
@@ -43,29 +46,36 @@ public interface StompWebSocketEndpointRegistration {
 	StompWebSocketEndpointRegistration addInterceptors(HandshakeInterceptor... interceptors);
 
 	/**
-	 * Configure allowed {@code Origin} header values. This check is mostly designed for
-	 * browser clients. There is nothing preventing other types of client to modify the
-	 * {@code Origin} header value.
+	 * Set the origins for which cross-origin requests are allowed from a browser.
+	 * Please, refer to {@link CorsConfiguration#setAllowedOrigins(List)} for
+	 * format details and considerations, and keep in mind that the CORS spec
+	 * does not allow use of {@code "*"} with {@code allowCredentials=true}.
+	 * For more flexible origin patterns use {@link #setAllowedOriginPatterns}
+	 * instead.
 	 *
-	 * <p>When SockJS is enabled and origins are restricted, transport types that do not
-	 * allow to check request origin (Iframe based transports) are disabled.
-	 * As a consequence, IE 6 to 9 are not supported when origins are restricted.
+	 * <p>By default, no origins are allowed. When
+	 * {@link #setAllowedOriginPatterns(String...) allowedOriginPatterns} is also
+	 * set, then that takes precedence over this property.
 	 *
-	 * <p>Each provided allowed origin must start by "http://", "https://" or be "*"
-	 * (means that all origins are allowed). By default, only same origin requests are
-	 * allowed (empty list).
+	 * <p>Note when SockJS is enabled and origins are restricted, transport types
+	 * that do not allow to check request origin (Iframe based transports) are
+	 * disabled. As a consequence, IE 6 to 9 are not supported when origins are
+	 * restricted.
 	 *
 	 * @since 4.1.2
+	 * @see #setAllowedOriginPatterns(String...)
 	 * @see <a href="https://tools.ietf.org/html/rfc6454">RFC 6454: The Web Origin Concept</a>
 	 * @see <a href="https://github.com/sockjs/sockjs-client#supported-transports-by-browser-html-served-from-http-or-https">SockJS supported transports by browser</a>
 	 */
 	StompWebSocketEndpointRegistration setAllowedOrigins(String... origins);
 
 	/**
-	 * A variant of {@link #setAllowedOrigins(String...)} that accepts flexible
-	 * domain patterns, e.g. {@code "https://*.domain1.com"}. Furthermore it
-	 * always sets the {@code Access-Control-Allow-Origin} response header to
-	 * the matched origin and never to {@code "*"}, nor to any other pattern.
+	 * Alternative to {@link #setAllowedOrigins(String...)} that supports more
+	 * flexible patterns for specifying the origins for which cross-origin
+	 * requests are allowed from a browser. Please, refer to
+	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for format
+	 * details and other considerations.
+	 * <p>By default this is not set.
 	 * @since 5.3.2
 	 */
 	StompWebSocketEndpointRegistration setAllowedOriginPatterns(String... originPatterns);

spring-websocket/src/main/java/org/springframework/web/socket/config/annotation/WebSocketHandlerRegistration.java

@@ -16,6 +16,9 @@
 
 package org.springframework.web.socket.config.annotation;
 
+import java.util.List;
+
+import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.socket.WebSocketHandler;
 import org.springframework.web.socket.server.HandshakeHandler;
 import org.springframework.web.socket.server.HandshakeInterceptor;
@@ -45,29 +48,36 @@ public interface WebSocketHandlerRegistration {
 	WebSocketHandlerRegistration addInterceptors(HandshakeInterceptor... interceptors);
 
 	/**
-	 * Configure allowed {@code Origin} header values. This check is mostly designed for
-	 * browser clients. There is nothing preventing other types of client to modify the
-	 * {@code Origin} header value.
+	 * Set the origins for which cross-origin requests are allowed from a browser.
+	 * Please, refer to {@link CorsConfiguration#setAllowedOrigins(List)} for
+	 * format details and considerations, and keep in mind that the CORS spec
+	 * does not allow use of {@code "*"} with {@code allowCredentials=true}.
+	 * For more flexible origin patterns use {@link #setAllowedOriginPatterns}
+	 * instead.
 	 *
-	 * <p>When SockJS is enabled and origins are restricted, transport types that do not
-	 * allow to check request origin (Iframe based transports) are disabled.
-	 * As a consequence, IE 6 to 9 are not supported when origins are restricted.
+	 * <p>By default, no origins are allowed. When
+	 * {@link #setAllowedOriginPatterns(String...) allowedOriginPatterns} is also
+	 * set, then that takes precedence over this property.
 	 *
-	 * <p>Each provided allowed origin must start by "http://", "https://" or be "*"
-	 * (means that all origins are allowed). By default, only same origin requests are
-	 * allowed (empty list).
+	 * <p>Note when SockJS is enabled and origins are restricted, transport types
+	 * that do not allow to check request origin (Iframe based transports) are
+	 * disabled. As a consequence, IE 6 to 9 are not supported when origins are
+	 * restricted.
 	 *
 	 * @since 4.1.2
+	 * @see #setAllowedOriginPatterns(String...)
 	 * @see <a href="https://tools.ietf.org/html/rfc6454">RFC 6454: The Web Origin Concept</a>
 	 * @see <a href="https://github.com/sockjs/sockjs-client#supported-transports-by-browser-html-served-from-http-or-https">SockJS supported transports by browser</a>
 	 */
 	WebSocketHandlerRegistration setAllowedOrigins(String... origins);
 
 	/**
-	 * A variant of {@link #setAllowedOrigins(String...)} that accepts flexible
-	 * domain patterns, e.g. {@code "https://*.domain1.com"}. Furthermore it
-	 * always sets the {@code Access-Control-Allow-Origin} response header to
-	 * the matched origin and never to {@code "*"}, nor to any other pattern.
+	 * Alternative to {@link #setAllowedOrigins(String...)} that supports more
+	 * flexible patterns for specifying the origins for which cross-origin
+	 * requests are allowed from a browser. Please, refer to
+	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for format
+	 * details and other considerations.
+	 * <p>By default this is not set.
 	 * @since 5.3.5
 	 */
 	WebSocketHandlerRegistration setAllowedOriginPatterns(String... originPatterns);

spring-websocket/src/main/java/org/springframework/web/socket/server/support/OriginHandshakeInterceptor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 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.
@@ -67,12 +67,23 @@ public class OriginHandshakeInterceptor implements HandshakeInterceptor {
 
 
 	/**
-	 * Configure allowed {@code Origin} header values. This check is mostly
-	 * designed for browsers. There is nothing preventing other types of client
-	 * to modify the {@code Origin} header value.
-	 * <p>Each provided allowed origin must have a scheme, and optionally a port
-	 * (e.g. "https://example.org", "https://example.org:9090"). An allowed origin
-	 * string may also be "*" in which case all origins are allowed.
+	 * Set the origins for which cross-origin requests are allowed from a browser.
+	 * Please, refer to {@link CorsConfiguration#setAllowedOrigins(List)} for
+	 * format details and considerations, and keep in mind that the CORS spec
+	 * does not allow use of {@code "*"} with {@code allowCredentials=true}.
+	 * For more flexible origin patterns use {@link #setAllowedOriginPatterns}
+	 * instead.
+	 *
+	 * <p>By default, no origins are allowed. When
+	 * {@link #setAllowedOriginPatterns(Collection) allowedOriginPatterns} is also
+	 * set, then that takes precedence over this property.
+	 *
+	 * <p>Note when SockJS is enabled and origins are restricted, transport types
+	 * that do not allow to check request origin (Iframe based transports) are
+	 * disabled. As a consequence, IE 6 to 9 are not supported when origins are
+	 * restricted.
+	 *
+	 * @see #setAllowedOriginPatterns(Collection)
 	 * @see <a href="https://tools.ietf.org/html/rfc6454">RFC 6454: The Web Origin Concept</a>
 	 */
 	public void setAllowedOrigins(Collection<String> allowedOrigins) {
@@ -81,7 +92,7 @@ public class OriginHandshakeInterceptor implements HandshakeInterceptor {
 	}
 
 	/**
-	 * Return the allowed {@code Origin} header values.
+	 * Return the {@link #setAllowedOriginPatterns(Collection) configured} allowed origins.
 	 * @since 4.1.5
 	 */
 	public Collection<String> getAllowedOrigins() {
@@ -91,12 +102,13 @@ public class OriginHandshakeInterceptor implements HandshakeInterceptor {
 	}
 
 	/**
-	 * A variant of {@link #setAllowedOrigins(Collection)} that accepts flexible
-	 * domain patterns, e.g. {@code "https://*.domain1.com"}. Furthermore it
-	 * always sets the {@code Access-Control-Allow-Origin} response header to
-	 * the matched origin and never to {@code "*"}, nor to any other pattern.
+	 * Alternative to {@link #setAllowedOrigins(Collection)} that supports more
+	 * flexible patterns for specifying the origins for which cross-origin
+	 * requests are allowed from a browser. Please, refer to
+	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for format
+	 * details and other considerations.
+	 * <p>By default this is not set.
 	 * @since 5.3.2
-	 * @see CorsConfiguration#setAllowedOriginPatterns(List)
 	 */
 	public void setAllowedOriginPatterns(Collection<String> allowedOriginPatterns) {
 		Assert.notNull(allowedOriginPatterns, "Allowed origin patterns Collection must not be null");
@@ -104,9 +116,8 @@ public class OriginHandshakeInterceptor implements HandshakeInterceptor {
 	}
 
 	/**
-	 * Return the allowed {@code Origin} pattern header values.
+	 * Return the {@link #setAllowedOriginPatterns(Collection) configured} allowed origin patterns.
 	 * @since 5.3.2
-	 * @see CorsConfiguration#getAllowedOriginPatterns()
 	 */
 	public Collection<String> getAllowedOriginPatterns() {
 		List<String> allowedOriginPatterns = this.corsConfiguration.getAllowedOriginPatterns();

spring-websocket/src/main/java/org/springframework/web/socket/sockjs/support/AbstractSockJsService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2021 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.
@@ -310,17 +310,24 @@ public abstract class AbstractSockJsService implements SockJsService, CorsConfig
 	}
 
 	/**
-	 * Configure allowed {@code Origin} header values. This check is mostly
-	 * designed for browsers. There is nothing preventing other types of client
-	 * to modify the {@code Origin} header value.
-	 * <p>When SockJS is enabled and origins are restricted, transport types
-	 * that do not allow to check request origin (Iframe based transports)
-	 * are disabled. As a consequence, IE 6 to 9 are not supported when origins
-	 * are restricted.
-	 * <p>Each provided allowed origin must have a scheme, and optionally a port
-	 * (e.g. "https://example.org", "https://example.org:9090"). An allowed origin
-	 * string may also be "*" in which case all origins are allowed.
+	 * Set the origins for which cross-origin requests are allowed from a browser.
+	 * Please, refer to {@link CorsConfiguration#setAllowedOrigins(List)} for
+	 * format details and considerations, and keep in mind that the CORS spec
+	 * does not allow use of {@code "*"} with {@code allowCredentials=true}.
+	 * For more flexible origin patterns use {@link #setAllowedOriginPatterns}
+	 * instead.
+	 *
+	 * <p>By default, no origins are allowed. When
+	 * {@link #setAllowedOriginPatterns(Collection) allowedOriginPatterns} is also
+	 * set, then that takes precedence over this property.
+	 *
+	 * <p>Note when SockJS is enabled and origins are restricted, transport types
+	 * that do not allow to check request origin (Iframe based transports) are
+	 * disabled. As a consequence, IE 6 to 9 are not supported when origins are
+	 * restricted.
+	 *
 	 * @since 4.1.2
+	 * @see #setAllowedOriginPatterns(Collection)
 	 * @see <a href="https://tools.ietf.org/html/rfc6454">RFC 6454: The Web Origin Concept</a>
 	 * @see <a href="https://github.com/sockjs/sockjs-client#supported-transports-by-browser-html-served-from-http-or-https">SockJS supported transports by browser</a>
 	 */
@@ -330,19 +337,19 @@ public abstract class AbstractSockJsService implements SockJsService, CorsConfig
 	}
 
 	/**
-	 * Return configure allowed {@code Origin} header values.
+	 * Return the {@link #setAllowedOrigins(Collection) configured} allowed origins.
 	 * @since 4.1.2
-	 * @see #setAllowedOrigins
 	 */
 	@SuppressWarnings("ConstantConditions")
 	public Collection<String> getAllowedOrigins() {
 		return this.corsConfiguration.getAllowedOrigins();
 	}
 	/**
-	 * A variant of {@link #setAllowedOrigins(Collection)} that accepts flexible
-	 * domain patterns, e.g. {@code "https://*.domain1.com"}. Furthermore it
-	 * always sets the {@code Access-Control-Allow-Origin} response header to
-	 * the matched origin and never to {@code "*"}, nor to any other pattern.
+	 * Alternative to {@link #setAllowedOrigins(Collection)} that supports more
+	 * flexible patterns for specifying the origins for which cross-origin
+	 * requests are allowed from a browser. Please, refer to
+	 * {@link CorsConfiguration#setAllowedOriginPatterns(List)} for format
+	 * details and other considerations.
 	 * <p>By default this is not set.
 	 * @since 5.2.3
 	 */
@@ -354,7 +361,6 @@ public abstract class AbstractSockJsService implements SockJsService, CorsConfig
 	/**
 	 * Return {@link #setAllowedOriginPatterns(Collection) configured} origin patterns.
 	 * @since 5.3.2
-	 * @see #setAllowedOriginPatterns
 	 */
 	@SuppressWarnings("ConstantConditions")
 	public Collection<String> getAllowedOriginPatterns() {