root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Further UriComponentsBuilder javadoc revision

This commit is contained in:
Juergen Hoeller 2014-05-20 01:13:18 +02:00
parent 545c28fd4e
commit 54636b3f7c
2 changed files with 49 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@ -34,10 +34,10 @@ import org.springframework.web.util.HierarchicalUriComponents.PathComponent;
/** /**
* Builder for {@link UriComponents}. * Builder for {@link UriComponents}.
* *
* <p></p>Typical usage involves: * <p>Typical usage involves:
* <ol> * <ol>
* <li>Create a {@code UriComponentsBuilder} with one of the static factory methods (such as * <li>Create a {@code UriComponentsBuilder} with one of the static factory methods
* {@link #fromPath(String)} or {@link #fromUri(URI)})</li> * (such as {@link #fromPath(String)} or {@link #fromUri(URI)})</li>
* <li>Set the various URI components through the respective methods ({@link #scheme(String)}, * <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 #userInfo(String)}, {@link #host(String)}, {@link #port(int)}, {@link #path(String)},
* {@link #pathSegment(String...)}, {@link #queryParam(String, Object...)}, and * {@link #pathSegment(String...)}, {@link #queryParam(String, Object...)}, and
@ -303,7 +303,7 @@ public class UriComponentsBuilder {
// URI components methods // 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 * @param uri the URI
* @return this UriComponentsBuilder * @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. * and may also be {@code null} to clear the scheme of this builder.
* @param scheme the URI scheme * @param scheme the URI scheme
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
@ -421,9 +421,8 @@ public class UriComponentsBuilder {
} }
/** /**
* Sets the URI user info. The given user info may contain URI template * Set the URI user info. The given user info may contain URI template variables,
* variables, and may also be {@code null} to clear the user info of this * and may also be {@code null} to clear the user info of this builder.
* builder.
* @param userInfo the URI user info * @param userInfo the URI user info
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
*/ */
@ -434,8 +433,8 @@ public class UriComponentsBuilder {
} }
/** /**
* Sets the URI host. The given host may contain URI template variables, and * Set the URI host. The given host may contain URI template variables,
* may also be {@code null} to clear the host of this builder. * and may also be {@code null} to clear the host of this builder.
* @param host the URI host * @param host the URI host
* @return this UriComponentsBuilder * @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 * @param port the URI port
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
*/ */
@ -458,8 +457,8 @@ public class UriComponentsBuilder {
} }
/** /**
* Appends the given path to the existing path of this builder. The given * Append the given path to the existing path of this builder.
* path may contain URI template variables. * The given path may contain URI template variables.
* @param path the URI path * @param path the URI path
* @return this UriComponentsBuilder * @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. * @param path the URI path; a {@code null} value results in an empty path.
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
*/ */
@ -481,8 +480,8 @@ public class UriComponentsBuilder {
} }
/** /**
* Appends the given path segments to the existing path of this builder. Each given * Append the given path segments to the existing path of this builder.
* path segments may contain URI template variables. * Each given path segment may contain URI template variables.
* @param pathSegments the URI path segments * @param pathSegments the URI path segments
* @return this UriComponentsBuilder * @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. * The given query may contain URI template variables.
* <p><strong>Note:</strong> The presence of reserved characters can prevent * <p><strong>Note:</strong> The presence of reserved characters can prevent
* correct parsing of the URI string. For example if a query parameter * 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. * @param query the query string; a {@code null} value removes all query parameters.
* @return this UriComponentsBuilder * @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 * 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 * values are given, the resulting URI will contain the query parameter name
* only (i.e. {@code ?foo} instead of {@code ?foo=bar}. * 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 * @param params the params
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
*/ */
@ -574,9 +573,8 @@ public class UriComponentsBuilder {
} }
/** /**
* Sets the query parameter values overriding all existing query values for * Set the query parameter values overriding all existing query values for
* the same parameter. If no values are given, the query parameter is * the same parameter. If no values are given, the query parameter is removed.
* removed.
* @param name the query parameter name * @param name the query parameter name
* @param values the query parameter values * @param values the query parameter values
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
@ -592,9 +590,8 @@ public class UriComponentsBuilder {
} }
/** /**
* Sets the URI fragment. The given fragment may contain URI template * Set the URI fragment. The given fragment may contain URI template variables,
* variables, and may also be {@code null} to clear the fragment of this * and may also be {@code null} to clear the fragment of this builder.
* builder.
* @param fragment the URI fragment * @param fragment the URI fragment
* @return this UriComponentsBuilder * @return this UriComponentsBuilder
*/ */
@ -615,6 +612,7 @@ public class UriComponentsBuilder {
PathComponent build(); PathComponent build();
} }
private static class CompositePathComponentBuilder implements PathComponentBuilder { private static class CompositePathComponentBuilder implements PathComponentBuilder {
private final LinkedList<PathComponentBuilder> componentBuilders = new LinkedList<PathComponentBuilder>(); private final LinkedList<PathComponentBuilder> componentBuilders = new LinkedList<PathComponentBuilder>();