Further UriComponentsBuilder javadoc revision

(cherry picked from commit 54636b3)

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

@@ -30,10 +30,10 @@ import org.springframework.util.Assert;
 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,17 +135,17 @@ public abstract class UriComponents implements Serializable {
 	 * 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");
@@ -153,10 +153,10 @@ public abstract class UriComponents implements Serializable {
 	}
 
 	/**
-	 * 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");
@@ -164,14 +164,14 @@ public abstract class UriComponents implements Serializable {
 	}
 
 	/**
-	 * 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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -34,15 +34,15 @@ import org.springframework.web.util.HierarchicalUriComponents.PathComponent;
 /**
  * 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,6 +303,7 @@ public class UriComponentsBuilder {
 	 * Build a URI String. This is a shortcut method which combines calls
 	 * to {@link #build()}, then {@link UriComponents#encode()} and finally
 	 * {@link UriComponents#toUriString()}.
+	 * @since 4.1
 	 * @see UriComponents#toUriString()
 	 */
 	public String toUriString() {
@@ -313,7 +314,7 @@ public class UriComponentsBuilder {
 	// 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
 	 */
@@ -362,7 +363,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
@@ -431,9 +432,8 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -444,8 +444,8 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -456,7 +456,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -468,8 +468,8 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -480,7 +480,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -491,8 +491,8 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -504,7 +504,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
@@ -537,7 +537,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -549,7 +549,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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}.
@@ -573,7 +573,7 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * Adds the given query parameters.
+	 * Add the given query parameters.
 	 * @param params the params
 	 * @return this UriComponentsBuilder
 	 */
@@ -584,9 +584,8 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
@@ -602,9 +601,8 @@ public class UriComponentsBuilder {
 	}
 
 	/**
-	 * 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
 	 */
@@ -625,6 +623,7 @@ public class UriComponentsBuilder {
 		PathComponent build();
 	}
 
+
 	private static class CompositePathComponentBuilder implements PathComponentBuilder {
 
 		private final LinkedList<PathComponentBuilder> componentBuilders = new LinkedList<PathComponentBuilder>();