org.apache.velocity.tools.generic

Class EscapeTool

java.lang.Object

org.apache.velocity.tools.generic.SafeConfig

org.apache.velocity.tools.generic.EscapeTool

All Implemented Interfaces:

Serializable

@DefaultKey(value="esc")
 @ValidScope(value="application")
public class EscapeTool
extends SafeConfig
implements Serializable

Tool for working with escaping in Velocity templates. It provides methods to escape outputs for Velocity, Java, JavaScript, HTML, HTTP, XML and SQL. Also provides methods to render VTL characters that otherwise needs escaping.

Example uses:

  $velocity                    -> Please escape $ and #!
  $esc.velocity($velocity)     -> Please escape ${esc.d} and ${esc.h}!

  $java                        -> He didn't say, "Stop!"
  $esc.java($java)             -> He didn't say, \"Stop!\"

  $javascript                  -> He didn't say, "Stop!"
  $esc.javascript($javascript) -> He didn\'t say, \"Stop!\"

  $html                        -> "bread" & "butter"
  $esc.html($html)             -> "bread" & "butter"

  $xml                         -> "bread" & "butter"
  $esc.xml($xml)               -> "bread" & "butter"

  $sql                         -> McHale's Navy
  $esc.sql($sql)               -> McHale''s Navy

  $url                         -> hello here & there
  $esc.url($url)               -> hello+here+%26+there
  $esc.unurl($esc.url($url))   -> hello here & there

  $esc.dollar                  -> $
  $esc.d                       -> $

  $esc.hash                    -> #
  $esc.h                       -> #

  $esc.backslash               -> \
  $esc.b                       -> \

  $esc.quote                   -> "
  $esc.q                       -> "

  $esc.singleQuote             -> '
  $esc.s                       -> '

  $esc.newline                 ->

  $esc.n                       ->


  $esc.exclamation             -> !
  $esc.e                       -> !
 

Example tools.xml config (if you want to use this with VelocityView):

 <tools>
   <toolbox scope="application">
     <tool class="org.apache.velocity.tools.generic.EscapeTool"/>
   </toolbox>
 </tools>
 

This tool is entirely threadsafe, and has no instance members. It may be used in any scope (request, session, or application).

Since:

VelocityTools 1.2

Version:

$Id: $

Author:

Shinobu Kawai

See Also:

StringEscapeUtils, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_KEY

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

Constructor Summary

Constructors

Constructor and Description
EscapeTool()

Method Summary

