Package org.springframework.web.util

Class UriComponentsBuilder

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. Use as follows:
  1. Create a builder through a factory method, e.g. fromUriString(String).
  2. Set URI components (e.g. scheme, host, path, etc) through instance methods.
  3. Build the UriComponents.
  4. Expand URI variables from a map or array or variable values.
  5. Encode via UriComponents.encode().
  6. Use UriComponents.toUri() or UriComponents.toUriString().

By default, URI parsing is based on the RFC parser type, which expects input strings to conform to RFC 3986 syntax. The alternative WhatWG parser type, based on the algorithm from the WhatWG URL Living Standard provides more lenient handling of a wide range of cases that occur in user types URL's.

Since:
3.1
Author:
Arjen Poutsma, Rossen Stoyanchev, Phillip Webb, Oliver Gierke, Brian Clozel, Sebastien Deleuze, Sam Brannen
See Also:

  • Constructor Details

    • UriComponentsBuilder

      protected UriComponentsBuilder()
      Default constructor. Protected to prevent direct instantiation.
      See Also:

    • 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 Details

    • 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 from the given URI.

      Note: the components in the resulting builder will be in fully encoded (raw) form and further changes must also supply values that are fully encoded, for example via methods in UriUtils. In addition please use build(boolean) with a value of "true" to build the UriComponents instance in order to indicate that the components are encoded.

      Parameters:
      uri - the URI to initialize with
      Returns:
      the new UriComponentsBuilder

    • fromUriString

      public static UriComponentsBuilder fromUriString(String uri) throws InvalidUrlException
      Variant of fromUriString(String, ParserType) that defaults to the UriComponentsBuilder.ParserType.RFC parsing.
      Throws:
      InvalidUrlException

    • fromUriString

      public static UriComponentsBuilder fromUriString(String uri, UriComponentsBuilder.ParserType parserType) throws InvalidUrlException
      Create a builder that is initialized by parsing 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
      parserType - the parsing algorithm to use
      Returns:
      the new UriComponentsBuilder
      Throws:
      InvalidUrlException - if uri cannot be parsed
      Since:
      6.2

    • fromHttpUrl

      @Deprecated(since="6.2") public static UriComponentsBuilder fromHttpUrl(String httpUrl) throws InvalidUrlException
      Deprecated.
      as of 6.2, in favor of fromUriString(String); scheduled for removal in 7.0.
      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
      Throws:
      InvalidUrlException

    • 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 when 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.

      When not expanding URI variables at all, prefer use of UriComponents.encode() since that will also encode anything that incidentally looks like a URI variable.

      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)
      Variant of build() to create a UriComponents instance when components are already fully encoded. This is useful for example if the builder was created via fromUri(URI).
      Parameters:
      encoded - whether the components in this builder are already encoded
      Returns:
      the URI components
      Throws:
      IllegalArgumentException - if any of the components contain illegal characters that should have been encoded.

    • 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()
      Specified by:
      toUriString in interface UriBuilder
      Since:
      4.1
      See Also:

    • 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 to the path of this builder.

      The given value is appended as-is to previous path values without inserting any additional slashes. For example: 

      
 builder.path("/first-").path("value/").path("/{id}").build("123")

 // Results is "/first-value/123"

      By contrast pathSegment does insert slashes between individual path segments. For example: 

      
 builder.pathSegment("first-value", "second-value").path("/")

 // Results is "/first-value/second-value/"

      The resulting full path is normalized to eliminate duplicate slashes.

      Note: When inserting a URI variable value that contains slashes in a path, whether those are encoded depends on the configured encoding mode. For more details, see encode(), or otherwise if building URIs indirectly via WebClient or RestTemplate, see its encodingMode. Also see the URI Encoding section of the reference docs.

      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 to the path using path segments. For example: 
      
 builder.pathSegment("first-value", "second-value", "{id}").build("123")

 // Results is "/first-value/second-value/123"

      If slashes are present in a path segment, they are encoded: 

      
 builder.pathSegment("ba/z", "{id}").build("a/b")

 // Results is "/ba%2Fz/a%2Fb"
      To insert a trailing slash, use the UriBuilder.path(java.lang.String) builder method: 
      
 builder.pathSegment("first-value", "second-value").path("/")

 // Results is "/first-value/second-value/"

      Empty path segments are ignored and therefore duplicate slashes do not appear in the resulting full path.

      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
      Override the current path.
      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, @Nullable 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, for example, "?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:

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

    • queryParamIfPresent

      public UriComponentsBuilder queryParamIfPresent(String name, Optional<?> value)
      Description copied from interface: UriBuilder
      Delegates to either UriBuilder.queryParam(String, Object...) or UriBuilder.queryParam(String, Collection) if the given Optional has a value, or else if it is empty, no query parameter is added at all.
      Specified by:
      queryParamIfPresent in interface UriBuilder
      Parameters:
      name - the query parameter name
      value - an Optional, either empty or holding the query parameter value.

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

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

    • 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