org.springframework.web.util

Class UriComponentsBuilder

java.lang.Object

org.springframework.web.util.UriComponentsBuilder

Direct Known Subclasses:

ServletUriComponentsBuilder

public class UriComponentsBuilder
extends java.lang.Object

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

See Also:

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

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	fragment
private java.lang.String	host
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 int	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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	UriComponentsBuilder() Default constructor.

Method Summary

Modifier and Type	Method and Description
UriComponents	build() Builds a UriComponents instance from the various components contained in this builder.
UriComponents	build(boolean encoded) Builds a UriComponents instance from the various components contained in this builder.
UriComponents	buildAndExpand(java.util.Map<java.lang.String,?> uriVariables) Builds a UriComponents instance and replaces URI template variables with the values from a map.
UriComponents	buildAndExpand(java.lang.Object... uriVariableValues) Builds a UriComponents instance and replaces URI template variables with the values from an array.
UriComponentsBuilder	fragment(java.lang.String fragment) Sets the URI fragment.
static UriComponentsBuilder	fromHttpUrl(java.lang.String httpUrl) Creates a new UriComponents object from the string HTTP URL.
static UriComponentsBuilder	fromPath(java.lang.String path) Returns a builder that is initialized with the given path.
static UriComponentsBuilder	fromUri(java.net.URI uri) Returns a builder that is initialized with the given URI.
static UriComponentsBuilder	fromUriString(java.lang.String uri) Returns a builder that is initialized with the given URI string.
UriComponentsBuilder	host(java.lang.String host) Sets the URI host.
static UriComponentsBuilder	newInstance() Returns a new, empty builder.
UriComponentsBuilder	path(java.lang.String path) Appends the given path to the existing path of this builder.
UriComponentsBuilder	pathSegment(java.lang.String... pathSegments) Appends the given path segments to the existing path of this builder.
UriComponentsBuilder	port(int port) Sets the URI port.
UriComponentsBuilder	query(java.lang.String query) Appends the given query to the existing query of this builder.
UriComponentsBuilder	queryParam(java.lang.String name, java.lang.Object... values) Appends the given query parameter to the existing query parameters.
UriComponentsBuilder	replacePath(java.lang.String path) Sets the path of this builder overriding all existing path and path segment values.
UriComponentsBuilder	replaceQuery(java.lang.String query) Sets the query of this builder overriding all existing query parameters.
UriComponentsBuilder	replaceQueryParam(java.lang.String name, java.lang.Object... values) Sets the query parameter values overriding all existing query values for the same parameter.
private void	resetHierarchicalComponents()
private void	resetSchemeSpecificPart()
UriComponentsBuilder	scheme(java.lang.String scheme) Sets the URI scheme.
UriComponentsBuilder	schemeSpecificPart(java.lang.String ssp) Set the URI scheme-specific-part.
UriComponentsBuilder	uri(java.net.URI uri) Initializes all components of this URI builder with the components of the given URI.
UriComponentsBuilder	userInfo(java.lang.String userInfo) Sets the URI user info.

Methods inherited from class java.lang.Object

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

Field Detail

QUERY_PARAM_PATTERN

private static final java.util.regex.Pattern QUERY_PARAM_PATTERN

SCHEME_PATTERN

private static final java.lang.String SCHEME_PATTERN

See Also:

Constant Field Values

HTTP_PATTERN

private static final java.lang.String HTTP_PATTERN

See Also:

Constant Field Values

USERINFO_PATTERN

private static final java.lang.String USERINFO_PATTERN

See Also:

Constant Field Values

HOST_PATTERN

private static final java.lang.String HOST_PATTERN

See Also:

Constant Field Values

PORT_PATTERN

private static final java.lang.String PORT_PATTERN

See Also:

Constant Field Values

PATH_PATTERN

private static final java.lang.String PATH_PATTERN

See Also:

Constant Field Values

QUERY_PATTERN

private static final java.lang.String QUERY_PATTERN

See Also:

Constant Field Values

LAST_PATTERN

private static final java.lang.String LAST_PATTERN

See Also:

Constant Field Values

URI_PATTERN

private static final java.util.regex.Pattern URI_PATTERN

HTTP_URL_PATTERN

private static final java.util.regex.Pattern HTTP_URL_PATTERN

scheme

private java.lang.String scheme

ssp

private java.lang.String ssp

userInfo

private java.lang.String userInfo

host

private java.lang.String host

port

private int port

pathBuilder

private UriComponentsBuilder.CompositePathComponentBuilder pathBuilder

queryParams

private final MultiValueMap<java.lang.String,java.lang.String> queryParams

fragment

private java.lang.String fragment

Constructor Detail

UriComponentsBuilder

protected UriComponentsBuilder()

Default constructor. Protected to prevent direct instantiation.

See Also:

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

Method Detail

newInstance

public static UriComponentsBuilder newInstance()

Returns a new, empty builder.

Returns:

the new UriComponentsBuilder

fromPath

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

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

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

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

Creates a new UriComponents object from the string HTTP URL.

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:

httpUrl - the source URI

Returns:

the URI components of the URI

build

public UriComponents build()

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

Returns:

the URI components

build

public UriComponents build(boolean encoded)

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

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

Builds 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 - URI variable values

Returns:

the URI components with expanded values

uri

public UriComponentsBuilder uri(java.net.URI uri)

Initializes all components of this URI builder with the components of the given URI.

Parameters:

uri - the URI

Returns:

this UriComponentsBuilder

resetHierarchicalComponents

private void resetHierarchicalComponents()

resetSchemeSpecificPart

private void resetSchemeSpecificPart()

scheme

public UriComponentsBuilder scheme(java.lang.String scheme)

Sets the URI scheme. The given scheme may contain URI template variables, and may also be null to clear the scheme of this builder.

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(java.lang.String userInfo)

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

Parameters:

userInfo - the URI user info

Returns:

this UriComponentsBuilder

host

public UriComponentsBuilder host(java.lang.String host)

Sets the URI host. The given host may contain URI template variables, and may also be null to clear the host of this builder.

Parameters:

host - the URI host

Returns:

this UriComponentsBuilder

port

public UriComponentsBuilder port(int port)

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

Parameters:

port - the URI port

Returns:

this UriComponentsBuilder

path

public UriComponentsBuilder path(java.lang.String path)

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

Parameters:

path - the URI path

Returns:

this UriComponentsBuilder

replacePath

public UriComponentsBuilder replacePath(java.lang.String path)

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

Parameters:

path - the URI path; a null value results in an empty path.

Returns:

this UriComponentsBuilder

pathSegment

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

Appends the given path segments to the existing path of this builder. Each given path segments may contain URI template variables.

Parameters:

pathSegments - the URI path segments

Returns:

this UriComponentsBuilder

Throws:

java.lang.IllegalArgumentException

query

public UriComponentsBuilder query(java.lang.String query)

Appends 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:

 String uriString = "/hotels/42?filter={value}";
 UriComponentsBuilder.fromUriString(uriString).buildAndExpand("hot&cold");
 

Parameters:

query - the query string

Returns:

this UriComponentsBuilder

replaceQuery

public UriComponentsBuilder replaceQuery(java.lang.String query)

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

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)

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

Parameters:

name - the query parameter name

values - the query parameter values

Returns:

this UriComponentsBuilder

replaceQueryParam

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

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

Parameters:

name - the query parameter name

values - the query parameter values

Returns:

this UriComponentsBuilder

fragment

public UriComponentsBuilder fragment(java.lang.String fragment)

Sets 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

Returns:

this UriComponentsBuilder