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

org.springframework.web.util

## Class UriUtils

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

-     public abstract class UriUtils
      extends Object

  Utility class for URI encoding and decoding based on RFC 3986. Offers encoding methods for the various URI components.

  All `encode*(String, String` methods in this class operate in a similar way:

  - Valid characters for the specific URI component as defined in RFC 3986 stay the same.
  - All other characters are converted into one or more bytes in the given encoding scheme. Each of the resulting bytes is written as a hexadecimal string in the "`%<i>xy</i>`" format.
  Since:
    3.0
  Author:
    Arjen Poutsma
  See Also:
    RFC 3986

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `UriUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `decode(String source, String encoding)` Decodes the given encoded source String into an URI.
    `static String` | `encodeAuthority(String authority, String encoding)` Encodes the given URI authority with the given encoding.
    `static String` | `encodeFragment(String fragment, String encoding)` Encodes the given URI fragment with the given encoding.
    `static String` | `encodeHost(String host, String encoding)` Encodes the given URI host with the given encoding.
    `static String` | `encodeHttpUrl(String httpUrl, String encoding)` Deprecated. in favor of `UriComponentsBuilder`; see note about query param encoding
    `static String` | `encodePath(String path, String encoding)` Encodes the given URI path with the given encoding.
    `static String` | `encodePathSegment(String segment, String encoding)` Encodes the given URI path segment with the given encoding.
    `static String` | `encodePort(String port, String encoding)` Encodes the given URI port with the given encoding.
    `static String` | `encodeQuery(String query, String encoding)` Encodes the given URI query with the given encoding.
    `static String` | `encodeQueryParam(String queryParam, String encoding)` Encodes the given URI query parameter with the given encoding.
    `static String` | `encodeScheme(String scheme, String encoding)` Encodes the given URI scheme with the given encoding.
    `static String` | `encodeUri(String uri, String encoding)` Deprecated. in favor of `UriComponentsBuilder`; see note about query param encoding
    `static String` | `encodeUriComponents(String scheme, String authority, String userInfo, String host, String port, String path, String query, String fragment, String encoding)` Deprecated. in favor of `UriComponentsBuilder`
    `static String` | `encodeUserInfo(String userInfo, String encoding)` Encodes the given URI user info with the given encoding.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### UriUtils

          public UriUtils()

  - ### Method Detail

    - #### encodeUri

          @Deprecated
          public static String encodeUri(String uri,
                                    String encoding)
                                  throws UnsupportedEncodingException

      Deprecated. in favor of `UriComponentsBuilder`; see note about query param encoding
      Encodes the given source URI into an encoded String. All various URI components are encoded according to their respective valid character sets.

      Note that this method does not attempt to encode "=" and "&" characters in query parameter names and query parameter values because they cannot be parsed in a reliable way. Instead use:

           UriComponents uriComponents = UriComponentsBuilder.fromUri("/path?name={value}").buildAndExpand("a=b");
           String encodedUri = uriComponents.encode().toUriString();

      Parameters:
        `uri` - the URI to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded URI
      Throws:
        `IllegalArgumentException` - when the given uri parameter is not a valid URI
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeHttpUrl

          @Deprecated
          public static String encodeHttpUrl(String httpUrl,
                                        String encoding)
                                      throws UnsupportedEncodingException

      Deprecated. in favor of `UriComponentsBuilder`; see note about query param encoding
      Encodes the given HTTP URI into an encoded String. All various URI components are encoded according to their respective valid character sets.

      Note that this method does not support fragments (`#`), as these are not supposed to be sent to the server, but retained by the client.

      Note that this method does not attempt to encode "=" and "&" characters in query parameter names and query parameter values because they cannot be parsed in a reliable way. Instead use:

           UriComponents uriComponents = UriComponentsBuilder.fromHttpUrl("/path?name={value}").buildAndExpand("a=b");
           String encodedUri = uriComponents.encode().toUriString();

      Parameters:
        `httpUrl` - the HTTP URL to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded URL
      Throws:
        `IllegalArgumentException` - when the given uri parameter is not a valid URI
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeUriComponents

          @Deprecated
          public static String encodeUriComponents(String scheme,
                                              String authority,
                                              String userInfo,
                                              String host,
                                              String port,
                                              String path,
                                              String query,
                                              String fragment,
                                              String encoding)
                                            throws UnsupportedEncodingException

      Deprecated. in favor of `UriComponentsBuilder`
      Encodes the given source URI components into an encoded String. All various URI components are optional, but encoded according to their respective valid character sets.
      Parameters:
        `scheme` - the scheme
        `authority` - the authority
        `userInfo` - the user info
        `host` - the host
        `port` - the port
        `path` - the path
        `query` - the query
        `fragment` - the fragment
        `encoding` - the character encoding to encode to
      Returns:
        the encoded URI
      Throws:
        `IllegalArgumentException` - when the given uri parameter is not a valid URI
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeScheme

          public static String encodeScheme(String scheme,
                            String encoding)
                                     throws UnsupportedEncodingException

      Encodes the given URI scheme with the given encoding.
      Parameters:
        `scheme` - the scheme to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded scheme
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeAuthority

          public static String encodeAuthority(String authority,
                               String encoding)
                                        throws UnsupportedEncodingException

      Encodes the given URI authority with the given encoding.
      Parameters:
        `authority` - the authority to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded authority
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeUserInfo

          public static String encodeUserInfo(String userInfo,
                              String encoding)
                                       throws UnsupportedEncodingException

      Encodes the given URI user info with the given encoding.
      Parameters:
        `userInfo` - the user info to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded user info
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeHost

          public static String encodeHost(String host,
                          String encoding)
                                   throws UnsupportedEncodingException

      Encodes the given URI host with the given encoding.
      Parameters:
        `host` - the host to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded host
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodePort

          public static String encodePort(String port,
                          String encoding)
                                   throws UnsupportedEncodingException

      Encodes the given URI port with the given encoding.
      Parameters:
        `port` - the port to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded port
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodePath

          public static String encodePath(String path,
                          String encoding)
                                   throws UnsupportedEncodingException

      Encodes the given URI path with the given encoding.
      Parameters:
        `path` - the path to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded path
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodePathSegment

          public static String encodePathSegment(String segment,
                                 String encoding)
                                          throws UnsupportedEncodingException

      Encodes the given URI path segment with the given encoding.
      Parameters:
        `segment` - the segment to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded segment
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeQuery

          public static String encodeQuery(String query,
                           String encoding)
                                    throws UnsupportedEncodingException

      Encodes the given URI query with the given encoding.
      Parameters:
        `query` - the query to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded query
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeQueryParam

          public static String encodeQueryParam(String queryParam,
                                String encoding)
                                         throws UnsupportedEncodingException

      Encodes the given URI query parameter with the given encoding.
      Parameters:
        `queryParam` - the query parameter to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded query parameter
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### encodeFragment

          public static String encodeFragment(String fragment,
                              String encoding)
                                       throws UnsupportedEncodingException

      Encodes the given URI fragment with the given encoding.
      Parameters:
        `fragment` - the fragment to be encoded
        `encoding` - the character encoding to encode to
      Returns:
        the encoded fragment
      Throws:
        `UnsupportedEncodingException` - when the given encoding parameter is not supported

    - #### decode

          public static String decode(String source,
                      String encoding)
                               throws UnsupportedEncodingException

      Decodes the given encoded source String into an URI. Based on the following rules:
      - Alphanumeric characters `"a"` through `"z"`, `"A"` through `"Z"`, and `"0"` through `"9"` stay the same.
      - Special characters `"-"`, `"_"`, `"."`, and `"*"` stay the same.
      - A sequence "`%<i>xy</i>`" is interpreted as a hexadecimal representation of the character.
      Parameters:
        `source` - the source string
        `encoding` - the encoding
      Returns:
        the decoded URI
      Throws:
        `IllegalArgumentException` - when the given source contains invalid encoded sequences
        `UnsupportedEncodingException` - when the given encoding parameter is not supported
      See Also:
        `URLDecoder.decode(String, String)`