From 23a66e016eac178e0b922ebbe0fba50165f37ab3 Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Sun, 24 May 2020 20:40:43 +0100 Subject: [PATCH] UriBuilder javadoc update Closes gh-25055 --- .../web/util/DefaultUriBuilderFactory.java | 24 +++++--- .../springframework/web/util/UriBuilder.java | 61 ++++++++++++++++--- 2 files changed, 68 insertions(+), 17 deletions(-) diff --git a/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java b/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java index d7654582436..1df9e750991 100644 --- a/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java +++ b/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2019 the original author or authors. + * Copyright 2002-2020 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. @@ -41,7 +41,14 @@ import org.springframework.util.StringUtils; public class DefaultUriBuilderFactory implements UriBuilderFactory { /** - * Enum to represent multiple URI encoding strategies. + * Enum to represent multiple URI encoding strategies. The following are + * available: + * * @see #setEncodingMode */ public enum EncodingMode { @@ -130,16 +137,13 @@ public class DefaultUriBuilderFactory implements UriBuilderFactory { /** - * Set the encoding mode to use. + * Set the {@link EncodingMode encoding mode} to use. *

By default this is set to {@link EncodingMode#TEMPLATE_AND_VALUES * EncodingMode.TEMPLATE_AND_VALUES}. - *

Note: In 5.1 the default was changed from - * {@link EncodingMode#URI_COMPONENT EncodingMode.URI_COMPONENT}. - * Consequently the {@code WebClient}, which relies on the built-in default - * has also been switched to the new default. The {@code RestTemplate} - * however sets this explicitly to {@link EncodingMode#URI_COMPONENT - * EncodingMode.URI_COMPONENT} explicitly for historic and backwards - * compatibility reasons. + *

Note: Prior to 5.1 the default was + * {@link EncodingMode#URI_COMPONENT EncodingMode.URI_COMPONENT} + * therefore the {@code WebClient} {@code RestTemplate} have switched their + * default behavior. * @param encodingMode the encoding mode to use */ public void setEncodingMode(EncodingMode encodingMode) { diff --git a/spring-web/src/main/java/org/springframework/web/util/UriBuilder.java b/spring-web/src/main/java/org/springframework/web/util/UriBuilder.java index 14618e75208..fbd04de36a1 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriBuilder.java +++ b/spring-web/src/main/java/org/springframework/web/util/UriBuilder.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2019 the original author or authors. + * Copyright 2002-2020 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. @@ -77,22 +77,69 @@ public interface UriBuilder { UriBuilder port(@Nullable String port); /** - * Append the given path to the existing path of this builder. - * The given path may contain URI template variables. + * Append to the path of this builder. + *

The given value is appended as-is without any checks for slashes other + * than to clean up duplicates. For example: + * 

+	 *
+	 * builder.path("/first-").path("value/").path("/{id}").build("123")
+	 *
+	 * // Results is "/first-value/123"
+	 *
+ *

By contrast {@link #pathSegment(String...)} builds the path from + * individual path segments and in that case slashes are inserted transparently. + * In some cases you may use a combination of both {@code pathSegment} and + * {@code path}. For example: + * 

+	 *
+	 * builder.pathSegment("first-value", "second-value").path("/")
+	 *
+	 * // Results is "/first-value/second-value/"
+	 *
+	 *
+ *

If a URI variable value contains slashes, whether those are encoded or + * not depends on the configured encoding mode. See + * {@link UriComponentsBuilder#encode()}, or if using + * {@code UriComponentsBuilder} via {@link DefaultUriBuilderFactory} + * (e.g. {@code WebClient} or {@code RestTemplate}) see its + * {@link DefaultUriBuilderFactory#setEncodingMode encodingMode} property. + * Also see the + * URI Encoding section of the reference docs. * @param path the URI path */ UriBuilder path(String path); /** - * Set the path of this builder overriding the existing path values. + * Override the existing path. * @param path the URI path, or {@code null} for an empty path */ UriBuilder replacePath(@Nullable String path); /** - * Append path segments to the existing path. Each path segment may contain - * URI template variables and should not contain any slashes. - * Use {@code path("/")} subsequently to ensure a trailing slash. + * Append to the path using path segments. For example: + * 

+	 *
+	 * builder.pathSegment("first-value", "second-value", "{id}").build("123")
+	 *
+	 * // Results is "/first-value/second-value/123"
+	 *
+	 *
+ *

If slashes are present in a path segment, they are encoded: + * 

+	 *
+	 * builder.pathSegment("ba/z", "{id}").build("a/b")
+	 *
+	 * // Results is "/ba%2Fz/a%2Fb"
+	 *
+	 *
+ * To insert a trailing slash, use the {@link #path} builder method: + * 
+	 *
+	 * builder.pathSegment("first-value", "second-value").path("/")
+	 *
+	 * // Results is "/first-value/second-value/"
+	 *
+	 *
* @param pathSegments the URI path segments */ UriBuilder pathSegment(String... pathSegments) throws IllegalArgumentException;