UriComponentsBuilder (Spring Framework 5.2.3.RELEASE API)

java.lang.Object
- org.springframework.web.util.UriComponentsBuilder

All Implemented Interfaces:

Cloneable, UriBuilder

Direct Known Subclasses:

ServletUriComponentsBuilder
```
public class UriComponentsBuilder
extends Object
implements UriBuilder, 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

All Methods Static Methods Instance Methods Concrete Methods
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.
`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.
`UriComponents`	`buildAndExpand(Map<String,?> uriVariables)` Build a `UriComponents` instance and replaces URI template variables with the values from a map.
`UriComponents`	`buildAndExpand(Object... uriVariableValues)` Build a `UriComponents` instance and replaces URI template variables with the values from an array.
`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(Charset charset)` A variant of `encode()` with a charset other than "UTF-8".
`UriComponentsBuilder`	`fragment(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(String httpUrl)` Create a URI components builder from the given HTTP URL String.
`static UriComponentsBuilder`	`fromOriginHeader(String origin)` Create an instance by parsing the "Origin" header of an HTTP request.
`static UriComponentsBuilder`	`fromPath(String path)` Create a builder that is initialized with the given path.
`static UriComponentsBuilder`	`fromUri(URI uri)` Create a builder that is initialized with the given `URI`.
`static UriComponentsBuilder`	`fromUriString(String uri)` Create a builder that is initialized with the given URI string.
`UriComponentsBuilder`	`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.
`static UriComponentsBuilder`	`newInstance()` Create a new, empty builder.
`UriComponentsBuilder`	`path(String path)` Append the given path to the existing path of this builder.
`UriComponentsBuilder`	`pathSegment(String... pathSegments)` Append path segments to the existing path.
`UriComponentsBuilder`	`port(int port)` Set the URI port.
`UriComponentsBuilder`	`port(String port)` Set the URI port .
`UriComponentsBuilder`	`query(String query)` Parse the given query string into query parameters where parameters are separated with `'&'` and their values, if any, with `'='`.
`UriComponentsBuilder`	`queryParam(String name, Collection<?> values)` Variant of `UriBuilder.queryParam(String, Object...)` with a Collection.
`UriComponentsBuilder`	`queryParam(String name, Object... values)` Append the given query parameter.
`UriComponentsBuilder`	`queryParams(MultiValueMap<String,String> params)` Add multiple query parameters and values.
`UriComponentsBuilder`	`replacePath(String path)` Set the path of this builder overriding the existing path values.
`UriComponentsBuilder`	`replaceQuery(String query)` Clear existing query parameters and then delegate to `UriBuilder.query(String)`.
`UriComponentsBuilder`	`replaceQueryParam(String name, Collection<?> values)` Variant of `UriBuilder.replaceQueryParam(String, Object...)` with a Collection.
`UriComponentsBuilder`	`replaceQueryParam(String name, Object... values)` Set the query parameter values replacing existing values, or if no values are given, the query parameter is removed.
`UriComponentsBuilder`	`replaceQueryParams(MultiValueMap<String,String> params)` Set the query parameter values after removing all existing ones.
`UriComponentsBuilder`	`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.
`UriComponentsBuilder`	`schemeSpecificPart(String ssp)` Set the URI scheme-specific-part.
`String`	`toUriString()` Build a URI String.
`UriComponentsBuilder`	`uri(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(Map<String,Object> uriVariables)` Configure URI variables to be expanded at build time.
`UriComponentsBuilder`	`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.

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(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(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(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(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(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(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(Map<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(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 URI build(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 URI build(Map<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 String toUriString()
```
    Build a URI String.
    Effectively, a shortcut for building, encoding, and returning the String representation:
```
 String uri = builder.build().encode().toUriString()
 
```
    However if URI variables have been provided then the URI template is pre-encoded separately from URI variables (see encode() for details), i.e. equivalent to:
```
 String uri = builder.encode().build().toUriString()
 
```
    Since:
    
    4.1
    
    See Also:
    
    UriComponents.toUriString()
  - uri
```
public UriComponentsBuilder uri(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
                                   String scheme)
```
    Description copied from interface: UriBuilder
    
    Set the URI scheme which 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
  - schemeSpecificPart
```
public UriComponentsBuilder schemeSpecificPart(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
                                     String userInfo)
```
    Description copied from interface: UriBuilder
    
    Set the URI user info which 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
  - host
```
public UriComponentsBuilder host(@Nullable
                                 String host)
```
    Description copied from interface: UriBuilder
    
    Set the URI host which 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
  - port
```
public UriComponentsBuilder port(int port)
```
    Description copied from interface: UriBuilder
    
    Set the URI port. Passing -1 will clear the port of this builder.
    
    Specified by:
    
    port in interface UriBuilder
    
    Parameters:
    
    port - the URI port
  - port
```
public UriComponentsBuilder port(@Nullable
                                 String port)
```
    Description copied from interface: UriBuilder
    
    Set the URI port . Use this method only when the port needs to be parameterized with a URI variable. Otherwise use UriBuilder.port(int). Passing null will clear the port of this builder.
    
    Specified by:
    
    port in interface UriBuilder
    
    Parameters:
    
    port - the URI port
  - path
