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

Improve UriBuilder Javadoc on query params 

Add a note on encoding for query parameters specifically mentioning the
"+" sign and a link to the reference docs.

Also remove duplicate Javadoc in UriComponentsBuilder which is already
inherited from UriBuilder.
This commit is contained in:
Rossen Stoyanchev 2019-12-20 11:03:08 +00:00
parent a1b8b18282
commit 261956fd08
3 changed files with 48 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
spring-web/src/main/java/org/springframework/web/util/HierarchicalUriComponents.java
View File

@ -588,7 +588,7 @@ final class HierarchicalUriComponents extends UriComponents {
/**
* Enumeration used to identify the allowed characters per URI component.
* <p>Contains methods to indicate whether a given character is valid in a specific URI component.
* @see <a href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>
* @see <a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>
*/
enum Type {

70
spring-web/src/main/java/org/springframework/web/util/UriBuilder.java
View File

@ -98,31 +98,40 @@ public interface UriBuilder {
UriBuilder pathSegment(String... pathSegments) throws IllegalArgumentException;
/**
* 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
* contains {@code '='} or {@code '&'} characters, the query string cannot
* be parsed unambiguously. Such values should be substituted for URI
* variables to enable correct parsing:
* <pre class="code">
* builder.query(&quot;filter={value}&quot;).uriString(&quot;hot&amp;cold&quot;);
* </pre>
* Parse the given query string into query parameters where parameters are
* separated with {@code '&'} and their values, if any, with {@code '='}.
* The query may contain URI template variables.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param query the query string
*/
UriBuilder query(String query);
/**
* Set the query of this builder overriding all existing query parameters.
* @param query the query string, or {@code null} to remove all query params
* Clear existing query parameters and then delegate to {@link #query(String)}.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param query the query string; a {@code null} value removes all query parameters.
*/
UriBuilder replaceQuery(@Nullable String query);
/**
* 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
* Append the given query parameter. Both the parameter name and values may
* contain URI template variables to be expanded later from values. If no
* values are given, the resulting URI will contain the query parameter name
* only (i.e. {@code ?foo} instead of {@code ?foo=bar}.
* only, e.g. {@code "?foo"} instead of {@code "?foo=bar"}.
* <p><strong>Note:</strong> encoding, if applied, will only encode characters
* that are illegal in a query parameter name or value such as {@code "="}
* or {@code "&"}. All others that are legal as per syntax rules in
* <a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a> are not
* encoded. This includes {@code "+"} which sometimes needs to be encoded
* to avoid its interpretation as an encoded space. Stricter encoding may
* be applied by using a URI template variable along with stricter encoding
* on variable values. For more details please read the
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#web-uri-encoding">"URI Encoding"</a>
* section of the Spring Framework reference.
* @param name the query parameter name
* @param values the query parameter values
* @see #queryParam(String, Collection)
@ -130,10 +139,10 @@ public interface UriBuilder {
UriBuilder queryParam(String name, Object... values);
/**
* 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}.
* Variant of {@link #queryParam(String, Object...)} with a Collection.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param name the query parameter name
* @param values the query parameter values
* @since 5.2
@ -142,14 +151,20 @@ public interface UriBuilder {
UriBuilder queryParam(String name, @Nullable Collection<?> values);
/**
* Add the given query parameters.
* Add multiple query parameters and values.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param params the params
*/
UriBuilder queryParams(MultiValueMap<String, String> params);
/**
* Set 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 replacing existing values, or if no
* values are given, the query parameter is removed.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param name the query parameter name
* @param values the query parameter values
* @see #replaceQueryParam(String, Collection)
@ -157,8 +172,10 @@ public interface UriBuilder {
UriBuilder replaceQueryParam(String name, Object... values);
/**
* Set the query parameter values overriding all existing query values for
* the same parameter. If no values are given, the query parameter is removed.
* Variant of {@link #replaceQueryParam(String, Object...)} with a Collection.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param name the query parameter name
* @param values the query parameter values
* @since 5.2
@ -167,7 +184,10 @@ public interface UriBuilder {
UriBuilder replaceQueryParam(String name, @Nullable Collection<?> values);
/**
* Set the query parameter values overriding all existing query values.
* Set the query parameter values after removing all existing ones.
* <p><strong>Note: </strong> please, review the Javadoc of
* {@link #queryParam(String, Object...)} for further notes on the treatment
* and encoding of individual query parameters.
* @param params the query parameter name
*/
UriBuilder replaceQueryParams(MultiValueMap<String, String> params);

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

@ -521,12 +521,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder scheme(@Nullable String scheme) {
this.scheme = scheme;
@ -547,12 +541,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder userInfo(@Nullable String userInfo) {
this.userInfo = userInfo;
@ -560,12 +548,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder host(@Nullable String host) {
this.host = host;
@ -573,11 +555,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* Set the URI port. Passing {@code -1} will clear the port of this builder.
* @param port the URI port
* @return this UriComponentsBuilder
*/
@Override
public UriComponentsBuilder port(int port) {
Assert.isTrue(port >= -1, "Port must be >= -1");
@ -586,13 +563,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* Set the URI port. Use this method only when the port needs to be
* parameterized with a URI variable. Otherwise use {@link #port(int)}.
* Passing {@code null} will clear the port of this builder.
* @param port the URI port
* @return this UriComponentsBuilder
*/
@Override
public UriComponentsBuilder port(@Nullable String port) {
this.port = port;
@ -600,12 +570,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder path(String path) {
this.pathBuilder.addPath(path);
@ -613,13 +577,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* Append path segments to the existing path. Each path segment may contain
* URI template variables and should not contain any slashes.
* Use {@code path("/")} subsequently to ensure a trailing slash.
* @param pathSegments the URI path segments
* @return this UriComponentsBuilder
*/
@Override
public UriComponentsBuilder pathSegment(String... pathSegments) throws IllegalArgumentException {
this.pathBuilder.addPathSegments(pathSegments);
@ -627,11 +584,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder replacePath(@Nullable String path) {
this.pathBuilder = new CompositePathComponentBuilder();
@ -642,22 +594,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
* contains {@code '='} or {@code '&'} characters, the query string cannot
* be parsed unambiguously. Such values should be substituted for URI
* variables to enable correct parsing:
* <pre class="code">
* UriComponentsBuilder.fromUriString(&quot;/hotels/42&quot;)
* .query(&quot;filter={value}&quot;)
* .buildAndExpand(&quot;hot&amp;cold&quot;);
* </pre>
* @param query the query string
* @return this UriComponentsBuilder
*/
@Override
public UriComponentsBuilder query(@Nullable String query) {
if (query != null) {
@ -676,11 +612,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder replaceQuery(@Nullable String query) {
this.queryParams.clear();
@ -691,16 +622,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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}).
* @param name the query parameter name
* @param values the query parameter values
* @return this UriComponentsBuilder
* @see #queryParam(String, Collection)
*/
@Override
public UriComponentsBuilder queryParam(String name, Object... values) {
Assert.notNull(name, "Name must not be null");
@ -717,26 +638,13 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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}).
* @param name the query parameter name
* @param values the query parameter values
* @return this UriComponentsBuilder
* @since 5.2
* @see #queryParam(String, Object...)
*/
@Override
public UriComponentsBuilder queryParam(String name, @Nullable Collection<?> values) {
return queryParam(name, values != null ? values.toArray() : EMPTY_VALUES);
}
/**
* Add the given query parameters.
* @param params the params
* @return this UriComponentsBuilder
* {@inheritDoc}
* @since 4.0
*/
@Override
@ -747,14 +655,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
* @see #replaceQueryParam(String, Collection)
*/
@Override
public UriComponentsBuilder replaceQueryParam(String name, Object... values) {
Assert.notNull(name, "Name must not be null");
@ -766,24 +666,13 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
* @see #replaceQueryParam(String, Object...)
* @since 5.2
*/
@Override
public UriComponentsBuilder replaceQueryParam(String name, @Nullable Collection<?> values) {
return replaceQueryParam(name, values != null ? values.toArray() : EMPTY_VALUES);
}
/**
* Set the query parameter values overriding all existing query values.
* @param params the query parameter name
* @return this UriComponentsBuilder
* {@inheritDoc}
* @since 4.2
*/
@Override
@ -795,12 +684,6 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
return this;
}
/**
* 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
*/
@Override
public UriComponentsBuilder fragment(@Nullable String fragment) {
if (fragment != null) {