org.springframework.web.util

Interface UriBuilder

All Known Implementing Classes:

ServletUriComponentsBuilder, UriComponentsBuilder

public interface UriBuilder

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.

Since:

5.0

Author:

Rossen Stoyanchev

See Also:

UriBuilderFactory, UriComponentsBuilder

Method Summary

Modifier and Type	Method and Description
URI	build(Map<String,?> uriVariables) Build a URI instance and replaces URI template variables with the values from a map.
URI	build(Object... uriVariables) Build a URI instance and replaces URI template variables with the values from an array.
UriBuilder	fragment(String fragment) Set the URI fragment.
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.
UriBuilder	path(String path) Append the given path to the existing path of this builder.
UriBuilder	pathSegment(String... pathSegments) Append path segments to the existing path.
UriBuilder	port(int port) Set the URI port.
UriBuilder	port(String port) Set the URI port .
UriBuilder	query(String query) Parse the given query string into query parameters where parameters are separated with '&' and their values, if any, with '='.
UriBuilder	queryParam(String name, Collection<?> values) Variant of queryParam(String, Object...) with a Collection.
UriBuilder	queryParam(String name, Object... values) Append the given query parameter.
UriBuilder	queryParams(MultiValueMap<String,String> params) Add multiple query parameters and values.
UriBuilder	replacePath(String path) Set the path of this builder overriding the existing path values.
UriBuilder	replaceQuery(String query) Clear existing query parameters and then delegate to query(String).
UriBuilder	replaceQueryParam(String name, Collection<?> values) Variant of replaceQueryParam(String, Object...) with a Collection.
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.
UriBuilder	replaceQueryParams(MultiValueMap<String,String> params) Set the query parameter values after removing all existing ones.
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.
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.

Method Detail

scheme

UriBuilder scheme(@Nullable
                  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 - the URI scheme

userInfo

UriBuilder userInfo(@Nullable
                    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 - the URI user info

host

UriBuilder host(@Nullable
                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 - the URI host

port

UriBuilder port(int port)

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

Parameters:

port - the URI port

port

UriBuilder port(@Nullable
                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 - the URI port

path

UriBuilder path(String path)

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

Parameters:

path - the URI path

replacePath

UriBuilder replacePath(@Nullable
                       String path)

Set the path of this builder overriding the existing path values.

Parameters:

path - the URI path, or null for an empty path

pathSegment

UriBuilder pathSegment(String... pathSegments)
                throws 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.

Parameters:

pathSegments - the URI path segments

Throws:

IllegalArgumentException

query

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 - the query string

replaceQuery

UriBuilder replaceQuery(@Nullable
                        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 - the query string; a null value removes all query parameters.

queryParam

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 - the query parameter name

values - the query parameter values

See Also:

queryParam(String, Collection)

queryParam

UriBuilder queryParam(String name,
                      @Nullable
                      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 - the query parameter name

values - the query parameter values

Since:

5.2

See Also:

queryParam(String, Object...)

queryParams

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 - the params

replaceQueryParam

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 - the query parameter name

values - the query parameter values

See Also:

replaceQueryParam(String, Collection)

replaceQueryParam

UriBuilder replaceQueryParam(String name,
                             @Nullable
                             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 - the query parameter name

values - the query parameter values

Since:

5.2

See Also:

replaceQueryParam(String, Object...)

replaceQueryParams

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 - the query parameter name

fragment

UriBuilder fragment(@Nullable
                    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 - the URI fragment

build

URI build(Object... uriVariables)

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

Parameters:

uriVariables - the map of URI variables

Returns:

the URI

build

URI build(Map<String,?> uriVariables)

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

Parameters:

uriVariables - the map of URI variables

Returns:

the URI