Further UriComponentsBuilder javadoc revision

Author: jhoeller

spring-web/src/main/java/org/springframework/web/util/UriComponents.java

@@ -30,10 +30,10 @@
 import org.springframework.util.MultiValueMap;
 
 /**
- * Represents an immutable collection of URI components, mapping component type to String
- * values. Contains convenience getters for all components. Effectively similar to {@link
- * java.net.URI}, but with more powerful encoding options and support for URI template
- * variables.
+ * Represents an immutable collection of URI components, mapping component type to
+ * String values. Contains convenience getters for all components. Effectively similar
+ * to {@link java.net.URI}, but with more powerful encoding options and support for
+ * URI template variables.
  *
  * @author Arjen Poutsma
  * @since 3.1
@@ -135,43 +135,43 @@ public final UriComponents encode() {
 	 * Encode all URI components using their specific encoding rules, and
 	 * returns the result as a new {@code UriComponents} instance.
 	 * @param encoding the encoding of the values contained in this map
-	 * @return the encoded uri components
+	 * @return the encoded URI components
 	 * @throws UnsupportedEncodingException if the given encoding is not supported
 	 */
 	public abstract UriComponents encode(String encoding) throws UnsupportedEncodingException;
 
 	/**
-	 * Replace all URI template variables with the values from a given map. The map keys
-	 * represent variable names; the values variable values. The order of variables is not
-	 * significant.
+	 * Replace all URI template variables with the values from a given map.
+	 * <p>The given map keys represent variable names; the corresponding values
+	 * represent variable values. The order of variables is not significant.
 	 * @param uriVariables the map of URI variables
-	 * @return the expanded uri components
+	 * @return the expanded URI components
 	 */
 	public final UriComponents expand(Map<String, ?> uriVariables) {
 		Assert.notNull(uriVariables, "'uriVariables' must not be null");
 		return expandInternal(new MapTemplateVariables(uriVariables));
 	}
 
 	/**
-	 * Replace all URI template variables with the values from a given array. The array
-	 * represent variable values. The order of variables is significant.
-	 * @param uriVariableValues URI variable values
-	 * @return the expanded uri components
+	 * Replace all URI template variables with the values from a given array.
+	 * <p>The given array represents variable values. The order of variables is significant.
+	 * @param uriVariableValues the URI variable values
+	 * @return the expanded URI components
 	 */
 	public final UriComponents expand(Object... uriVariableValues) {
 		Assert.notNull(uriVariableValues, "'uriVariableValues' must not be null");
 		return expandInternal(new VarArgsTemplateVariables(uriVariableValues));
 	}
 
 	/**
-	 * Replace all URI template variables with the values obtained through the
-	 * given {@link UriTemplateVariables} instance.
-	 * @param uriTemplateVars resolves URI template variable values
-	 * @return the expanded uri components
+	 * Replace all URI template variables with the values from the given
+	 * {@link UriTemplateVariables}.
+	 * @param uriVariables the URI template values
+	 * @return the expanded URI components
 	 */
