Package com.google.gwt.safehtml.shared

Class 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 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

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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 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