public interface UriBuilder
Effectively a generalization of UriComponentsBuilder but with
shortcuts to expand directly into URI rather than
UriComponents and also leaving common concerns such as encoding
preferences, a base URI, and others as implementation concerns.
Typically obtained via UriBuilderFactory which serves as a central
component configured once and used to create many URLs.
UriBuilderFactory,
UriComponentsBuilder| Modifier and Type | Method and Description |
|---|---|
URI |
build(Map<String,?> uriVariables)
Build a
URI instance and replaces URI template variables
with the values from a map. |
URI |
build(Object... uriVariables)
Build a
URI instance and replaces URI template variables
with the values from an array. |
UriBuilder |
fragment(String fragment)
Set the URI fragment.
|
UriBuilder |
host(String host)
Set the URI host which may contain URI template variables, and may also
be
null to clear the host of this builder. |
UriBuilder |
path(String path)
Append to the path of this builder.
|
UriBuilder |
pathSegment(String... pathSegments)
Append to the path using path segments.
|
UriBuilder |
port(int port)
Set the URI port.
|
UriBuilder |
port(String port)
Set the URI port .
|
UriBuilder |
query(String query)
Parse the given query string into query parameters where parameters are
separated with
'&' and their values, if any, with '='. |
UriBuilder |
queryParam(String name,
Collection<?> values)
Variant of
queryParam(String, Object...) with a Collection. |
UriBuilder |
queryParam(String name,
Object... values)
Append the given query parameter.
|
UriBuilder |
queryParams(MultiValueMap<String,String> params)
Add multiple query parameters and values.
|
UriBuilder |
replacePath(String path)
Override the existing path.
|
UriBuilder |
replaceQuery(String query)
Clear existing query parameters and then delegate to
query(String). |
UriBuilder |
replaceQueryParam(String name,
Collection<?> values)
Variant of
replaceQueryParam(String, Object...) with a Collection. |
UriBuilder |
replaceQueryParam(String name,
Object... values)
Set the query parameter values replacing existing values, or if no
values are given, the query parameter is removed.
|
UriBuilder |
replaceQueryParams(MultiValueMap<String,String> params)
Set the query parameter values after removing all existing ones.
|
UriBuilder |
scheme(String scheme)
Set the URI scheme which may contain URI template variables,
and may also be
null to clear the scheme of this builder. |
UriBuilder |
userInfo(String userInfo)
Set the URI user info which may contain URI template variables, and
may also be
null to clear the user info of this builder. |
UriBuilder scheme(@Nullable String scheme)
null to clear the scheme of this builder.scheme - the URI schemeUriBuilder userInfo(@Nullable String userInfo)
null to clear the user info of this builder.userInfo - the URI user infoUriBuilder host(@Nullable String host)
null to clear the host of this builder.host - the URI hostUriBuilder port(int port)
-1 will clear the port of this builder.port - the URI portUriBuilder port(@Nullable String port)
port(int).
Passing null will clear the port of this builder.port - the URI portUriBuilder path(String path)
The given value is appended as-is without any checks for slashes other than to clean up duplicates. For example:
builder.path("/first-").path("value/").path("/{id}").build("123")
// Results is "/first-value/123"
By contrast pathSegment(String...) builds the path from
individual path segments and in that case slashes are inserted transparently.
In some cases you may use a combination of both pathSegment and
path. For example:
builder.pathSegment("first-value", "second-value").path("/")
// Results is "/first-value/second-value/"
If a URI variable value contains slashes, whether those are encoded or
not depends on the configured encoding mode. See
UriComponentsBuilder.encode(), or if using
UriComponentsBuilder via DefaultUriBuilderFactory
(e.g. WebClient or RestTemplate) see its
encodingMode property.
Also see the
URI Encoding section of the reference docs.
path - the URI pathUriBuilder replacePath(@Nullable String path)
path - the URI path, or null for an empty pathUriBuilder pathSegment(String... pathSegments) throws IllegalArgumentException
builder.pathSegment("first-value", "second-value", "{id}").build("123")
// Results is "/first-value/second-value/123"
If slashes are present in a path segment, they are encoded:
builder.pathSegment("ba/z", "{id}").build("a/b")
// Results is "/ba%2Fz/a%2Fb"
To insert a trailing slash, use the path(java.lang.String) builder method:
builder.pathSegment("first-value", "second-value").path("/")
// Results is "/first-value/second-value/"
pathSegments - the URI path segmentsIllegalArgumentExceptionUriBuilder query(String query)
'&' and their values, if any, with '='.
The query may contain URI template variables.
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
query - the query stringUriBuilder replaceQuery(@Nullable String query)
query(String).
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
query - the query string; a null value removes all query parameters.UriBuilder queryParam(String name, Object... values)
"?foo" instead of "?foo=bar".
Note: encoding, if applied, will only encode characters
that are illegal in a query parameter name or value such as "="
or "&". All others that are legal as per syntax rules in
RFC 3986 are not
encoded. This includes "+" 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
"URI Encoding"
section of the Spring Framework reference.
name - the query parameter namevalues - the query parameter valuesqueryParam(String, Collection)UriBuilder queryParam(String name, @Nullable Collection<?> values)
queryParam(String, Object...) with a Collection.
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
name - the query parameter namevalues - the query parameter valuesqueryParam(String, Object...)UriBuilder queryParams(MultiValueMap<String,String> params)
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
params - the paramsUriBuilder replaceQueryParam(String name, Object... values)
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
name - the query parameter namevalues - the query parameter valuesreplaceQueryParam(String, Collection)UriBuilder replaceQueryParam(String name, @Nullable Collection<?> values)
replaceQueryParam(String, Object...) with a Collection.
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
name - the query parameter namevalues - the query parameter valuesreplaceQueryParam(String, Object...)UriBuilder replaceQueryParams(MultiValueMap<String,String> params)
Note: please, review the Javadoc of
queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
params - the query parameter nameUriBuilder fragment(@Nullable String fragment)
null to clear the fragment of this builder.fragment - the URI fragmentURI build(Object... uriVariables)
URI instance and replaces URI template variables
with the values from an array.uriVariables - the map of URI variables