com.google.gwt.safehtml.shared

## Class UriUtils

- java.lang.Object
- - com.google.gwt.safehtml.shared.UriUtils

-     public final class UriUtils
      extends java.lang.Object

  Utility class containing static methods for validating and sanitizing URIs.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static java.lang.String` | `DONT_NEED_ENCODING` Characters that don't need %-escaping (minus letters and digits), according to ECMAScript 5th edition for the `encodeURI` function.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `encode(java.lang.String uri)` Encodes the URL.
    `static java.lang.String` | `encodeAllowEscapes(java.lang.String uri)` Encodes the URL, preserving existing %-escapes.
    `static java.lang.String` | `extractScheme(java.lang.String uri)` Extracts the scheme of a URI.
    `static SafeUri` | `fromSafeConstant(java.lang.String s)` Returns a `SafeUri` constructed from a value that is fully under the control of the program, e.g., a constant.
    `static SafeUri` | `fromString(java.lang.String s)` Returns a `SafeUri` obtained by sanitizing the provided string.
    `static SafeUri` | `fromTrustedString(java.lang.String s)` Returns a `SafeUri` constructed from a trusted string, i.e., without sanitizing the string.
    `static boolean` | `isSafeUri(java.lang.String uri)` Determines if a `String` is safe to use as the value of a URI-valued HTML attribute such as `src` or `href`.
    `static java.lang.String` | `sanitizeUri(java.lang.String uri)` Sanitizes a URI.
    `static SafeUri` | `unsafeCastFromUntrustedString(java.lang.String s)` Deprecated. This method is intended only for use in APIs that use `SafeUri` to represent URIs, but for backwards compatibility have methods that accept URI parameters as plain strings.

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

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

- - ### Field Detail

    - #### DONT_NEED_ENCODING

          static final java.lang.String DONT_NEED_ENCODING

      Characters that don't need %-escaping (minus letters and digits), according to ECMAScript 5th edition for the `encodeURI` function.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### encode

          public static java.lang.String encode(java.lang.String uri)

      Encodes the URL.

      In client code, this method delegates to `URL.encode(String)` and then unescapes brackets, as they might be used for IPv6 addresses.

      Parameters:
        `uri` - the URL to encode
      Returns:
        the %-escaped URL

    - #### encodeAllowEscapes

          public static java.lang.String encodeAllowEscapes(java.lang.String uri)

      Encodes the URL, preserving existing %-escapes.
      Parameters:
        `uri` - the URL to encode
      Returns:
        the %-escaped URL

    - #### extractScheme

          public static java.lang.String extractScheme(java.lang.String uri)

      Extracts the scheme of a URI.
      Parameters:
        `uri` - the URI to extract the scheme from
      Returns:
        the URI's scheme, or `null` if the URI does not have one

    - #### fromSafeConstant

          public static SafeUri fromSafeConstant(java.lang.String s)

      Returns a `SafeUri` constructed from a value that is fully under the control of the program, e.g., a constant.

      The string is not sanitized and no checks are performed. The assumption that the resulting value adheres to the `SafeUri` type contract is entirely based on the argument being fully under program control and not being derived from a program input.

      Convention of use: This method must only be invoked on values that are fully under the program's control, such as string literals.

      Parameters:
        `s` - the input String
      Returns:
        a SafeUri instance

    - #### fromString

          public static SafeUri fromString(java.lang.String s)

      Returns a `SafeUri` obtained by sanitizing the provided string.

      The input string is sanitized using `sanitizeUri(String)`.

      Parameters:
        `s` - the input String
      Returns:
        a SafeUri instance

    - #### fromTrustedString

          public static SafeUri fromTrustedString(java.lang.String s)

      Returns a `SafeUri` constructed from a trusted string, i.e., without sanitizing the string. No checks are performed. The calling code should be carefully reviewed to ensure the argument meets the SafeUri contract.
      Parameters:
        `s` - the input String
      Returns:
        a SafeUri instance

    - #### isSafeUri

          public static boolean isSafeUri(java.lang.String uri)

      Determines if a `String` is safe to use as the value of a URI-valued HTML attribute such as `src` or `href`.

      In this context, a URI is safe if it can be established that using it as the value of a URI-valued HTML attribute such as `src` or `href` cannot result in script execution. Specifically, this method deems a URI safe if it either does not have a scheme, or its scheme is one of `http, https, ftp, mailto`.

      Parameters:
        `uri` - the URI to validate
      Returns:
        `true` if `uri` is safe in the above sense; `false` otherwise

    - #### sanitizeUri

          public static java.lang.String sanitizeUri(java.lang.String uri)

      Sanitizes a URI.

      This method returns the URI provided if it is safe to use as the the value of a URI-valued HTML attribute according to `isSafeUri(java.lang.String)`, or the URI "`#`" otherwise.

      Parameters:
        `uri` - the URI to sanitize
      Returns:
        a sanitized String

    - #### unsafeCastFromUntrustedString

          @Deprecated
          public static SafeUri unsafeCastFromUntrustedString(java.lang.String s)

      Deprecated. This method is intended only for use in APIs that use `SafeUri` to represent URIs, but for backwards compatibility have methods that accept URI parameters as plain strings.
      Returns a `SafeUri` constructed from an untrusted string but without sanitizing it. Despite this method creating a SafeUri instance, no checks are performed, so the returned SafeUri is absolutely NOT guaranteed to be safe!
      Parameters:
        `s` - the input String
      Returns:
        a SafeUri instance