Class EscapeTool
- java.lang.Object
-
- org.apache.velocity.tools.generic.SafeConfig
-
- org.apache.velocity.tools.generic.EscapeTool
-
@DefaultKey("esc") public class EscapeTool extends SafeConfig
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 -> hello+here+%26+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
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
DEFAULT_KEY
private java.lang.String
key
-
Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY
-
-
Constructor Summary
Constructors Constructor Description EscapeTool()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
configure(ValueParser values)
Does the actual configuration.protected java.lang.String
dumpString(java.lang.String string, boolean key)
This code was pulled from the Apache Harmony project.java.lang.String
getB()
Renders a backslash (\).java.lang.String
getBackslash()
Renders a backslash (\).java.lang.String
getD()
Renders a dollar sign ($).java.lang.String
getDollar()
Renders a dollar sign ($).java.lang.String
getE()
Renders an exclamation mark (!).java.lang.String
getExclamation()
Renders an exclamation mark (!).java.lang.String
getH()
Renders a hash (#).java.lang.String
getHash()
Renders a hash (#).java.lang.String
getKey()
Should return the key under which this tool has been configured.java.lang.String
getN()
Renders a new line character appropriate for the operating system ("\n" in java).java.lang.String
getNewline()
Renders a new line character appropriate for the operating system ("\n" in java).java.lang.String
getQ()
Renders a double quotation mark (").java.lang.String
getQuote()
Renders a double quotation mark (").java.lang.String
getS()
Renders a single quotation mark (').java.lang.String
getSingleQuote()
Renders a single quotation mark (').java.lang.String
html(java.lang.Object string)
Escapes the characters in aString
using HTML entities.java.lang.String
java(java.lang.Object string)
Escapes the characters in aString
using Java String rules.java.lang.String
javascript(java.lang.Object string)
Escapes the characters in aString
using JavaScript String rules.java.lang.String
propertyKey(java.lang.Object string)
Escapes the characters in aString
using java.util.Properties rules for escaping property keys.java.lang.String
propertyValue(java.lang.Object string)
Escapes the characters in aString
using java.util.Properties rules for escaping property values.protected void
setKey(java.lang.String key)
Sets the key under which this tool has been configured.java.lang.String
sql(java.lang.Object string)
Escapes the characters in aString
to be suitable to pass to an SQL query.java.lang.String
unicode(java.lang.Object code)
Converts the specified Unicode code point and/or escape sequence into the associated Unicode character.java.lang.String
url(java.lang.Object string)
Escape the characters in aString
to be suitable to use as an HTTP parameter value.java.lang.String
velocity(java.lang.Object obj)
Escapes the characters in aString
using "poor man's escaping" for Velocity templates by replacing all '$' characters with '${esc.d}' and all '#' characters with '${esc.h}'.java.lang.String
xml(java.lang.Object string)
Escapes the characters in aString
using XML entities.-
Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
-
-
-
-
Field Detail
-
DEFAULT_KEY
public static final java.lang.String DEFAULT_KEY
- See Also:
- Constant Field Values
-
key
private java.lang.String key
-
-
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 classSafeConfig
-
setKey
protected void setKey(java.lang.String key)
Sets the key under which this tool has been configured.- See Also:
velocity(java.lang.Object)
-
getKey
public java.lang.String getKey()
Should return the key under which this tool has been configured. The default is 'esc'.- See Also:
velocity(java.lang.Object)
-
velocity
public java.lang.String velocity(java.lang.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 java.lang.String java(java.lang.Object string)
Escapes the characters in aString
using Java String rules.
Delegates the process toStringEscapeUtils#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 java.lang.String propertyKey(java.lang.Object string)
Escapes the characters in aString
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 java.lang.String propertyValue(java.lang.Object string)
Escapes the characters in aString
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 java.lang.String dumpString(java.lang.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
-
javascript
public java.lang.String javascript(java.lang.Object string)
Escapes the characters in aString
using JavaScript String rules.
Delegates the process toStringEscapeUtils#escapeJavaScript(String)
.- Parameters:
string
- the string to escape values, may be null- Returns:
- String with escaped values,
null
if null string input - See Also:
StringEscapeUtils#escapeJavaScript(String)
-
html
public java.lang.String html(java.lang.Object string)
Escapes the characters in aString
using HTML entities.
Delegates the process toStringEscapeUtils#escapeHtml(String)
.- Parameters:
string
- the string to escape, may be null- Returns:
- a new escaped
String
,null
if null string input - See Also:
StringEscapeUtils#escapeHtml(String)
-
url
public java.lang.String url(java.lang.Object string)
Escape the characters in aString
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
-
xml
public java.lang.String xml(java.lang.Object string)
Escapes the characters in aString
using XML entities.
Delegates the process toStringEscapeUtils#escapeXml(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 java.lang.String sql(java.lang.Object string)
Escapes the characters in aString
to be suitable to pass to an SQL query.
Delegates the process toStringEscapeUtils#escapeSql(String)
.- Parameters:
string
- the string to escape, may be null- Returns:
- a new String, escaped for SQL,
null
if null string input - See Also:
StringEscapeUtils#escapeSql(String)
-
unicode
public java.lang.String unicode(java.lang.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 java.lang.String getDollar()
Renders a dollar sign ($).- Returns:
- a dollar sign ($).
- See Also:
getD()
-
getD
public java.lang.String getD()
Renders a dollar sign ($).- Returns:
- a dollar sign ($).
- See Also:
getDollar()
-
getHash
public java.lang.String getHash()
Renders a hash (#).- Returns:
- a hash (#).
- See Also:
getH()
-
getH
public java.lang.String getH()
Renders a hash (#).- Returns:
- a hash (#).
- See Also:
getHash()
-
getBackslash
public java.lang.String getBackslash()
Renders a backslash (\).- Returns:
- a backslash (\).
- See Also:
getB()
-
getB
public java.lang.String getB()
Renders a backslash (\).- Returns:
- a backslash (\).
- See Also:
getBackslash()
-
getQuote
public java.lang.String getQuote()
Renders a double quotation mark (").- Returns:
- a double quotation mark (").
- See Also:
getQ()
-
getQ
public java.lang.String getQ()
Renders a double quotation mark (").- Returns:
- a double quotation mark (").
- See Also:
getQuote()
-
getSingleQuote
public java.lang.String getSingleQuote()
Renders a single quotation mark (').- Returns:
- a single quotation mark (').
- See Also:
getS()
-
getS
public java.lang.String getS()
Renders a single quotation mark (').- Returns:
- a single quotation mark (').
- See Also:
getSingleQuote()
-
getNewline
public java.lang.String getNewline()
Renders a new line character appropriate for the operating system ("\n" in java).- See Also:
getN()
-
getN
public java.lang.String getN()
Renders a new line character appropriate for the operating system ("\n" in java).- See Also:
getNewline()
-
getExclamation
public java.lang.String getExclamation()
Renders an exclamation mark (!).- Returns:
- an exclamation mark (!).
- See Also:
getE()
-
getE
public java.lang.String getE()
Renders an exclamation mark (!).- Returns:
- an exclamation mark (!).
- See Also:
getExclamation()
-
-