```
public UriComponentsBuilder path(String path)
```
    Description copied from interface: UriBuilder
    
    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
  - pathSegment
```
public UriComponentsBuilder pathSegment(String... pathSegments)
                                 throws IllegalArgumentException
```
    Description copied from interface: UriBuilder
    
    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
    
    Throws:
    
    IllegalArgumentException
  - replacePath
```
public UriComponentsBuilder replacePath(@Nullable
                                        String path)
```
    Description copied from interface: UriBuilder
    
    Set the path of this builder overriding the existing path values.
    
    Specified by:
    
    replacePath in interface UriBuilder
    
    Parameters:
    
    path - the URI path, or null for an empty path
  - query
```
public UriComponentsBuilder query(@Nullable
                                  String query)
```
    Description copied from interface: UriBuilder
    
    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 UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    query in interface UriBuilder
    
    Parameters:
    
    query - the query string
  - replaceQuery
```
public UriComponentsBuilder replaceQuery(@Nullable
                                         String query)
```
    Description copied from interface: UriBuilder
    
    Clear existing query parameters and then delegate to UriBuilder.query(String).
    Note: please, review the Javadoc of UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    replaceQuery in interface UriBuilder
    
    Parameters:
    
    query - the query string; a null value removes all query parameters.
  - queryParam
```
public UriComponentsBuilder queryParam(String name,
                                       Object... values)
```
    Description copied from interface: UriBuilder
    
    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.
    
    Specified by:
    
    queryParam in interface UriBuilder
    
    Parameters:
    
    name - the query parameter name
    
    values - the query parameter values
    
    See Also:
    
    UriBuilder.queryParam(String, Collection)
  - queryParam
```
public UriComponentsBuilder queryParam(String name,
                                       @Nullable
                                       Collection<?> values)
```
    Description copied from interface: UriBuilder
    
    Variant of UriBuilder.queryParam(String, Object...) with a Collection.
    Note: please, review the Javadoc of UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    queryParam in interface UriBuilder
    
    Parameters:
    
    name - the query parameter name
    
    values - the query parameter values
    
    See Also:
    
    UriBuilder.queryParam(String, Object...)
  - queryParams
```
public UriComponentsBuilder queryParams(@Nullable
                                        MultiValueMap<String,String> params)
```
    Add multiple query parameters and values.
    Note: please, review the Javadoc of UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    queryParams in interface UriBuilder
    
    Parameters:
    
    params - the params
    
    Since:
    
    4.0
  - replaceQueryParam
```
public UriComponentsBuilder replaceQueryParam(String name,
                                              Object... values)
```
    Description copied from interface: UriBuilder
    
    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 UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    replaceQueryParam in interface UriBuilder
    
    Parameters:
    
    name - the query parameter name
    
    values - the query parameter values
    
    See Also:
    
    UriBuilder.replaceQueryParam(String, Collection)
  - replaceQueryParam
```
public UriComponentsBuilder replaceQueryParam(String name,
                                              @Nullable
                                              Collection<?> values)
```
    Description copied from interface: UriBuilder
    
    Variant of UriBuilder.replaceQueryParam(String, Object...) with a Collection.
    Note: please, review the Javadoc of UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    replaceQueryParam in interface UriBuilder
    
    Parameters:
    
    name - the query parameter name
    
    values - the query parameter values
    
    See Also:
    
    UriBuilder.replaceQueryParam(String, Object...)
  - replaceQueryParams
```
public UriComponentsBuilder replaceQueryParams(@Nullable
                                               MultiValueMap<String,String> params)
```
    Set the query parameter values after removing all existing ones.
    Note: please, review the Javadoc of UriBuilder.queryParam(String, Object...) for further notes on the treatment and encoding of individual query parameters.
    
    Specified by:
    
    replaceQueryParams in interface UriBuilder
    
    Parameters:
    
    params - the query parameter name
    
    Since:
    
    4.2
  - fragment
```
public UriComponentsBuilder fragment(@Nullable
                                     String fragment)
```
    Description copied from interface: UriBuilder
    
    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
  - uriVariables
```
public UriComponentsBuilder uriVariables(Map<String,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 Object clone()
```
    Public declaration of Object's clone() method. Delegates to cloneBuilder().
    
    Overrides:
    
    clone in class Object
  - cloneBuilder
```
public UriComponentsBuilder cloneBuilder()
```
    Clone this UriComponentsBuilder.
    
    Returns:
    
    the cloned UriComponentsBuilder object
    
    Since:
    
    4.2.7

Class UriComponentsBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

UriComponentsBuilder

UriComponentsBuilder

Method Detail

newInstance

fromPath

fromUri

fromUriString

fromHttpUrl

fromHttpRequest

fromOriginHeader

encode

encode

build

build

buildAndExpand

buildAndExpand

build

build

toUriString

uri

uriComponents

scheme

schemeSpecificPart

userInfo

host

port

port

path

pathSegment

replacePath

query

replaceQuery

queryParam

queryParam

queryParams

replaceQueryParam

replaceQueryParam

replaceQueryParams

fragment

uriVariables

clone

cloneBuilder