UriComponentsBuilder (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.util

## Class UriComponentsBuilder

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

- Direct Known Subclasses:
    ServletUriComponentsBuilder

      public class UriComponentsBuilder
      extends 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
  See Also:
    `newInstance()`, `fromPath(String)`, `fromUri(URI)`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `UriComponentsBuilder()` Default constructor.

  - ### Method Summary

    Methods
    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(Map<String,?> uriVariables)` Builds a `UriComponents` instance and replaces URI template variables with the values from a map.
    `UriComponents` | `buildAndExpand(Object... uriVariableValues)` Builds a `UriComponents` instance and replaces URI template variables with the values from an array.
    `UriComponentsBuilder` | `fragment(String fragment)` Sets the URI fragment.
    `static UriComponentsBuilder` | `fromHttpUrl(String httpUrl)` Creates a new `UriComponents` object from the string HTTP URL.
    `static UriComponentsBuilder` | `fromPath(String path)` Returns a builder that is initialized with the given path.
    `static UriComponentsBuilder` | `fromUri(URI uri)` Returns a builder that is initialized with the given `URI`.
    `static UriComponentsBuilder` | `fromUriString(String uri)` Returns a builder that is initialized with the given URI string.
    `UriComponentsBuilder` | `host(String host)` Sets the URI host.
    `static UriComponentsBuilder` | `newInstance()` Returns a new, empty builder.
    `UriComponentsBuilder` | `path(String path)` Appends the given path to the existing path of this builder.
    `UriComponentsBuilder` | `pathSegment(String... pathSegments)` Appends the given path segments to the existing path of this builder.
    `UriComponentsBuilder` | `port(int port)` Sets the URI port.
    `UriComponentsBuilder` | `query(String query)` Appends the given query to the existing query of this builder.
    `UriComponentsBuilder` | `queryParam(String name, Object... values)` Appends the given query parameter to the existing query parameters.
    `UriComponentsBuilder` | `replacePath(String path)` Sets the path of this builder overriding all existing path and path segment values.
    `UriComponentsBuilder` | `replaceQuery(String query)` Sets the query of this builder overriding all existing query parameters.
    `UriComponentsBuilder` | `replaceQueryParam(String name, Object... values)` Sets the query parameter values overriding all existing query values for the same parameter.
    `UriComponentsBuilder` | `scheme(String scheme)` Sets the URI scheme.
    `UriComponentsBuilder` | `schemeSpecificPart(String ssp)` Set the URI scheme-specific-part.
    `UriComponentsBuilder` | `uri(URI uri)` Initializes all components of this URI builder with the components of the given URI.
    `UriComponentsBuilder` | `userInfo(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`

- - ### 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(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(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(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(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(Map<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(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(URI uri)

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

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

      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(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(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(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(String... pathSegments)
                                           throws 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:
        `IllegalArgumentException`

    - #### query

          public UriComponentsBuilder query(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(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(String name,
                                        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(String name,
                                               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(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