Typical usage involves:
Create a
UriComponentsBuilder
with one of the static factory methods
(such as
fromPath(String)
or
fromUri(URI)
)
Set the various URI components through the respective methods (
scheme(String)
,
userInfo(String)
,
host(String)
,
port(int)
,
path(String)
,
pathSegment(String...)
,
queryParam(String, Object...)
, and
fragment(String)
.
Build the
UriComponents
instance with the
build()
method.
Since:
Author:
Arjen Poutsma, Rossen Stoyanchev, Phillip Webb, Oliver Gierke, Brian Clozel, Sebastien Deleuze, Sam Brannen
See Also:
newInstance()
fromPath(String)
fromUri(URI)
Build a
UriComponents
instance from the various components contained in this builder.
Build a
URI
instance and replaces URI template variables
with the values from an array.
Build a
URI
instance and replaces URI template variables
with the values from a map.
Build a
UriComponents
instance and replaces URI template variables
with the values from an array.
Build a
UriComponents
instance and replaces URI template variables
with the values from a map.
Public declaration of Object's
clone()
method.
Clone this
UriComponentsBuilder
.
Request to have the URI template pre-encoded at build time, and
URI variables encoded separately when expanded.
A variant of
encode()
with a charset other than "UTF-8".
Set the URI fragment.
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.
Create a URI components builder from the given HTTP URL String.
Create an instance by parsing the "Origin" header of an HTTP request.
Create a builder that is initialized with the given path.
Create a builder that is initialized from the given
URI
.
Create a builder that is initialized with the given URI string.
Set the URI host which may contain URI template variables, and may also
be
null
to clear the host of this builder.
Create a new, empty builder.
Parse the first "Forwarded: for=..." or "X-Forwarded-For" header value to
an
InetSocketAddress
representing the address of the client.
Append to the path of this builder.
Append to the path using path segments.
Set the URI port.
Set the URI port.
Parse the given query string into query parameters where parameters are
separated with
'&'
and their values, if any, with
'='
.
Append the given query parameter.
Add multiple query parameters and values.
Override the current path.
Set the query parameter values replacing existing values, or if no
values are given, the query parameter is removed.
Set the query parameter values after removing all existing ones.
Set the URI scheme which may contain URI template variables,
and may also be
null
to clear the scheme of this builder.
Set the URI scheme-specific-part.
Build a URI String.
Initialize components of this builder from components of the given URI.
Set or append individual URI components of this builder from the values
of the given
UriComponents
instance.
Configure URI variables to be expanded at build time.
Set the URI user info which may contain URI template variables, and
may also be
null
to clear the user info of this builder.
UriComponentsBuilder
protected
UriComponentsBuilder
()
Default constructor. Protected to prevent direct instantiation.
See Also:
newInstance()
fromPath(String)
fromUri(URI)
UriComponentsBuilder
Create a deep copy of the given UriComponentsBuilder.
Parameters:
other
- the other builder to copy from
Since:
4.1.3
newInstance
Create a new, empty builder.
Returns:
the new
UriComponentsBuilder
fromPath
Create a builder that is initialized with the given path.
Parameters:
path
- the path to initialize with
Returns:
the new
UriComponentsBuilder
fromUri
Create a builder that is initialized from the given
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 with
Returns:
the new
UriComponentsBuilder
fromUriString
Create a builder that is initialized with the given URI string.
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");
Parameters:
uri - the URI string to initialize with
Returns:
the new UriComponentsBuilder
fromHttpUrl
Create a URI components builder from the given HTTP URL String.
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");
Parameters:
httpUrl - the source URI
Returns:
the URI components of the URI
fromHttpRequest
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.
request - the source request
Returns:
the URI components of the URI
Since:
4.1.5
See Also:
parseForwardedFor(HttpRequest, InetSocketAddress)
parseForwardedFor
Parse the first "Forwarded: for=..." or "X-Forwarded-For" header value to
an InetSocketAddress representing the address of the client.
Parameters:
request - a request with headers that may contain forwarded headers
remoteAddress - the current remoteAddress
Returns:
an InetSocketAddress with the extracted host and port, or
null if the headers are not present.
Since:
See Also:
RFC 7239, Section 5.2
fromOriginHeader
Create an instance by parsing the "Origin" header of an HTTP request.
See Also:
RFC 6454
encode
Request to have the URI template pre-encoded at build time, and
URI variables encoded separately when expanded.
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.
encode
A variant of
encode() with a charset other than "UTF-8".
charset - the charset to use for encoding
Since:
5.0.8
build
Build a UriComponents instance from the various components contained in this builder.
Returns:
the URI components
build
Variant of
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 encoded
Returns:
the URI components
Throws:
IllegalArgumentException - if any of the components contain illegal
characters that should have been encoded.
buildAndExpand
Build a
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 variables
Returns:
the URI components with expanded values
buildAndExpand
Build a
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 values
Returns:
the URI components with expanded values
build
Build a
URI instance and replaces URI template variables
with the values from an array.
build in interface UriBuilder
Parameters:
uriVariables - the map of URI variables
Returns:
the URI
build
Build a
URI instance and replaces URI template variables
with the values from a map.
build in interface UriBuilder
Parameters:
uriVariables - the map of URI variables
Returns:
the URI
Build a URI String.
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()
Since:
See Also:
UriComponents.toUriString()
Initialize components of this builder from components of the given URI.
Parameters:
uri - the URI
Returns:
this UriComponentsBuilder
uriComponents
Set or append individual URI components of this builder from the values
of the given
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 from
Returns:
this UriComponentsBuilder
Set the URI scheme which may contain URI template variables,
and may also be null to clear the scheme of this builder.
Specified by:
scheme in interface UriBuilder
Parameters:
scheme - the URI scheme
schemeSpecificPart
Parameters:
ssp - the URI scheme-specific-part, may contain URI template parameters
Returns:
this UriComponentsBuilder
Set the URI user info which may contain URI template variables, and
may also be null to clear the user info of this builder.
Specified by:
userInfo in interface UriBuilder
Parameters:
userInfo - the URI user info
Set the URI host which may contain URI template variables, and may also
be null to clear the host of this builder.
Specified by:
host in interface UriBuilder
Parameters:
host - the URI host
Set the URI port. Passing -1 will clear the port of this builder.
Specified by:
port in interface UriBuilder
Parameters:
port - the URI port
Set the URI port. Use this method only when the port needs to be
parameterized with a URI variable. Otherwise use
UriBuilder.port(int).
Passing
null will clear the port of this builder.
port in interface UriBuilder
Parameters:
port - the URI port
Append to the path of this builder.
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
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 UriBuilder
Parameters:
path - the URI path
pathSegment
Append to the path using path segments. For example:
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 UriBuilder
Parameters:
pathSegments - the URI path segments
Throws:
IllegalArgumentException
Override the current path.
Specified by:
replacePath in interface UriBuilder
Parameters:
path - the URI path, or null for an empty path
Parse the given query string into query parameters where parameters are
separated with
'&' 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 UriBuilder
Parameters:
query - the query string
Specified by:
replaceQuery in interface UriBuilder
Parameters:
query - the query string; a null value removes all query parameters.
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, e.g.
"?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 UriBuilder
Parameters:
name - the query parameter name
values - the query parameter values
See Also:
UriBuilder.queryParam(String, Collection)
Collection<?> values)
queryParam in interface UriBuilder
Parameters:
name - the query parameter name
values - the query parameter values
See Also:
UriBuilder.queryParam(String, Object...)
queryParamIfPresent
Specified by:
queryParamIfPresent in interface UriBuilder
Parameters:
name - the query parameter name
value - an Optional, either empty or holding the query parameter value.
queryParams
Specified by:
queryParams in interface UriBuilder
Parameters:
params - the params
Since:
replaceQueryParam
Set the query parameter values replacing existing values, or if no
values are given, the query parameter is removed.
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 UriBuilder
Parameters:
name - the query parameter name
values - the query parameter values
See Also:
UriBuilder.replaceQueryParam(String, Collection)
replaceQueryParam
Specified by:
replaceQueryParam in interface UriBuilder
Parameters:
name - the query parameter name
values - the query parameter values
See Also:
UriBuilder.replaceQueryParam(String, Object...)
replaceQueryParams
Set the query parameter values after removing all existing ones.
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 UriBuilder
Parameters:
params - the query parameter name
Since:
Set the URI fragment. The given fragment may contain URI template variables,
and may also be null to clear the fragment of this builder.
Specified by:
fragment in interface UriBuilder
Parameters:
fragment - the URI fragment
uriVariables
Configure URI variables to be expanded at build time.
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 use
Returns:
this UriComponentsBuilder
Since:
5.0.8
Public declaration of Object's
clone() method.
Delegates to
cloneBuilder().
clone in class Object
cloneBuilder
Clone this UriComponentsBuilder.
Returns:
the cloned UriComponentsBuilder object
Since:
4.2.7
