org.springframework.web.util

Class UriComponentsBuilder

java.lang.Object

org.springframework.web.util.UriComponentsBuilder

All Implemented Interfaces:

java.lang.Cloneable, UriBuilder

Direct Known Subclasses:

ServletUriComponentsBuilder

public class UriComponentsBuilder
extends java.lang.Object
implements UriBuilder, java.lang.Cloneable

Builder for UriComponents.

Typical usage involves:

1. Create a UriComponentsBuilder with one of the static factory methods (such as fromPath(String) or fromUri(URI))
2. 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).
3. Build the UriComponents instance with the build() method.

Since:

3.1

Author:

Arjen Poutsma, Rossen Stoyanchev, Phillip Webb, Oliver Gierke, Brian Clozel, Sebastien Deleuze

See Also:

newInstance(), fromPath(String), fromUri(URI)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	UriComponentsBuilder() Default constructor.
protected	UriComponentsBuilder(UriComponentsBuilder other) Create a deep copy of the given UriComponentsBuilder.

Method Summary

Modifier and Type	Method and Description
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	encode() Request to have the URI template pre-encoded at build time, and URI variables encoded separately when expanded.
UriComponentsBuilder	encode(java.nio.charset.Charset charset) A variant of encode() with a charset other than "UTF-8".
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.
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	uriVariables(java.util.Map<java.lang.String,java.lang.Object> uriVariables) Configure URI variables to be expanded at build time.
UriComponentsBuilder	userInfo(java.lang.String userInfo) Set the URI user info.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UriComponentsBuilder

protected UriComponentsBuilder()

Default constructor. Protected to prevent direct instantiation.

See Also:

newInstance(), fromPath(String), fromUri(URI)

UriComponentsBuilder

protected UriComponentsBuilder(UriComponentsBuilder other)

Create a deep copy of the given UriComponentsBuilder.

Parameters:

other - the other builder to copy from

Since:

4.1.3

Method Detail

newInstance

public static UriComponentsBuilder newInstance()

Create a new, empty builder.

Returns:

the new UriComponentsBuilder

fromPath

public static UriComponentsBuilder fromPath(java.lang.String path)

Create a builder that is initialized with the given path.

Parameters:

path - the path to initialize with

Returns:

the new UriComponentsBuilder

fromUri

public static UriComponentsBuilder fromUri(java.net.URI uri)

Create a builder that is initialized with the given URI.

Parameters:

uri - the URI to initialize with

Returns:

the new UriComponentsBuilder

fromUriString

public static UriComponentsBuilder fromUriString(java.lang.String uri)

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

public static UriComponentsBuilder fromHttpUrl(java.lang.String httpUrl)

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

public 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.

Parameters:

request - the source request

Returns:

the URI components of the URI

Since:

4.1.5

fromOriginHeader

public static UriComponentsBuilder fromOriginHeader(java.lang.String origin)

Create an instance by parsing the "Origin" header of an HTTP request.

See Also:

RFC 6454

encode

public final UriComponentsBuilder 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 only if 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.

Since:

5.0.8

encode

public UriComponentsBuilder encode(java.nio.charset.Charset charset)

A variant of encode() with a charset other than "UTF-8".

Parameters:

charset - the charset to use for encoding

Since:

5.0.8

build

public UriComponents build()

Build a UriComponents instance from the various components contained in this builder.

Returns:

the URI components

build

public UriComponents build(boolean encoded)

Build a UriComponents instance from the various components contained in this builder.

Parameters:

encoded - whether all the components set in this builder are encoded (true) or not (false)

Returns:

the URI components

buildAndExpand

public UriComponents buildAndExpand(java.util.Map<java.lang.String,?> uriVariables)

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).

Parameters:

uriVariables - the map of URI variables

Returns:

the URI components with expanded values

buildAndExpand

public UriComponents buildAndExpand(java.lang.Object... uriVariableValues)

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...).

Parameters:

uriVariableValues - the URI variable values

Returns:

the URI components with expanded values

build

public java.net.URI build(java.lang.Object... uriVariables)

Description copied from interface: UriBuilder

Build a URI instance and replaces URI template variables with the values from an array.

Specified by:

build in interface UriBuilder

Parameters:

uriVariables - the map of URI variables

Returns:

the URI

build

public java.net.URI build(java.util.Map<java.lang.String,?> uriVariables)

Description copied from interface: UriBuilder

Build a URI instance and replaces URI template variables with the values from a map.

Specified by:

build in interface UriBuilder

Parameters:

uriVariables - the map of URI variables

Returns:

the URI

toUriString

public java.lang.String toUriString()

Build a URI String. This is a shortcut method which combines calls to build(), then UriComponents.encode() and finally UriComponents.toUriString().

Since:

4.1

See Also:

UriComponents.toUriString()

uri

public UriComponentsBuilder uri(java.net.URI uri)

Initialize components of this builder from components of the given URI.

Parameters:

uri - the URI

Returns:

this UriComponentsBuilder

uriComponents