Modifier and Type	Method and Description
protected void	configure(ValueParser values) Does the actual configuration.
protected String	dumpString(String string, boolean key) This code was pulled from the Apache Harmony project.
String	getB() Renders a backslash (\).
String	getBackslash() Renders a backslash (\).
String	getD() Renders a dollar sign ($).
String	getDollar() Renders a dollar sign ($).
String	getE() Renders an exclamation mark (!).
String	getExclamation() Renders an exclamation mark (!).
String	getH() Renders a hash (#).
String	getHash() Renders a hash (#).
String	getKey() Should return the key under which this tool has been configured.
String	getN() Renders a new line character appropriate for the operating system ("\n" in java).
String	getNewline() Renders a new line character appropriate for the operating system ("\n" in java).
String	getQ() Renders a double quotation mark (").
String	getQuote() Renders a double quotation mark (").
String	getS() Renders a single quotation mark (').
String	getSingleQuote() Renders a single quotation mark (').
String	html(Object string) Escapes the characters in a String using HTML entities.
String	java(Object string) Escapes the characters in a String using Java String rules.
String	javascript(Object string) Escapes the characters in a String using JavaScript String rules.
String	propertyKey(Object string) Escapes the characters in a String using java.util.Properties rules for escaping property keys.
String	propertyValue(Object string) Escapes the characters in a String using java.util.Properties rules for escaping property values.
protected void	setKey(String key) Sets the key under which this tool has been configured.
String	sql(Object string) Escapes the characters in a String to be suitable to pass to an SQL query.
String	unicode(Object code) Converts the specified Unicode code point and/or escape sequence into the associated Unicode character.
String	unurl(Object string) Unscape the characters in a String encoded as an HTTP parameter value.
String	url(Object string) Escape the characters in a String to be suitable to use as an HTTP parameter value.
String	velocity(Object obj) Escapes the characters in a String using "poor man's escaping" for Velocity templates by replacing all '$' characters with '${esc.d}' and all '#' characters with '${esc.h}'.
String	xml(Object string) Escapes the characters in a String using XML entities.

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_KEY

public static final String DEFAULT_KEY

See Also:

Constant Field Values

Constructor Detail

EscapeTool

public EscapeTool()

Method Detail

configure

protected void configure(ValueParser values)

Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.

Overrides:

configure in class SafeConfig

Parameters:

values - configuration values

setKey

protected void setKey(String key)

Sets the key under which this tool has been configured.

Parameters:

key - tool key

See Also:

velocity(java.lang.Object)

getKey

public String getKey()

Should return the key under which this tool has been configured. The default is 'esc'.

Returns:

tool key

See Also:

velocity(java.lang.Object)

velocity

public String velocity(Object obj)

Escapes the characters in a String using "poor man's escaping" for Velocity templates by replacing all '$' characters with '${esc.d}' and all '#' characters with '${esc.h}'. This form of escaping is far more reliable and consistent than using '\' to escape valid references, directives and macros, though it does require that you have the EscapeTool available in the context when you later go to process the result returned by this method.

NOTE: This will only work so long as the EscapeTool is placed in the context using its default key 'esc' or you are using VelocityTools 2.0+ and have put this tool in one of your toolboxes under an alternate key (in which case the EscapeTool will automatically be told what its new key is). If for some strange reason you wish to use an alternate key and are not using the tool management facilities of VelocityTools 2.0+, you must subclass this tool and manually call setKey(String) before using this method.

Parameters:

obj - the string value that needs escaping

Returns:

String with escaped values, null if null string input

java

public String java(Object string)

Escapes the characters in a String using Java String rules.

Delegates the process to StringEscapeUtils.escapeJava(String).

Parameters:

string - the string to escape values, may be null

Returns:

String with escaped values, null if null string input

See Also:

StringEscapeUtils.escapeJava(String)

propertyKey

public String propertyKey(Object string)

Escapes the characters in a String using java.util.Properties rules for escaping property keys.

Parameters:

string - the string to escape values, may be null

Returns:

String with escaped values, null if null string input

See Also:

dumpString(String, boolean)

propertyValue

public String propertyValue(Object string)

Escapes the characters in a String using java.util.Properties rules for escaping property values.

Parameters:

string - the string to escape values, may be null

Returns:

String with escaped values, null if null string input

See Also:

dumpString(String, boolean)

dumpString

protected String dumpString(String string,
                            boolean key)

This code was pulled from the Apache Harmony project. See https://svn.apache.org/repos/asf/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Properties.java

Parameters:

string - property key or property value

key - true for a property key

Returns:

escaped string

javascript

public String javascript(Object string)

Escapes the characters in a String using JavaScript String rules.

Delegates the process to StringEscapeUtils.escapeEcmaScript(String).

Parameters:

string - the string to escape values, may be null

Returns:

String with escaped values, null if null string input

See Also:

StringEscapeUtils.escapeEcmaScript(String)

html

public String html(Object string)

Escapes the characters in a String using HTML entities.

Delegates the process to StringEscapeUtils.escapeHtml4(String).

Parameters:

string - the string to escape, may be null

Returns:

a new escaped String, null if null string input

See Also:

StringEscapeUtils.escapeHtml4(String)

url

public String url(Object string)

Escape the characters in a String to be suitable to use as an HTTP parameter value.

Uses UTF-8 as default character encoding.

Parameters:

string - the string to escape, may be null

Returns:

a new escaped String, null if null string input See java.net.URLEncoder#encode(String,String)

Since:

VelocityTools 1.3

unurl

public String unurl(Object string)

Unscape the characters in a String encoded as an HTTP parameter value.

Uses UTF-8 as default character encoding.

Parameters:

string - the string to unescape, may be null

Returns:

a new unescaped String, null if null string input

Since:

VelocityTools 3.0

See Also:

URLDecoder.decode(String,String)

xml

public String xml(Object string)

Escapes the characters in a String using XML entities.

Delegates the process to StringEscapeUtils.escapeXml(java.lang.String).

Parameters:

string - the string to escape, may be null

Returns:

a new escaped String, null if null string input

See Also:

StringEscapeUtils.escapeXml(String)

sql

public String sql(Object string)

Escapes the characters in a String to be suitable to pass to an SQL query.

It boils down to doubling single quotes.

Parameters:

string - the string to escape, may be null

Returns:

a new String, escaped for SQL, null if null string input

unicode

public String unicode(Object code)

Converts the specified Unicode code point and/or escape sequence into the associated Unicode character. This allows numeric code points or String versions of the numeric code point to be correctly translated within a template. This is especially useful for those creating unicode from a reference value, or injecting a unicode character into a template with a version of Velocity prior to 1.6.

Parameters:

code - the code to be translated/escaped, may be null

Returns:

the unicode character for that code, null if input was null

See Also:

Character.toChars(int codePoint)

getDollar

public String getDollar()

Renders a dollar sign ($).

Returns:

a dollar sign ($).

See Also:

getD()

getD

public String getD()

Renders a dollar sign ($).

Returns:

a dollar sign ($).

See Also:

getDollar()

getHash

public String getHash()

Renders a hash (#).

Returns:

a hash (#).

See Also:

getH()

getH

public String getH()

Renders a hash (#).

Returns:

a hash (#).

See Also:

getHash()

getBackslash

public String getBackslash()

Renders a backslash (\).

Returns:

a backslash (\).

See Also:

getB()

getB

public String getB()

Renders a backslash (\).

Returns:

a backslash (\).

See Also:

getBackslash()

getQuote

public String getQuote()

Renders a double quotation mark (").

Returns:

a double quotation mark (").

See Also:

getQ()

getQ

public String getQ()

Renders a double quotation mark (").

Returns:

a double quotation mark (").

See Also:

getQuote()

getSingleQuote

public String getSingleQuote()

Renders a single quotation mark (').

Returns:

a single quotation mark (').

See Also:

getS()

getS

public String getS()

Renders a single quotation mark (').

Returns:

a single quotation mark (').

See Also:

getSingleQuote()

getNewline

public String getNewline()

Renders a new line character appropriate for the operating system ("\n" in java).

Returns:

system newline string

See Also:

getN()

getN

public String getN()

Renders a new line character appropriate for the operating system ("\n" in java).

Returns:

system newline string

See Also:

getNewline()

getExclamation

public String getExclamation()

Renders an exclamation mark (!).

Returns:

an exclamation mark (!).

See Also:

getE()

getE

public String getE()

Renders an exclamation mark (!).

Returns:

an exclamation mark (!).

See Also:

getExclamation()