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)             -> &quot;bread&quot; &amp; &quot;butter&quot;

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

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

All Methods Instance Methods Concrete Methods
`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()`