-	public final UriComponents expand(UriTemplateVariables uriTemplateVars) {
-		Assert.notNull(uriTemplateVars, "'uriTemplateVars' must not be null");
-		return expandInternal(uriTemplateVars);
+	public final UriComponents expand(UriTemplateVariables uriVariables) {
+		Assert.notNull(uriVariables, "'uriVariables' must not be null");
+		return expandInternal(uriVariables);
 	}
 
 	/**

spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java

@@ -34,15 +34,15 @@
 /**
  * Builder for {@link UriComponents}.
  *
- * <p></p>Typical usage involves:
+ * <p>Typical usage involves:
  * <ol>
- *     <li>Create a {@code UriComponentsBuilder} with one of the static factory methods (such as
- *     {@link #fromPath(String)} or {@link #fromUri(URI)})</li>
- *     <li>Set the various URI components through the respective methods ({@link #scheme(String)},
- *     {@link #userInfo(String)}, {@link #host(String)}, {@link #port(int)}, {@link #path(String)},
- *     {@link #pathSegment(String...)}, {@link #queryParam(String, Object...)}, and
- *     {@link #fragment(String)}.</li>
- *     <li>Build the {@link UriComponents} instance with the {@link #build()} method.</li>
+ * <li>Create a {@code UriComponentsBuilder} with one of the static factory methods
+ * (such as {@link #fromPath(String)} or {@link #fromUri(URI)})</li>
+ * <li>Set the various URI components through the respective methods ({@link #scheme(String)},
+ * {@link #userInfo(String)}, {@link #host(String)}, {@link #port(int)}, {@link #path(String)},
+ * {@link #pathSegment(String...)}, {@link #queryParam(String, Object...)}, and
+ * {@link #fragment(String)}.</li>
+ * <li>Build the {@link UriComponents} instance with the {@link #build()} method.</li>
  * </ol>
  *
  * @author Arjen Poutsma
@@ -303,7 +303,7 @@ public UriComponents buildAndExpand(Object... uriVariableValues) {
 	// URI components methods
 
 	/**
-	 * Initializes all components of this URI builder with the components of the given URI.
+	 * Initialize all components of this URI builder with the components of the given URI.
 	 * @param uri the URI
 	 * @return this UriComponentsBuilder
 	 */
@@ -352,7 +352,7 @@ private void resetSchemeSpecificPart() {
 	}
 
 	/**
-	 * Sets the URI scheme. The given scheme may contain URI template variables,
+	 * Set the URI scheme. The given scheme may contain URI template variables,
 	 * and may also be {@code null} to clear the scheme of this builder.
 	 * @param scheme the URI scheme
 	 * @return this UriComponentsBuilder
@@ -421,9 +421,8 @@ public UriComponentsBuilder schemeSpecificPart(String ssp) {
 	}
 
 	/**
-	 * Sets the URI user info. The given user info may contain URI template
-	 * variables, and may also be {@code null} to clear the user info of this
-	 * builder.
+	 * Set the URI user info. The given user info may contain URI template variables,
+	 * and may also be {@code null} to clear the user info of this builder.
 	 * @param userInfo the URI user info
 	 * @return this UriComponentsBuilder
 	 */
@@ -434,8 +433,8 @@ public UriComponentsBuilder userInfo(String userInfo) {
 	}
 
 	/**
-	 * Sets the URI host. The given host may contain URI template variables, and
-	 * may also be {@code null} to clear the host of this builder.
+	 * Set the URI host. The given host may contain URI template variables,
+	 * and may also be {@code null} to clear the host of this builder.
 	 * @param host the URI host
 	 * @return this UriComponentsBuilder
 	 */
@@ -446,7 +445,7 @@ public UriComponentsBuilder host(String host) {
 	}
 
 	/**
-	 * Sets the URI port. Passing {@code -1} will clear the port of this builder.
+	 * Set the URI port. Passing {@code -1} will clear the port of this builder.
 	 * @param port the URI port
 	 * @return this UriComponentsBuilder
 	 */
@@ -458,8 +457,8 @@ public UriComponentsBuilder port(int port) {
 	}
 
 	/**
-	 * Appends the given path to the existing path of this builder. The given
-	 * path may contain URI template variables.
+	 * Append the given path to the existing path of this builder.
+	 * The given path may contain URI template variables.
 	 * @param path the URI path
 	 * @return this UriComponentsBuilder
 	 */
@@ -470,7 +469,7 @@ public UriComponentsBuilder path(String path) {
 	}
 
 	/**
-	 * Sets the path of this builder overriding all existing path and path segment values.
+	 * Set the path of this builder overriding all existing path and path segment values.
 	 * @param path the URI path; a {@code null} value results in an empty path.
 	 * @return this UriComponentsBuilder
 	 */
@@ -481,8 +480,8 @@ public UriComponentsBuilder replacePath(String path) {
 	}
 
 	/**
-	 * Appends the given path segments to the existing path of this builder. Each given
-	 * path segments may contain URI template variables.
+	 * Append the given path segments to the existing path of this builder.
+	 * Each given path segment may contain URI template variables.
 	 * @param pathSegments the URI path segments
 	 * @return this UriComponentsBuilder
 	 */
@@ -494,7 +493,7 @@ public UriComponentsBuilder pathSegment(String... pathSegments) throws IllegalAr
 	}
 
 	/**
-	 * Appends the given query to the existing query of this builder.
+	 * Append the given query to the existing query of this builder.
 	 * The given query may contain URI template variables.
 	 * <p><strong>Note:</strong> The presence of reserved characters can prevent
 	 * correct parsing of the URI string. For example if a query parameter
@@ -527,7 +526,7 @@ public UriComponentsBuilder query(String query) {
 	}
 
 	/**
-	 * Sets the query of this builder overriding all existing query parameters.
+	 * Set the query of this builder overriding all existing query parameters.
 	 * @param query the query string; a {@code null} value removes all query parameters.
 	 * @return this UriComponentsBuilder
 	 */
@@ -539,7 +538,7 @@ public UriComponentsBuilder replaceQuery(String query) {
 	}
 
 	/**
-	 * Appends the given query parameter to the existing query parameters. The
+	 * Append the given query parameter to the existing query parameters. The
 	 * given name or any of the values may contain URI template variables. If no
 	 * values are given, the resulting URI will contain the query parameter name
 	 * only (i.e. {@code ?foo} instead of {@code ?foo=bar}.
@@ -563,7 +562,7 @@ public UriComponentsBuilder queryParam(String name, Object... values) {
 	}
 
 	/**
-	 * Adds the given query parameters.
+	 * Add the given query parameters.
 	 * @param params the params
 	 * @return this UriComponentsBuilder
 	 */
@@ -574,9 +573,8 @@ public UriComponentsBuilder queryParams(MultiValueMap<String, String> params) {
 	}
 
 	/**
-	 * Sets the query parameter values overriding all existing query values for
-	 * the same parameter. If no values are given, the query parameter is
-	 * removed.
+	 * Set the query parameter values overriding all existing query values for
+	 * the same parameter. If no values are given, the query parameter is removed.
 	 * @param name the query parameter name
 	 * @param values the query parameter values
 	 * @return this UriComponentsBuilder
@@ -592,9 +590,8 @@ public UriComponentsBuilder replaceQueryParam(String name, Object... values) {
 	}
 
 	/**
-	 * Sets the URI fragment. The given fragment may contain URI template
-	 * variables, and may also be {@code null} to clear the fragment of this
-	 * builder.
+	 * Set the URI fragment. The given fragment may contain URI template variables,
+	 * and may also be {@code null} to clear the fragment of this builder.
 	 * @param fragment the URI fragment
 	 * @return this UriComponentsBuilder
 	 */
@@ -615,6 +612,7 @@ private interface PathComponentBuilder {
 		PathComponent build();
 	}
 
+
 	private static class CompositePathComponentBuilder implements PathComponentBuilder {
 
 		private final LinkedList<PathComponentBuilder> componentBuilders = new LinkedList<PathComponentBuilder>();