Version 4.10.0
Class SafeText

  extended by
All Implemented Interfaces:
Serializable, Comparable<SafeText>

public final class SafeText
extends Object
implements Serializable, Comparable<SafeText>

Models free-form text entered by the user, and protects your application from Cross Site Scripting (XSS).

Free-form text refers to text entered by the end user. It differs from other data in that its content is not tightly constrained. Examples of free-form text might include a user name, a description of something, a comment, and so on. If you model free-form text as a simple String, then when presenting that text in a web page, you must take special precautions against Cross Site Scripting attacks, by escaping special characters. When modeling such data as SafeText, however, such special steps are not needed, since the escaping is built directly into its toString() method.

It is worth noting that there are two defects with JSTL' s handling of this problem :

Using SafeText will protect you from both of these defects. Since the correct escaping is built into toString(), you may freely use JSP Expression Language, without needing to do any escaping in the view. Note that if you use <c:out> with SafeText (not recommeded), then you must use escapeXml='false' to avoid double-escaping of special characters.

There are various ways of presenting text :

Checking For Vulnerabilities Upon Startup

WEB4J will perform checks for Cross-Site Scripting vulnerabilities upon startup, by scanning your application's classes for public Model Objects having public getXXX methods that return a String. It will log such occurrences to encourage you to investigate them further.

Design Notes :
This class is final, immutable, Serializable, and Comparable, in imitation of the other building block classes such as String, Integer, and so on.

The reason why protection against Cross-Site Scripting is not implemented as a Servlet Filter is because a filter would have no means of distinguishing between safe and unsafe markup.

One might object to escaping special characters in the Model, instead of in the View. However, from a practical point of view, it seems more likely that the programmer will remember to use SafeText once in the Model, than remember to do the escaping repeatedly in the View.

See Also:
Serialized Form

Constructor Summary
SafeText(String aText)
Method Summary
 int compareTo(SafeText aThat)
 boolean equals(Object aThat)
static SafeText from(String aText)
          Factory method.
 String getJsonSafe()
          Return the text in a form safe for JSON (JavaScript Object Notation) data.
 String getRawString()
          Return the (trimmed) text passed to the constructor.
 String getXmlSafe()
          Return the text in a form safe for an XML element.
 int hashCode()
static boolean isEscaped(int aCodePoint)
          Returns true only if the given character is always escaped by toString().
 String toString()
          Return the text in a form safe for an HTML document.
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail


public SafeText(String aText)

aText - free-form text input by the end user, which may contain Cross Site Scripting attacks. Non-null. The text is trimmed by this constructor.
Method Detail


public static boolean isEscaped(int aCodePoint)
Returns true only if the given character is always escaped by toString(). For the list of characters, see EscapeChars.forHTML(String).

Recommended that your implementation of PermittedCharacters use this method. This will allow you to accept many special characters in your list of permissible characters.


public static SafeText from(String aText)
Factory method. Simply a slightly more compact way of building an object, as opposed to 'new'.


public String toString()
Return the text in a form safe for an HTML document. Passes the raw text through EscapeChars.forHTML(String).

toString in class Object


public String getRawString()
Return the (trimmed) text passed to the constructor.


public String getXmlSafe()
Return the text in a form safe for an XML element.

Arbitrary text can be rendered safely in an XML document in two ways :

This method will escape the above five special characters, and replace them with character entities, using EscapeChars.forXML(String)


public String getJsonSafe()
Return the text in a form safe for JSON (JavaScript Object Notation) data.

This method is intended for the data elements of JSON. It is intended for values of things, not for their names. Typically, only the values will come from end user input, while the names will be hard-coded.


public boolean equals(Object aThat)
equals in class Object


public int hashCode()
hashCode in class Object


public int compareTo(SafeText aThat)
Specified by:
compareTo in interface Comparable<SafeText>

Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.