Top Description Methods
org.springframework.web.util

public Interface UriBuilder

Known Direct Implementers
org.springframework.web.util.UriComponentsBuilder, org.springframework.web.util.DefaultUriBuilderFactory.DefaultUriBuilder
Imports
java.net.URI, java.util.Collection, .Map, .Optional, org.springframework.lang.Nullable, org.springframework.util.MultiValueMap
Builder-style methods to prepare and expand a URI template with variables.

Effectively a generalization of UriComponentsBuilder but with shortcuts to expand directly into URI rather than UriComponents and also leaving common concerns such as encoding preferences, a base URI, and others as implementation concerns.

Typically obtained via UriBuilderFactory which serves as a central component configured once and used to create many URLs.

Author
Rossen Stoyanchev
Since
5.0
See Also
UriBuilderFactory, UriComponentsBuilder

Method Summary

Modifier and TypeMethod and Description
public URI

Returns:

the URI
build(Object...
the map of URI variables
uriVariables)

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

public URI

Returns:

the URI
build(Map<String, ?>
the map of URI variables
uriVariables)

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

public UriBuilder
fragment(String
the URI fragment
fragment)

Set the URI fragment.

public UriBuilder
host(String
the URI host
host)

Set the URI host which may contain URI template variables, and may also be null to clear the host of this builder.

public UriBuilder
path(String
the URI path
path)

Append to the path of this builder.

public UriBuilder
pathSegment(String...
the URI path segments
pathSegments)

Append to the path using path segments.

public UriBuilder
port(int
the URI port
port)

Set the URI port.

public UriBuilder
port(String
the URI port
port)

Set the URI port.

public UriBuilder
query(String
the query string
query)

Parse the given query string into query parameters where parameters are separated with '&' and their values, if any, with '='.

public UriBuilder
queryParam(String
the query parameter name
name, Object...
the query parameter values
values)

Append the given query parameter.

public UriBuilder
queryParam(String
the query parameter name
name, Collection<?>
the query parameter values
values)

Variant of queryParam(String, Object...) with a Collection.

public UriBuilder
queryParamIfPresent(String
the query parameter name
name, Optional<?>
an Optional, either empty or holding the query parameter value.
value)

Delegates to either queryParam(String, Object...) or queryParam(String, Collection) if the given Optional has a value, or else if it is empty, no query parameter is added at all.

public UriBuilder
queryParams(MultiValueMap<String, String>
the params
params)

Add multiple query parameters and values.

public UriBuilder
replacePath(String
the URI path, or null for an empty path
path)

Override the current path.

public UriBuilder
replaceQuery(String
the query string; a null value removes all query parameters.
query)

Clear existing query parameters and then delegate to query(String).

public UriBuilder
replaceQueryParam(String
the query parameter name
name, Object...
the query parameter values
values)

Set the query parameter values replacing existing values, or if no values are given, the query parameter is removed.

public UriBuilder
replaceQueryParam(String
the query parameter name
name, Collection<?>
the query parameter values
values)

Variant of replaceQueryParam(String, Object...) with a Collection.

public UriBuilder
replaceQueryParams(MultiValueMap<String, String>
the query parameter name
params)

Set the query parameter values after removing all existing ones.

public UriBuilder
scheme(String
the URI scheme
scheme)

Set the URI scheme which may contain URI template variables, and may also be null to clear the scheme of this builder.

public String
toUriString()

Return a String representation of the URI by concatenating all URI component values into the fully formed URI String.

public UriBuilder
userInfo(String
the URI user info
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.

Method Detail

buildback to summary
public URI build(Object... uriVariables)

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

Parameters
uriVariables:Object[]

the map of URI variables

Returns:URI

the URI

buildback to summary
public URI build(Map<String, ?> uriVariables)

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

Parameters
uriVariables:Map<String, ?>

the map of URI variables

Returns:URI

the URI

fragmentback to summary
public UriBuilder fragment(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.

Parameters
fragment:String

the URI fragment

hostback to summary
public UriBuilder 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.

Parameters
host:String

the URI host

pathback to summary
public UriBuilder path(String path)

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 UriComponentsBuilder#encode(), or otherwise if building URIs indirectly via WebClient or RestTemplate, see its encodingMode. Also see the URI Encoding section of the reference docs.

Parameters
path:String

the URI path

pathSegmentback to summary
public UriBuilder pathSegment(String... pathSegments) throws IllegalArgumentException

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

Parameters
pathSegments:String[]

the URI path segments

portback to summary
public UriBuilder port(int port)

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

Parameters
port:int

the URI port

portback to summary
public UriBuilder port(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.

Parameters
port:String

the URI port

queryback to summary
public UriBuilder query(String query)

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 queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
query:String

the query string

queryParamback to summary
public UriBuilder queryParam(String name, Object... values)

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.

Parameters
name:String

the query parameter name

values:Object[]

the query parameter values

See Also
queryParam(String, Collection)
queryParamback to summary
public UriBuilder queryParam(String name, Collection<?> values)

Variant of queryParam(String, Object...) with a Collection.

Note

please, review the Javadoc of queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
name:String

the query parameter name

values:Collection<?>

the query parameter values

Since
5.2
See Also
queryParam(String, Object...)
queryParamIfPresentback to summary
public UriBuilder queryParamIfPresent(String name, Optional<?> value)

Delegates to either queryParam(String, Object...) or queryParam(String, Collection) if the given Optional has a value, or else if it is empty, no query parameter is added at all.

Parameters
name:String

the query parameter name

value:Optional<?>

an Optional, either empty or holding the query parameter value.

Since
5.3
queryParamsback to summary
public UriBuilder queryParams(MultiValueMap<String, String> params)

Add multiple query parameters and values.

Note

please, review the Javadoc of queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
params:MultiValueMap<String, String>

the params

replacePathback to summary
public UriBuilder replacePath(String path)

Override the current path.

Parameters
path:String

the URI path, or null for an empty path

replaceQueryback to summary
public UriBuilder replaceQuery(String query)

Clear existing query parameters and then delegate to query(String).

Note

please, review the Javadoc of queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
query:String

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

replaceQueryParamback to summary
public UriBuilder replaceQueryParam(String name, Object... values)

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 queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
name:String

the query parameter name

values:Object[]

the query parameter values

See Also
replaceQueryParam(String, Collection)
replaceQueryParamback to summary
public UriBuilder replaceQueryParam(String name, Collection<?> values)

Variant of replaceQueryParam(String, Object...) with a Collection.

Note

please, review the Javadoc of queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
name:String

the query parameter name

values:Collection<?>

the query parameter values

Since
5.2
See Also
replaceQueryParam(String, Object...)
replaceQueryParamsback to summary
public UriBuilder replaceQueryParams(MultiValueMap<String, String> params)

Set the query parameter values after removing all existing ones.

Note

please, review the Javadoc of queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.

Parameters
params:MultiValueMap<String, String>

the query parameter name

schemeback to summary
public UriBuilder 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.

Parameters
scheme:String

the URI scheme

toUriStringback to summary
public String toUriString()

Return a String representation of the URI by concatenating all URI component values into the fully formed URI String. Implementing classes should perform simple String concatenation of current URI component values to preserve URI template placeholders.

Since
6.1.2
userInfoback to summary
public UriBuilder 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.

Parameters
userInfo:String

the URI user info