com.google.gwt.safehtml.shared

## Interface SafeHtml

- All Superinterfaces:
    java.io.Serializable
  All Known Implementing Classes:
    OnlyToBeUsedInGeneratedCodeStringBlessedAsSafeHtml, SafeHtmlString

      public interface SafeHtml
      extends java.io.Serializable

  An object that implements this interface encapsulates HTML that is guaranteed to be safe to use (with respect to potential Cross-Site-Scripting vulnerabilities) in an HTML context.

  Note on usage: SafeHtml should be used to ensure user input is not executed in the browser. SafeHtml should not be used to sanitize input before sending it to the server: The server cannot rely on the type contract of SafeHtml values received from clients, because a malicious client could provide maliciously crafted serialized forms of implementations of this type that violate the type contract.

  All implementing classes must maintain the class invariant (by design and implementation and/or convention of use), that invoking `asString()` on any instance will return a string that is safe to assign to the `.innerHTML` DOM property in a browser (or to use similarly in an "inner HTML" context), in the sense that doing so must not cause execution of script in the browser.

  Furthermore, values of this type must be composable, i.e. for any two values `A` and `B` of this type, `A.asString() + B.asString()` must itself be a value that satisfies the SafeHtml type constraint. This requirement implies that for any value `A` of this type, if `A.asString()` includes HTML markup, the string must end in an "inner HTML" context and not inside a tag or attribute. For example, a value of `<div style="` or `<img src="` would not satisfy the SafeHtml contract. This is because concatenating such strings with a second value that itself does not contain script-executing HTML markup can result in an overall string that does. For example, if `javascript:malicious()">` is appended to `<img src="`, the resulting string may result in script execution.

  All implementations must implement equals() and hashCode() to behave consistently with the result of asString().equals() and asString.hashCode().

  Implementations must not return `null` from `asString()`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `asString()` Returns this object's contained HTML as a string.
    `boolean` | `equals(java.lang.Object anObject)` Compares this string to the specified object.
    `int` | `hashCode()` Returns a hash code for this string.

- - ### Method Detail

    - #### asString

          java.lang.String asString()

      Returns this object's contained HTML as a string.

      Based on this class' contract, the returned value will be non-null and a string that is safe to use in an HTML context.

      Returns:
        the contents as a String

    - #### equals

          boolean equals(java.lang.Object anObject)

      Compares this string to the specified object. Must be equal to asString().equals().
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `anObject` - the object to compare to

    - #### hashCode

          int hashCode()

      Returns a hash code for this string. Must be equal to asString().hashCode().
      Overrides:
        `hashCode` in class `java.lang.Object`