Correct Javadoc in ServletUriComponentsBuilder

Replace all method level comments related to forwaded headers, some
current and some outdated, with a single class-level comment.

Issue: SPR-17317

spring-webmvc/src/main/java/org/springframework/web/servlet/support/ServletUriComponentsBuilder.java

@@ -32,13 +32,12 @@ import org.springframework.web.util.UrlPathHelper;
  * UriComponentsBuilder with additional static factory methods to create links
  * based on the current HttpServletRequest.
  *
- * <p><strong>Note:</strong> This class uses values from "Forwarded"
+ * <p><strong>Note:</strong> As of 5.1, methods in this class do not extract
- * (<a href="http://tools.ietf.org/html/rfc7239">RFC 7239</a>),
+ * {@code "Forwarded"} and {@code "X-Forwarded-*"} headers that specify the
- * "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers,
+ * client-originated address. Please, use
- * if present, in order to reflect the client-originated protocol and address.
+ * {@link org.springframework.web.filter.ForwardedHeaderFilter
- * Consider using the {@code ForwardedHeaderFilter} in order to choose from a
+ * ForwardedHeaderFilter}, or similar from the underlying server, to extract
- * central place whether to extract and use, or to discard such headers.
+ * and use such headers, or to discard them.
- * See the Spring Framework reference for more on this filter.
  *
  * @author Rossen Stoyanchev
  * @since 3.1
@@ -76,10 +75,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Prepare a builder from the host, port, scheme, and context path of the
 	 * given HttpServletRequest.
-	 * <p><strong>Note:</strong> As of 5.1, this method ignores
-	 * {@code "Forwarded"} and {@code "X-Forwarded-*"} headers that specify the
-	 * client-originated address. Consider using the {@code ForwardedHeaderFilter}
-	 * to extract and use, or to discard such headers.
 	 */
 	public static ServletUriComponentsBuilder fromContextPath(HttpServletRequest request) {
 		ServletUriComponentsBuilder builder = initFromRequest(request);
@@ -94,10 +89,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	 * will end with "/main". If the servlet is mapped otherwise, e.g.
 	 * {@code "/"} or {@code "*.do"}, the result will be the same as
 	 * if calling {@link #fromContextPath(HttpServletRequest)}.
-	 * <p><strong>Note:</strong> As of 5.1, this method ignores
-	 * {@code "Forwarded"} and {@code "X-Forwarded-*"} headers that specify the
-	 * client-originated address. Consider using the {@code ForwardedHeaderFilter}
-	 * to extract and use, or to discard such headers.
 	 */
 	public static ServletUriComponentsBuilder fromServletMapping(HttpServletRequest request) {
 		ServletUriComponentsBuilder builder = fromContextPath(request);
@@ -110,10 +101,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Prepare a builder from the host, port, scheme, and path (but not the query)
 	 * of the HttpServletRequest.
-	 * <p><strong>Note:</strong> As of 5.1, this method ignores
-	 * {@code "Forwarded"} and {@code "X-Forwarded-*"} headers that specify the
-	 * client-originated address. Consider using the {@code ForwardedHeaderFilter}
-	 * to extract and use, or to discard such headers.
 	 */
 	public static ServletUriComponentsBuilder fromRequestUri(HttpServletRequest request) {
 		ServletUriComponentsBuilder builder = initFromRequest(request);
@@ -124,10 +111,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Prepare a builder by copying the scheme, host, port, path, and
 	 * query string of an HttpServletRequest.
-	 * <p><strong>Note:</strong> As of 5.1, this method ignores
-	 * {@code "Forwarded"} and {@code "X-Forwarded-*"} headers that specify the
-	 * client-originated address. Consider using the {@code ForwardedHeaderFilter}
-	 * to extract and use, or to discard such headers.
 	 */
 	public static ServletUriComponentsBuilder fromRequest(HttpServletRequest request) {
 		ServletUriComponentsBuilder builder = initFromRequest(request);
@@ -159,11 +142,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Same as {@link #fromContextPath(HttpServletRequest)} except the
 	 * request is obtained through {@link RequestContextHolder}.
-	 * <p><strong>Note:</strong> This method extracts values from "Forwarded"
-	 * and "X-Forwarded-*" headers if found. See class-level docs.
-	 * <p>As of 4.3.15, this method replaces the contextPath with the value
-	 * of "X-Forwarded-Prefix" rather than prepending, thus aligning with
-	 * {@code ForwardedHeaderFilter}.
 	 */
 	public static ServletUriComponentsBuilder fromCurrentContextPath() {
 		return fromContextPath(getCurrentRequest());
@@ -172,11 +150,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Same as {@link #fromServletMapping(HttpServletRequest)} except the
 	 * request is obtained through {@link RequestContextHolder}.
-	 * <p><strong>Note:</strong> This method extracts values from "Forwarded"
-	 * and "X-Forwarded-*" headers if found. See class-level docs.
-	 * <p>As of 4.3.15, this method replaces the contextPath with the value
-	 * of "X-Forwarded-Prefix" rather than prepending, thus aligning with
-	 * {@code ForwardedHeaderFilter}.
 	 */
 	public static ServletUriComponentsBuilder fromCurrentServletMapping() {
 		return fromServletMapping(getCurrentRequest());
@@ -185,11 +158,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Same as {@link #fromRequestUri(HttpServletRequest)} except the
 	 * request is obtained through {@link RequestContextHolder}.
-	 * <p><strong>Note:</strong> This method extracts values from "Forwarded"
-	 * and "X-Forwarded-*" headers if found. See class-level docs.
-	 * <p>As of 4.3.15, this method replaces the contextPath with the value
-	 * of "X-Forwarded-Prefix" rather than prepending, thus aligning with
-	 * {@code ForwardedHeaderFilter}.
 	 */
 	public static ServletUriComponentsBuilder fromCurrentRequestUri() {
 		return fromRequestUri(getCurrentRequest());
@@ -198,11 +166,6 @@ public class ServletUriComponentsBuilder extends UriComponentsBuilder {
 	/**
 	 * Same as {@link #fromRequest(HttpServletRequest)} except the
 	 * request is obtained through {@link RequestContextHolder}.
-	 * <p><strong>Note:</strong> This method extracts values from "Forwarded"
-	 * and "X-Forwarded-*" headers if found. See class-level docs.
-	 * <p>As of 4.3.15, this method replaces the contextPath with the value
-	 * of "X-Forwarded-Prefix" rather than prepending, thus aligning with
-	 * {@code ForwardedHeaderFilter}.
 	 */
 	public static ServletUriComponentsBuilder fromCurrentRequest() {
 		return fromRequest(getCurrentRequest());