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 |
queryParamIfPresent(String name,
Optional<?> value)
Delegates to either
queryParam(String, Object...) or
queryParam(String, Collection) if the given Optional has
a value, or else if it is empty, no query parameter is added at all. |
UriBuilder |
queryParams(MultiValueMap<String,String> params)
Add multiple query parameters and values.
|
UriBuilder |
replacePath(String path)
Override the current 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 to previous path
values without inserting any additional slashes. For example:
builder.path("/first-").path("value/").path("/{id}").build("123") // Results is "/first-value/123"
By contrast pathSegment
does insert
slashes between individual path segments. For example:
builder.pathSegment("first-value", "second-value").path("/") // Results is "/first-value/second-value/"
The resulting full path is normalized to eliminate duplicate slashes.
Note: When inserting a URI variable value that
contains slashes in a path
, whether those are
encoded depends on the configured encoding mode. For more details, see
UriComponentsBuilder.encode()
, or otherwise if building URIs
indirectly via WebClient
or RestTemplate
, see its
encodingMode
.
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/"
Empty path segments are ignored and therefore duplicate slashes do not appear in the resulting full path.
pathSegments
- the URI path segmentsIllegalArgumentException
UriBuilder 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 queryParamIfPresent(String name, Optional<?> value)
queryParam(String, Object...)
or
queryParam(String, Collection)
if the given Optional
has
a value, or else if it is empty, no query parameter is added at all.name
- the query parameter namevalue
- an Optional, either empty or holding the query parameter value.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