public class UriComponentsBuilder extends Object implements UriBuilder, Cloneable
UriComponents.
Typical usage involves:
UriComponentsBuilder with one of the static factory methods
(such as fromPath(String) or fromUri(URI))scheme(String),
userInfo(String), host(String), port(int), path(String),
pathSegment(String...), queryParam(String, Object...), and
fragment(String).UriComponents instance with the build() method.newInstance(),
fromPath(String),
fromUri(URI)| Modifier | Constructor and Description |
|---|---|
protected |
UriComponentsBuilder()
Default constructor.
|
protected |
UriComponentsBuilder(UriComponentsBuilder other)
Create a deep copy of the given UriComponentsBuilder.
|
| Modifier and Type | Method and Description |
|---|---|
UriComponents |
build()
Build a
UriComponents instance from the various components contained in this builder. |
UriComponents |
build(boolean encoded)
Variant of
build() to create a UriComponents instance
when components are already fully encoded. |
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. |
UriComponents |
buildAndExpand(Map<String,?> uriVariables)
Build a
UriComponents instance and replaces URI template variables
with the values from a map. |
UriComponents |
buildAndExpand(Object... uriVariableValues)
Build a
UriComponents instance and replaces URI template variables
with the values from an array. |
Object |
clone()
Public declaration of Object's
clone() method. |
UriComponentsBuilder |
cloneBuilder()
Clone this
UriComponentsBuilder. |
UriComponentsBuilder |
encode()
Request to have the URI template pre-encoded at build time, and
URI variables encoded separately when expanded.
|
UriComponentsBuilder |
encode(Charset charset)
A variant of
encode() with a charset other than "UTF-8". |
UriComponentsBuilder |
fragment(String fragment)
Set the URI fragment.
|
static UriComponentsBuilder |
fromHttpRequest(HttpRequest request)
Create a new
UriComponents object from the URI associated with
the given HttpRequest while also overlaying with values from the headers
"Forwarded" (RFC 7239),
or "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if
"Forwarded" is not found. |
static UriComponentsBuilder |
fromHttpUrl(String httpUrl)
Create a URI components builder from the given HTTP URL String.
|
static UriComponentsBuilder |
fromOriginHeader(String origin)
Create an instance by parsing the "Origin" header of an HTTP request.
|
static UriComponentsBuilder |
fromPath(String path)
Create a builder that is initialized with the given path.
|
static UriComponentsBuilder |
fromUri(URI uri)
Create a builder that is initialized from the given
URI. |
static UriComponentsBuilder |
fromUriString(String uri)
Create a builder that is initialized with the given URI string.
|
UriComponentsBuilder |
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. |
static UriComponentsBuilder |
newInstance()
Create a new, empty builder.
|
static InetSocketAddress |
parseForwardedFor(HttpRequest request,
InetSocketAddress remoteAddress)
Parse the first "Forwarded: for=..." or "X-Forwarded-For" header value to
an
InetSocketAddress representing the address of the client. |
UriComponentsBuilder |
path(String path)
Append to the path of this builder.
|
UriComponentsBuilder |
pathSegment(String... pathSegments)
Append to the path using path segments.
|
UriComponentsBuilder |
port(int port)
Set the URI port.
|
UriComponentsBuilder |
port(String port)
Set the URI port .
|
UriComponentsBuilder |
query(String query)
Parse the given query string into query parameters where parameters are
separated with
'&' and their values, if any, with '='. |
UriComponentsBuilder |
queryParam(String name,
Collection<?> values)
Variant of
UriBuilder.queryParam(String, Object...) with a Collection. |
UriComponentsBuilder |
queryParam(String name,
Object... values)
Append the given query parameter.
|
UriComponentsBuilder |
queryParamIfPresent(String name,
Optional<?> value)
Delegates to either
UriBuilder.queryParam(String, Object...) or
UriBuilder.queryParam(String, Collection) if the given Optional has
a value, or else if it is empty, no query parameter is added at all. |
UriComponentsBuilder |
queryParams(MultiValueMap<String,String> params)
Add multiple query parameters and values.
|
UriComponentsBuilder |
replacePath(String path)
Override the current path.
|
UriComponentsBuilder |
replaceQuery(String query)
Clear existing query parameters and then delegate to
UriBuilder.query(String). |
UriComponentsBuilder |
replaceQueryParam(String name,
Collection<?> values)
Variant of
UriBuilder.replaceQueryParam(String, Object...) with a Collection. |
UriComponentsBuilder |
replaceQueryParam(String name,
Object... values)
Set the query parameter values replacing existing values, or if no
values are given, the query parameter is removed.
|
UriComponentsBuilder |
replaceQueryParams(MultiValueMap<String,String> params)
Set the query parameter values after removing all existing ones.
|
UriComponentsBuilder |
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. |
UriComponentsBuilder |
schemeSpecificPart(String ssp)
Set the URI scheme-specific-part.
|
String |
toUriString()
Build a URI String.
|
UriComponentsBuilder |
uri(URI uri)
Initialize components of this builder from components of the given URI.
|
UriComponentsBuilder |
uriComponents(UriComponents uriComponents)
Set or append individual URI components of this builder from the values
of the given
UriComponents instance. |
UriComponentsBuilder |
uriVariables(Map<String,Object> uriVariables)
Configure URI variables to be expanded at build time.
|
UriComponentsBuilder |
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. |
protected UriComponentsBuilder()
newInstance(),
fromPath(String),
fromUri(URI)protected UriComponentsBuilder(UriComponentsBuilder other)
other - the other builder to copy frompublic static UriComponentsBuilder newInstance()
UriComponentsBuilderpublic static UriComponentsBuilder fromPath(String path)
path - the path to initialize withUriComponentsBuilderpublic static UriComponentsBuilder fromUri(URI uri)
URI.
Note: the components in the resulting builder will be
in fully encoded (raw) form and further changes must also supply values
that are fully encoded, for example via methods in UriUtils.
In addition please use build(boolean) with a value of "true" to
build the UriComponents instance in order to indicate that the
components are encoded.
uri - the URI to initialize withUriComponentsBuilderpublic static UriComponentsBuilder fromUriString(String uri)
Note: The presence of reserved characters can prevent
correct parsing of the URI string. For example if a query parameter
contains '=' or '&' characters, the query string cannot
be parsed unambiguously. Such values should be substituted for URI
variables to enable correct parsing:
String uriString = "/hotels/42?filter={value}";
UriComponentsBuilder.fromUriString(uriString).buildAndExpand("hot&cold");
uri - the URI string to initialize withUriComponentsBuilderpublic static UriComponentsBuilder fromHttpUrl(String httpUrl)
Note: The presence of reserved characters can prevent
correct parsing of the URI string. For example if a query parameter
contains '=' or '&' characters, the query string cannot
be parsed unambiguously. Such values should be substituted for URI
variables to enable correct parsing:
String urlString = "https://example.com/hotels/42?filter={value}";
UriComponentsBuilder.fromHttpUrl(urlString).buildAndExpand("hot&cold");
httpUrl - the source URIpublic static UriComponentsBuilder fromHttpRequest(HttpRequest request)
UriComponents object from the URI associated with
the given HttpRequest while also overlaying with values from the headers
"Forwarded" (RFC 7239),
or "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if
"Forwarded" is not found.request - the source requestparseForwardedFor(HttpRequest, InetSocketAddress)@Nullable public static InetSocketAddress parseForwardedFor(HttpRequest request, @Nullable InetSocketAddress remoteAddress)
InetSocketAddress representing the address of the client.request - a request with headers that may contain forwarded headersremoteAddress - the current remoteAddressInetSocketAddress with the extracted host and port, or
null if the headers are not present.public static UriComponentsBuilder fromOriginHeader(String origin)
public final UriComponentsBuilder encode()
In comparison to UriComponents.encode(), this method has the
same effect on the URI template, i.e. each URI component is encoded by
replacing non-ASCII and illegal (within the URI component type) characters
with escaped octets. However URI variables are encoded more strictly, by
also escaping characters with reserved meaning.
For most cases, this method is more likely to give the expected result
because in treats URI variables as opaque data to be fully encoded, while
UriComponents.encode() is useful when intentionally expanding URI
variables that contain reserved characters.
For example ';' is legal in a path but has reserved meaning. This
method replaces ";" with "%3B" in URI variables but not in the URI
template. By contrast, UriComponents.encode() never replaces ";"
since it is a legal character in a path.
When not expanding URI variables at all, prefer use of
UriComponents.encode() since that will also encode anything that
incidentally looks like a URI variable.
public UriComponentsBuilder encode(Charset charset)
encode() with a charset other than "UTF-8".charset - the charset to use for encodingpublic UriComponents build()
UriComponents instance from the various components contained in this builder.public UriComponents build(boolean encoded)
build() to create a UriComponents instance
when components are already fully encoded. This is useful for example if
the builder was created via fromUri(URI).encoded - whether the components in this builder are already encodedIllegalArgumentException - if any of the components contain illegal
characters that should have been encoded.public UriComponents buildAndExpand(Map<String,?> uriVariables)
UriComponents instance and replaces URI template variables
with the values from a map. This is a shortcut method which combines
calls to build() and then UriComponents.expand(Map).uriVariables - the map of URI variablespublic UriComponents buildAndExpand(Object... uriVariableValues)
UriComponents instance and replaces URI template variables
with the values from an array. This is a shortcut method which combines
calls to build() and then UriComponents.expand(Object...).uriVariableValues - the URI variable valuespublic URI build(Object... uriVariables)
UriBuilderURI instance and replaces URI template variables
with the values from an array.build in interface UriBuilderuriVariables - the map of URI variablespublic URI build(Map<String,?> uriVariables)
UriBuilderURI instance and replaces URI template variables
with the values from a map.build in interface UriBuilderuriVariables - the map of URI variablespublic String toUriString()
Effectively, a shortcut for building, encoding, and returning the String representation:
String uri = builder.build().encode().toUriString()
However if URI variables have been provided
then the URI template is pre-encoded separately from URI variables (see
encode() for details), i.e. equivalent to:
String uri = builder.encode().build().toUriString()
UriComponents.toUriString()public UriComponentsBuilder uri(URI uri)
uri - the URIpublic UriComponentsBuilder uriComponents(UriComponents uriComponents)
UriComponents instance.
For the semantics of each component (i.e. set vs append) check the
builder methods on this class. For example host(String) sets
while path(String) appends.
uriComponents - the UriComponents to copy frompublic UriComponentsBuilder scheme(@Nullable String scheme)
UriBuildernull to clear the scheme of this builder.scheme in interface UriBuilderscheme - the URI schemepublic UriComponentsBuilder schemeSpecificPart(String ssp)
query.ssp - the URI scheme-specific-part, may contain URI template parameterspublic UriComponentsBuilder userInfo(@Nullable String userInfo)
UriBuildernull to clear the user info of this builder.userInfo in interface UriBuilderuserInfo - the URI user infopublic UriComponentsBuilder host(@Nullable String host)
UriBuildernull to clear the host of this builder.host in interface UriBuilderhost - the URI hostpublic UriComponentsBuilder port(int port)
UriBuilder-1 will clear the port of this builder.port in interface UriBuilderport - the URI portpublic UriComponentsBuilder port(@Nullable String port)
UriBuilderUriBuilder.port(int).
Passing null will clear the port of this builder.port in interface UriBuilderport - the URI portpublic UriComponentsBuilder path(String path)
UriBuilderThe 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
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 in interface UriBuilderpath - the URI pathpublic UriComponentsBuilder pathSegment(String... pathSegments) throws IllegalArgumentException
UriBuilder
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 UriBuilder.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.
pathSegment in interface UriBuilderpathSegments - the URI path segmentsIllegalArgumentExceptionpublic UriComponentsBuilder replacePath(@Nullable String path)
UriBuilderreplacePath in interface UriBuilderpath - the URI path, or null for an empty pathpublic UriComponentsBuilder query(@Nullable String query)
UriBuilder'&' and their values, if any, with '='.
The query may contain URI template variables.
Note: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
query in interface UriBuilderquery - the query stringpublic UriComponentsBuilder replaceQuery(@Nullable String query)
UriBuilderUriBuilder.query(String).
Note: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
replaceQuery in interface UriBuilderquery - the query string; a null value removes all query parameters.public UriComponentsBuilder queryParam(String name, Object... values)
UriBuilder"?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.
queryParam in interface UriBuildername - the query parameter namevalues - the query parameter valuesUriBuilder.queryParam(String, Collection)public UriComponentsBuilder queryParam(String name, @Nullable Collection<?> values)
UriBuilderUriBuilder.queryParam(String, Object...) with a Collection.
Note: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
queryParam in interface UriBuildername - the query parameter namevalues - the query parameter valuesUriBuilder.queryParam(String, Object...)public UriComponentsBuilder queryParamIfPresent(String name, Optional<?> value)
UriBuilderUriBuilder.queryParam(String, Object...) or
UriBuilder.queryParam(String, Collection) if the given Optional has
a value, or else if it is empty, no query parameter is added at all.queryParamIfPresent in interface UriBuildername - the query parameter namevalue - an Optional, either empty or holding the query parameter value.public UriComponentsBuilder queryParams(@Nullable MultiValueMap<String,String> params)
Note: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
queryParams in interface UriBuilderparams - the paramspublic UriComponentsBuilder replaceQueryParam(String name, Object... values)
UriBuilderNote: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
replaceQueryParam in interface UriBuildername - the query parameter namevalues - the query parameter valuesUriBuilder.replaceQueryParam(String, Collection)public UriComponentsBuilder replaceQueryParam(String name, @Nullable Collection<?> values)
UriBuilderUriBuilder.replaceQueryParam(String, Object...) with a Collection.
Note: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
replaceQueryParam in interface UriBuildername - the query parameter namevalues - the query parameter valuesUriBuilder.replaceQueryParam(String, Object...)public UriComponentsBuilder replaceQueryParams(@Nullable MultiValueMap<String,String> params)
Note: please, review the Javadoc of
UriBuilder.queryParam(String, Object...) for further notes on the treatment
and encoding of individual query parameters.
replaceQueryParams in interface UriBuilderparams - the query parameter namepublic UriComponentsBuilder fragment(@Nullable String fragment)
UriBuildernull to clear the fragment of this builder.fragment in interface UriBuilderfragment - the URI fragmentpublic UriComponentsBuilder uriVariables(Map<String,Object> uriVariables)
The provided variables may be a subset of all required ones. At build time, the available ones are expanded, while unresolved URI placeholders are left in place and can still be expanded later.
In contrast to UriComponents.expand(Map) or
buildAndExpand(Map), this method is useful when you need to
supply URI variables without building the UriComponents instance
just yet, or perhaps pre-expand some shared default values such as host
and port.
uriVariables - the URI variables to usepublic Object clone()
clone() method.
Delegates to cloneBuilder().public UriComponentsBuilder cloneBuilder()
UriComponentsBuilder.UriComponentsBuilder object