From 54636b3f7cff08a2565670f95df9f23286663969 Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Tue, 20 May 2014 01:13:18 +0200 Subject: [PATCH] Further UriComponentsBuilder javadoc revision --- .../web/util/UriComponents.java | 40 ++++++------- .../web/util/UriComponentsBuilder.java | 60 +++++++++---------- 2 files changed, 49 insertions(+), 51 deletions(-) diff --git a/spring-web/src/main/java/org/springframework/web/util/UriComponents.java b/spring-web/src/main/java/org/springframework/web/util/UriComponents.java index be20b0fa00..e81e2ba786 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriComponents.java +++ b/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. + *

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 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. + *

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); } /** diff --git a/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java b/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java index 4dde5c5317..4565eebfdc 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java +++ b/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java @@ -34,15 +34,15 @@ import org.springframework.web.util.HierarchicalUriComponents.PathComponent; /** * Builder for {@link UriComponents}. * - *

Typical usage involves: + *

Typical usage involves: *

    - *
  1. Create a {@code UriComponentsBuilder} with one of the static factory methods (such as - * {@link #fromPath(String)} or {@link #fromUri(URI)})
    2. - *
  2. 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)}.
    3. - *
  3. Build the {@link UriComponents} instance with the {@link #build()} method.
    4. + *
  4. Create a {@code UriComponentsBuilder} with one of the static factory methods + * (such as {@link #fromPath(String)} or {@link #fromUri(URI)})
    5. + *
  5. 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)}.
    6. + *
  6. Build the {@link UriComponents} instance with the {@link #build()} method.
    7. *
* * @author Arjen Poutsma @@ -303,7 +303,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 */ @@ -352,7 +352,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 @@ -421,9 +421,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 */ @@ -434,8 +433,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 */ @@ -446,7 +445,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 */ @@ -458,8 +457,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 */ @@ -470,7 +469,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 */ @@ -481,8 +480,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 */ @@ -494,7 +493,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. *

Note: The presence of reserved characters can prevent * correct parsing of the URI string. For example if a query parameter @@ -527,7 +526,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 */ @@ -539,7 +538,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}. @@ -563,7 +562,7 @@ public class UriComponentsBuilder { } /** - * Adds the given query parameters. + * Add the given query parameters. * @param params the params * @return this UriComponentsBuilder */ @@ -574,9 +573,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 @@ -592,9 +590,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 */ @@ -615,6 +612,7 @@ public class UriComponentsBuilder { PathComponent build(); } + private static class CompositePathComponentBuilder implements PathComponentBuilder { private final LinkedList componentBuilders = new LinkedList(); -- GitLab