root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 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;
/**
* 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);
}
/**

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

@ -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,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.
* <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 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<PathComponentBuilder> componentBuilders = new LinkedList<PathComponentBuilder>();