GitHub-Spring
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Further UriComponentsBuilder javadoc revision

pull/555/head
Juergen Hoeller 12 years ago
parent
545c28fd4e
commit
54636b3f7c
2 changed files with 49 additions and 51 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 40
      spring-web/src/main/java/org/springframework/web/util/UriComponents.java
  2. 60
      spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java

40
spring-web/src/main/java/org/springframework/web/util/UriComponents.java
Unescape 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);
} }
/** /**

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

@ -34,15 +34,15 @@ 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
* {@link #fragment(String)}.</li> * {@link #fragment(String)}.</li>
* <li>Build the {@link UriComponents} instance with the {@link #build()} method.</li> * <li>Build the {@link UriComponents} instance with the {@link #build()} method.</li>
* </ol> * </ol>
* *
* @author Arjen Poutsma * @author Arjen Poutsma
@ -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>();

Write Preview
Loading…
Cancel
Save