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
`(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
`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