public class UriComponentsBuilder extends Object implements 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. |
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 |
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.
|
static UriComponentsBuilder |
newInstance()
Create a new, empty builder.
|
UriComponentsBuilder |
path(String path)
Append the given path to the existing path of this builder.
|
UriComponentsBuilder |
pathSegment(String... pathSegments)
Append path segments to the existing path.
|
UriComponentsBuilder |
port(int port)
Set the URI port.
|
UriComponentsBuilder |
port(String port)
Set the URI port.
|
UriComponentsBuilder |
query(String query)
Append the given query to the existing query of this builder.
|
UriComponentsBuilder |
queryParam(String name,
Object... values)
Append the given query parameter to the existing query parameters.
|
UriComponentsBuilder |
queryParams(MultiValueMap<String,String> params)
Add the given query parameters.
|
UriComponentsBuilder |
replacePath(String path)
Set the path of this builder overriding all existing path and path segment values.
|
UriComponentsBuilder |
replaceQuery(String query)
Set the query of this builder overriding all existing query parameters.
|
UriComponentsBuilder |
replaceQueryParam(String name,
Object... values)
Set the query parameter values overriding all existing query values for
the same parameter.
|
UriComponentsBuilder |
replaceQueryParams(MultiValueMap<String,String> params)
Set the query parameter values overriding all existing query values.
|
UriComponentsBuilder |
scheme(String scheme)
Set the URI scheme.
|
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 |
userInfo(String userInfo)
Set the URI user info.
|
protected UriComponentsBuilder()
newInstance()
,
fromPath(String)
,
fromUri(URI)
protected UriComponentsBuilder(UriComponentsBuilder other)
other
- the other builder to copy frompublic static UriComponentsBuilder newInstance()
UriComponentsBuilder
public static UriComponentsBuilder fromPath(String path)
path
- the path to initialize withUriComponentsBuilder
public 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 withUriComponentsBuilder
public 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 withUriComponentsBuilder
public 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.
Note: this method uses values from forwarded headers,
if present, in order to reflect the client-originated protocol and address.
Consider using the ForwardedHeaderFilter
in order to choose from a
central place whether to extract and use, or to discard such headers.
See the Spring Framework reference for more on this filter.
request
- the source requestpublic static UriComponentsBuilder fromOriginHeader(String origin)
public 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
- URI variable valuespublic String toUriString()
build()
, then UriComponents.encode()
and finally
UriComponents.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(String scheme)
null
to clear the scheme of this builder.scheme
- the URI schemepublic UriComponentsBuilder schemeSpecificPart(String ssp)
query
.ssp
- the URI scheme-specific-part, may contain URI template parameterspublic UriComponentsBuilder userInfo(String userInfo)
null
to clear the user info of this builder.userInfo
- the URI user infopublic UriComponentsBuilder host(String host)
null
to clear the host of this builder.host
- the URI hostpublic UriComponentsBuilder port(int port)
-1
will clear the port of this builder.port
- the URI portpublic UriComponentsBuilder port(String port)
port(int)
.
Passing null
will clear the port of this builder.port
- the URI portpublic UriComponentsBuilder path(String path)
path
- the URI pathpublic UriComponentsBuilder pathSegment(String... pathSegments) throws IllegalArgumentException
path("/")
subsequently to ensure a trailing slash.pathSegments
- the URI path segmentsIllegalArgumentException
public UriComponentsBuilder replacePath(String path)
path
- the URI path (a null
value results in an empty path)public UriComponentsBuilder query(String query)
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:
UriComponentsBuilder.fromUriString("/hotels/42") .query("filter={value}") .buildAndExpand("hot&cold");
query
- the query stringpublic UriComponentsBuilder replaceQuery(String query)
query
- the query string; a null
value removes all query parameters.public UriComponentsBuilder queryParam(String name, Object... values)
?foo
instead of ?foo=bar
).name
- the query parameter namevalues
- the query parameter valuespublic UriComponentsBuilder queryParams(MultiValueMap<String,String> params)
params
- the paramspublic UriComponentsBuilder replaceQueryParam(String name, Object... values)
name
- the query parameter namevalues
- the query parameter valuespublic UriComponentsBuilder replaceQueryParams(MultiValueMap<String,String> params)
params
- the query parameter namepublic UriComponentsBuilder fragment(String fragment)
null
to clear the fragment of this builder.fragment
- the URI fragmentpublic Object clone()
clone()
method.
Delegates to cloneBuilder()
.public UriComponentsBuilder cloneBuilder()
UriComponentsBuilder
.UriComponentsBuilder
object