Package org.springframework.web.util

Class UriComponentsBuilder

    • Method Detail

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

      • 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

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

      • 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 without any checks for slashes other than to clean up duplicates. For example: 

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

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

        By contrast UriBuilder.pathSegment(String...) builds the path from individual path segments and in that case slashes are inserted transparently. In some cases you may use a combination of both pathSegment and path. For example: 

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

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

        If a URI variable value contains slashes, whether those are encoded or not depends on the configured encoding mode. See encode(), or if using UriComponentsBuilder via DefaultUriBuilderFactory (e.g. WebClient or RestTemplate) see its encodingMode property. 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/"
        Specified by:
        pathSegment in interface UriBuilder
        Parameters:
        pathSegments - the URI path segments
        Throws:
        IllegalArgumentException

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

      • 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