UriComponentsBuilder (Spring Framework 4.1.6.RELEASE API)

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

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

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

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.
`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.
`protected Object`	`clone()`
`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 "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if present.
`static UriComponentsBuilder`	`fromHttpUrl(String httpUrl)` Create a URI components builder from the given HTTP URL String.
`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.
`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 the given path segments to the existing path of this builder.
`UriComponentsBuilder`	`port(int port)` Set the URI port.
`UriComponentsBuilder`	`port(String port)` Set the URI port.
`UriComponentsBuilder`	`query(String query)` Append the given query to the existing query of this builder.
`UriComponentsBuilder`	`queryParam(String name, Object... values)` Append the given query parameter to the existing query parameters.
`UriComponentsBuilder`	`queryParams(MultiValueMap<String,String> params)` Add the given query parameters.
`UriComponentsBuilder`	`replacePath(String path)` Set the path of this builder overriding all existing path and path segment values.
`UriComponentsBuilder`	`replaceQuery(String query)` Set the query of this builder overriding all existing query parameters.
`UriComponentsBuilder`	`replaceQueryParam(String name, Object... values)` Set the query parameter values overriding all existing query values for the same parameter.
`UriComponentsBuilder`	`scheme(String scheme)` Set the URI scheme.
`UriComponentsBuilder`	`schemeSpecificPart(String ssp)` Set the URI scheme-specific-part.
`String`	`toUriString()` Build a URI String.
`UriComponentsBuilder`	`uri(URI uri)` Initialize all components of this URI builder with the components of the given URI.
`UriComponentsBuilder`	`uriComponents(UriComponents uriComponents)` Set all components of this URI builder from the given `UriComponents`.
`UriComponentsBuilder`	`userInfo(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
- 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 uriString = "/hotels/42?filter={value}";
 UriComponentsBuilder.fromUriString(uriString).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 "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" if present.
    
    Parameters:
    
    request - the source request
    
    Returns:
    
    the URI components of the URI
    
    Since:
    
    4.1.5
  - 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 - URI variable values
    
    Returns:
    
    the URI components with expanded values
  - toUriString
```
public 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(URI uri)
```
    Initialize all components of this URI builder with the components of the given URI.
    
    Parameters:
    
    uri - the URI
    
    Returns:
    
    this UriComponentsBuilder
  - scheme
```
public UriComponentsBuilder scheme(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.
    
    Parameters:
    
    scheme - the URI scheme
    
    Returns:
    
    this UriComponentsBuilder
  - uriComponents
```
public UriComponentsBuilder uriComponents(UriComponents uriComponents)
```
    Set all components of this URI builder from the given UriComponents.
    
    Parameters:
    
    uriComponents - the UriComponents instance
    
    Returns:
    
    this UriComponentsBuilder
  - 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(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.
    
    Parameters:
    
    userInfo - the URI user info
    
    Returns:
    
    this UriComponentsBuilder
  - host
```
public UriComponentsBuilder host(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.
    
    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.
    
    Parameters:
    
    port - the URI port
    
    Returns:
    
    this UriComponentsBuilder
  - port
```
public UriComponentsBuilder 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 - the URI port
    
    Returns:
    
    this UriComponentsBuilder
  - path
```
public UriComponentsBuilder 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
    
    Returns:
    
    this UriComponentsBuilder
  - replacePath
```
public UriComponentsBuilder replacePath(String path)
```
    Set 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(String... pathSegments)
                                 throws IllegalArgumentException
```
    Append the given path segments to the existing path of this builder. Each given path segment may contain URI template variables.
    
    Parameters:
    
    pathSegments - the URI path segments
    
    Returns:
    
    this UriComponentsBuilder
    
    Throws:
    
    IllegalArgumentException
  - query
```
public UriComponentsBuilder query(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:
```
 String uriString = "/hotels/42?filter={value}";
 UriComponentsBuilder.fromUriString(uriString).buildAndExpand("hot&cold");
 
```
    Parameters:
    
    query - the query string
    
    Returns:
    
    this UriComponentsBuilder
  - replaceQuery
```
public UriComponentsBuilder replaceQuery(String query)
```
    Set 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(String name,
                                       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.
    
    Parameters:
    
    name - the query parameter name
    
    values - the query parameter values
    
    Returns:
    
    this UriComponentsBuilder
  - queryParams
```
public UriComponentsBuilder queryParams(MultiValueMap<String,String> params)
```
    Add the given query parameters.
    
    Parameters:
    
    params - the params
    
    Returns:
    
    this UriComponentsBuilder
  - replaceQueryParam
```
public UriComponentsBuilder replaceQueryParam(String name,
                                              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.
    
    Parameters:
    
    name - the query parameter name
    
    values - the query parameter values
    
    Returns:
    
    this UriComponentsBuilder
  - fragment
```
public UriComponentsBuilder 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 - the URI fragment
    
    Returns:
    
    this UriComponentsBuilder
  - clone
```
protected Object clone()
```
    Overrides:
    
    clone in class Object

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

build

build

buildAndExpand

buildAndExpand

toUriString

uri

scheme

uriComponents

schemeSpecificPart

userInfo

host

port

port

path

replacePath

pathSegment

query

replaceQuery

queryParam

queryParams

replaceQueryParam

fragment

clone