public UriComponentsBuilder uriComponents(UriComponents 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.

Parameters:

uriComponents - the UriComponents to copy from

Returns:

this UriComponentsBuilder

scheme

public UriComponentsBuilder scheme(@Nullable
                                   java.lang.String scheme)

Set the URI scheme. The given scheme 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

Returns:

this UriComponentsBuilder

schemeSpecificPart

public UriComponentsBuilder schemeSpecificPart(java.lang.String ssp)

Set the URI scheme-specific-part. When invoked, this method overwrites user-info, host, port, path, and query.

Parameters:

ssp - the URI scheme-specific-part, may contain URI template parameters

Returns:

this UriComponentsBuilder

userInfo

public UriComponentsBuilder userInfo(@Nullable
                                     java.lang.String userInfo)

Set the URI user info. The given user info 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

Returns:

this UriComponentsBuilder

host

public UriComponentsBuilder host(@Nullable
                                 java.lang.String host)

Set the URI host. The given host 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

Returns:

this UriComponentsBuilder

port

public UriComponentsBuilder port(int port)

Set the URI port. Passing -1 will clear the port of this builder.

Specified by:

port in interface UriBuilder

Parameters:

port - the URI port

Returns:

this UriComponentsBuilder

port

public UriComponentsBuilder port(@Nullable
                                 java.lang.String port)

Set the URI port. Use this method only when the port needs to be parameterized with a URI variable. Otherwise use port(int). Passing null will clear the port of this builder.

Specified by:

port in interface UriBuilder

Parameters:

port - the URI port

Returns:

this UriComponentsBuilder

path

public UriComponentsBuilder path(java.lang.String path)

Append the given path to the existing path of this builder. The given path may contain URI template variables.

Specified by:

path in interface UriBuilder

Parameters:

path - the URI path

Returns:

this UriComponentsBuilder

pathSegment

public UriComponentsBuilder pathSegment(java.lang.String... pathSegments)
                                 throws java.lang.IllegalArgumentException

Append path segments to the existing path. Each path segment may contain URI template variables and should not contain any slashes. Use path("/") subsequently to ensure a trailing slash.

Specified by:

pathSegment in interface UriBuilder

Parameters:

pathSegments - the URI path segments

Returns:

this UriComponentsBuilder

Throws:

java.lang.IllegalArgumentException

replacePath

public UriComponentsBuilder replacePath(@Nullable
                                        java.lang.String path)

Set the path of this builder overriding all existing path and path segment values.

Specified by:

replacePath in interface UriBuilder

Parameters:

path - the URI path (a null value results in an empty path)

Returns:

this UriComponentsBuilder

query

public UriComponentsBuilder query(@Nullable
                                  java.lang.String query)

Append the given query to the existing query of this builder. The given query may contain URI template variables.

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");
 

Specified by:

query in interface UriBuilder

Parameters:

query - the query string

Returns:

this UriComponentsBuilder

replaceQuery

public UriComponentsBuilder replaceQuery(@Nullable
                                         java.lang.String query)

Set the query of this builder overriding all existing query parameters.

Specified by:

replaceQuery in interface UriBuilder

Parameters:

query - the query string; a null value removes all query parameters.

Returns:

this UriComponentsBuilder

queryParam

public UriComponentsBuilder queryParam(java.lang.String name,
                                       java.lang.Object... values)

Append the given query parameter to the existing query parameters. The given name or any of the values may contain URI template variables. If no values are given, the resulting URI will contain the query parameter name only (i.e. ?foo instead of ?foo=bar).

Specified by:

queryParam in interface UriBuilder

Parameters:

name - the query parameter name

values - the query parameter values

Returns:

this UriComponentsBuilder

queryParams

public UriComponentsBuilder queryParams(@Nullable
                                        MultiValueMap<java.lang.String,java.lang.String> params)

Add the given query parameters.

Specified by:

queryParams in interface UriBuilder

Parameters:

params - the params

Returns:

this UriComponentsBuilder

Since:

4.0

replaceQueryParam

public UriComponentsBuilder replaceQueryParam(java.lang.String name,
                                              java.lang.Object... values)

Set the query parameter values overriding all existing query values for the same parameter. If no values are given, the query parameter is removed.

Specified by:

replaceQueryParam in interface UriBuilder

Parameters:

name - the query parameter name

values - the query parameter values

Returns:

this UriComponentsBuilder

replaceQueryParams

public UriComponentsBuilder replaceQueryParams(@Nullable
                                               MultiValueMap<java.lang.String,java.lang.String> params)

Set the query parameter values overriding all existing query values.

Specified by:

replaceQueryParams in interface UriBuilder

Parameters:

params - the query parameter name

Returns:

this UriComponentsBuilder

Since:

4.2

fragment

public UriComponentsBuilder fragment(@Nullable
                                     java.lang.String fragment)

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

Returns:

this UriComponentsBuilder

uriVariables

public UriComponentsBuilder uriVariables(java.util.Map<java.lang.String,java.lang.Object> 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.

Parameters:

uriVariables - the URI variables to use

Returns:

this UriComponentsBuilder

Since:

5.0.8

clone

public java.lang.Object clone()

Public declaration of Object's clone() method. Delegates to cloneBuilder().

Overrides:

clone in class java.lang.Object

cloneBuilder

public UriComponentsBuilder cloneBuilder()

Clone this UriComponentsBuilder.

Returns:

the cloned UriComponentsBuilder object

Since:

4.2.7