public class UriComponentsBuilder extends java.lang.Object implements UriBuilder, java.lang.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 and Type | Class and Description |
---|---|
private static class |
UriComponentsBuilder.CompositePathComponentBuilder |
private static class |
UriComponentsBuilder.FullPathComponentBuilder |
private static interface |
UriComponentsBuilder.PathComponentBuilder |
private static class |
UriComponentsBuilder.PathSegmentComponentBuilder |
Modifier and Type | Field and Description |
---|---|
private static java.util.regex.Pattern |
FORWARDED_HOST_PATTERN |
private static java.util.regex.Pattern |
FORWARDED_PROTO_PATTERN |
private java.lang.String |
fragment |
private java.lang.String |
host |
private static java.lang.String |
HOST_IPV4_PATTERN |
private static java.lang.String |
HOST_IPV6_PATTERN |
private static java.lang.String |
HOST_PATTERN |
private static java.lang.String |
HTTP_PATTERN |
private static java.util.regex.Pattern |
HTTP_URL_PATTERN |
private static java.lang.String |
LAST_PATTERN |
private static java.lang.String |
PATH_PATTERN |
private UriComponentsBuilder.CompositePathComponentBuilder |
pathBuilder |
private java.lang.String |
port |
private static java.lang.String |
PORT_PATTERN |
private static java.util.regex.Pattern |
QUERY_PARAM_PATTERN |
private static java.lang.String |
QUERY_PATTERN |
private MultiValueMap<java.lang.String,java.lang.String> |
queryParams |
private java.lang.String |
scheme |
private static java.lang.String |
SCHEME_PATTERN |
private java.lang.String |
ssp |
private static java.util.regex.Pattern |
URI_PATTERN |
private java.lang.String |
userInfo |
private static java.lang.String |
USERINFO_PATTERN |
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 |
---|---|
private void |
adaptForwardedHost(java.lang.String hostToUse) |
(package private) UriComponentsBuilder |
adaptFromForwardedHeaders(HttpHeaders headers)
Adapt this builder's scheme+host+port from the given headers, specifically
"Forwarded" (RFC 7239,
or "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if
"Forwarded" is not found.
|
UriComponents |
build()
Build a
UriComponents instance from the various components contained in this builder. |
UriComponents |
build(boolean encoded)
Build a
UriComponents instance from the various components
contained in this builder. |
java.net.URI |
build(java.util.Map<java.lang.String,?> uriVariables)
Build a
URI instance and replaces URI template variables
with the values from a map. |
java.net.URI |
build(java.lang.Object... uriVariables)
Build a
URI instance and replaces URI template variables
with the values from an array. |
UriComponents |
buildAndExpand(java.util.Map<java.lang.String,?> uriVariables)
Build a
UriComponents instance and replaces URI template variables
with the values from a map. |
UriComponents |
buildAndExpand(java.lang.Object... uriVariableValues)
Build a
UriComponents instance and replaces URI template variables
with the values from an array. |
java.lang.Object |
clone()
Public declaration of Object's
clone() method. |
UriComponentsBuilder |
cloneBuilder()
Clone this
UriComponentsBuilder . |
UriComponentsBuilder |
fragment(java.lang.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(java.lang.String httpUrl)
Create a URI components builder from the given HTTP URL String.
|
static UriComponentsBuilder |
fromOriginHeader(java.lang.String origin)
Create an instance by parsing the "Origin" header of an HTTP request.
|
static UriComponentsBuilder |
fromPath(java.lang.String path)
Create a builder that is initialized with the given path.
|
static UriComponentsBuilder |
fromUri(java.net.URI uri)
Create a builder that is initialized with the given
URI . |
static UriComponentsBuilder |
fromUriString(java.lang.String uri)
Create a builder that is initialized with the given URI string.
|
UriComponentsBuilder |
host(java.lang.String host)
Set the URI host.
|
static UriComponentsBuilder |
newInstance()
Create a new, empty builder.
|
UriComponentsBuilder |
path(java.lang.String path)
Append the given path to the existing path of this builder.
|
UriComponentsBuilder |
pathSegment(java.lang.String... pathSegments)
Append path segments to the existing path.
|
UriComponentsBuilder |
port(int port)
Set the URI port.
|
UriComponentsBuilder |
port(java.lang.String port)
Set the URI port.
|
UriComponentsBuilder |
query(java.lang.String query)
Append the given query to the existing query of this builder.
|
UriComponentsBuilder |
queryParam(java.lang.String name,
java.lang.Object... values)
Append the given query parameter to the existing query parameters.
|
UriComponentsBuilder |
queryParams(MultiValueMap<java.lang.String,java.lang.String> params)
Add the given query parameters.
|
UriComponentsBuilder |
replacePath(java.lang.String path)
Set the path of this builder overriding all existing path and path segment values.
|
UriComponentsBuilder |
replaceQuery(java.lang.String query)
Set the query of this builder overriding all existing query parameters.
|
UriComponentsBuilder |
replaceQueryParam(java.lang.String name,
java.lang.Object... values)
Set the query parameter values overriding all existing query values for
the same parameter.
|
UriComponentsBuilder |
replaceQueryParams(MultiValueMap<java.lang.String,java.lang.String> params)
Set the query parameter values overriding all existing query values.
|
private void |
resetHierarchicalComponents() |
private void |
resetSchemeSpecificPart() |
UriComponentsBuilder |
scheme(java.lang.String scheme)
Set the URI scheme.
|
UriComponentsBuilder |
schemeSpecificPart(java.lang.String ssp)
Set the URI scheme-specific-part.
|
java.lang.String |
toUriString()
Build a URI String.
|
UriComponentsBuilder |
uri(java.net.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(java.lang.String userInfo)
Set the URI user info.
|
private static final java.util.regex.Pattern QUERY_PARAM_PATTERN
private static final java.lang.String SCHEME_PATTERN
private static final java.lang.String HTTP_PATTERN
private static final java.lang.String USERINFO_PATTERN
private static final java.lang.String HOST_IPV4_PATTERN
private static final java.lang.String HOST_IPV6_PATTERN
private static final java.lang.String HOST_PATTERN
private static final java.lang.String PORT_PATTERN
private static final java.lang.String PATH_PATTERN
private static final java.lang.String QUERY_PATTERN
private static final java.lang.String LAST_PATTERN
private static final java.util.regex.Pattern URI_PATTERN
private static final java.util.regex.Pattern HTTP_URL_PATTERN
private static final java.util.regex.Pattern FORWARDED_HOST_PATTERN
private static final java.util.regex.Pattern FORWARDED_PROTO_PATTERN
@Nullable private java.lang.String scheme
@Nullable private java.lang.String ssp
@Nullable private java.lang.String userInfo
@Nullable private java.lang.String host
@Nullable private java.lang.String port
private UriComponentsBuilder.CompositePathComponentBuilder pathBuilder
private final MultiValueMap<java.lang.String,java.lang.String> queryParams
@Nullable private java.lang.String fragment
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(java.lang.String path)
path
- the path to initialize withUriComponentsBuilder
public static UriComponentsBuilder fromUri(java.net.URI uri)
URI
.uri
- the URI to initialize withUriComponentsBuilder
public static UriComponentsBuilder fromUriString(java.lang.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(java.lang.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 requestpublic static UriComponentsBuilder fromOriginHeader(java.lang.String origin)
public UriComponents build()
UriComponents
instance from the various components contained in this builder.public UriComponents build(boolean encoded)
UriComponents
instance from the various components
contained in this builder.encoded
- whether all the components set in this builder are
encoded (true
) or not (false
)public UriComponents buildAndExpand(java.util.Map<java.lang.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(java.lang.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 java.net.URI build(java.lang.Object... uriVariables)
URI
instance and replaces URI template variables
with the values from an array.build
in interface UriBuilder
uriVariables
- the map of URI variablespublic java.net.URI build(java.util.Map<java.lang.String,?> uriVariables)
URI
instance and replaces URI template variables
with the values from a map.build
in interface UriBuilder
uriVariables
- the map of URI variablespublic java.lang.String toUriString()
build()
, then UriComponents.encode()
and finally
UriComponents.toUriString()
.UriComponents.toUriString()
public UriComponentsBuilder uri(java.net.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 java.lang.String scheme)
null
to clear the scheme of this builder.scheme
in interface UriBuilder
scheme
- the URI schemepublic UriComponentsBuilder schemeSpecificPart(java.lang.String ssp)
query
.ssp
- the URI scheme-specific-part, may contain URI template parameterspublic UriComponentsBuilder userInfo(@Nullable java.lang.String userInfo)
null
to clear the user info of this builder.userInfo
in interface UriBuilder
userInfo
- the URI user infopublic UriComponentsBuilder host(@Nullable java.lang.String host)
null
to clear the host of this builder.host
in interface UriBuilder
host
- the URI hostpublic UriComponentsBuilder port(int port)
-1
will clear the port of this builder.port
in interface UriBuilder
port
- the URI portpublic UriComponentsBuilder port(@Nullable java.lang.String port)
port(int)
.
Passing null
will clear the port of this builder.port
in interface UriBuilder
port
- the URI portpublic UriComponentsBuilder path(java.lang.String path)
path
in interface UriBuilder
path
- the URI pathpublic UriComponentsBuilder pathSegment(java.lang.String... pathSegments) throws java.lang.IllegalArgumentException
path("/")
subsequently to ensure a trailing slash.pathSegment
in interface UriBuilder
pathSegments
- the URI path segmentsjava.lang.IllegalArgumentException
public UriComponentsBuilder replacePath(@Nullable java.lang.String path)
replacePath
in interface UriBuilder
path
- the URI path (a null
value results in an empty path)public UriComponentsBuilder query(@Nullable java.lang.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
in interface UriBuilder
query
- the query stringpublic UriComponentsBuilder replaceQuery(@Nullable java.lang.String query)
replaceQuery
in interface UriBuilder
query
- the query string; a null
value removes all query parameters.public UriComponentsBuilder queryParam(java.lang.String name, java.lang.Object... values)
?foo
instead of ?foo=bar
).queryParam
in interface UriBuilder
name
- the query parameter namevalues
- the query parameter valuespublic UriComponentsBuilder queryParams(@Nullable MultiValueMap<java.lang.String,java.lang.String> params)
queryParams
in interface UriBuilder
params
- the paramspublic UriComponentsBuilder replaceQueryParam(java.lang.String name, java.lang.Object... values)
replaceQueryParam
in interface UriBuilder
name
- the query parameter namevalues
- the query parameter valuespublic UriComponentsBuilder replaceQueryParams(@Nullable MultiValueMap<java.lang.String,java.lang.String> params)
replaceQueryParams
in interface UriBuilder
params
- the query parameter namepublic UriComponentsBuilder fragment(@Nullable java.lang.String fragment)
null
to clear the fragment of this builder.fragment
in interface UriBuilder
fragment
- the URI fragmentUriComponentsBuilder adaptFromForwardedHeaders(HttpHeaders headers)
headers
- the HTTP headers to considerprivate void adaptForwardedHost(java.lang.String hostToUse)
private void resetHierarchicalComponents()
private void resetSchemeSpecificPart()
public java.lang.Object clone()
clone()
method.
Delegates to cloneBuilder()
.clone
in class java.lang.Object
public UriComponentsBuilder cloneBuilder()
UriComponentsBuilder
.UriComponentsBuilder
object