1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.velocity.tools.generic;
18
19 import org.apache.commons.lang.StringEscapeUtils;
20
21 /***
22 * Tool for working with escaping in Velocity templates.
23 * It provides methods to escape outputs for Java, JavaScript, HTML, XML and SQL.
24 * Also provides methods to render VTL characters that otherwise needs escaping.
25 *
26 * <p><pre>
27 * Example uses:
28 * $java -> He didn't say, "Stop!"
29 * $esc.java($java) -> He didn't say, \"Stop!\"
30 *
31 * $javascript -> He didn't say, "Stop!"
32 * $esc.javascript($javascript) -> He didn\'t say, \"Stop!\"
33 *
34 * $html -> "bread" & "butter"
35 * $esc.html($html) -> &quot;bread&quot; &amp; &quot;butter&quot;
36 *
37 * $xml -> "bread" & "butter"
38 * $esc.xml($xml) -> &quot;bread&quot; &amp; &quot;butter&quot;
39 *
40 * $sql -> McHale's Navy
41 * $esc.sql($sql) -> McHale''s Navy
42 *
43 * $esc.dollar -> $
44 * $esc.d -> $
45 *
46 * $esc.hash -> #
47 * $esc.h -> #
48 *
49 * $esc.backslash -> \
50 * $esc.b -> \
51 *
52 * $esc.quote -> "
53 * $esc.q -> "
54 *
55 * $esc.singleQuote -> '
56 * $esc.s -> '
57 *
58 * $esc.exclamation -> !
59 * $esc.e -> !
60 *
61 * Example toolbox.xml config (if you want to use this with VelocityView):
62 * <tool>
63 * <key>esc</key>
64 * <scope>application</scope>
65 * <class>org.apache.velocity.tools.generic.EscapeTool</class>
66 * </tool>
67 * </pre></p>
68 *
69 * <p>This tool is entirely threadsafe, and has no instance members.
70 * It may be used in any scope (request, session, or application).
71 * </p>
72 *
73 * @author <a href="mailto:shinobu@ieee.org">Shinobu Kawai</a>
74 * @version $Id: $
75 *
76 * @see StringEscapeUtils
77 */
78 public class EscapeTool
79 {
80
81 /***
82 * Default constructor.
83 */
84 public EscapeTool()
85 {
86 }
87
88 /***
89 * Escapes the characters in a <code>String</code> using Java String rules.
90 * <br />
91 * Delegates the process to {@link StringEscapeUtils#escapeJava(String)}.
92 *
93 * @param string the string to escape values, may be null
94 * @return String with escaped values, <code>null</code> if null string input
95 *
96 * @see StringEscapeUtils#escapeJava(String)
97 */
98 public String java(Object string)
99 {
100 if (string == null)
101 {
102 return null;
103 }
104 return StringEscapeUtils.escapeJava(String.valueOf(string));
105 }
106
107 /***
108 * Escapes the characters in a <code>String</code> using JavaScript String rules.
109 * <br />
110 * Delegates the process to {@link StringEscapeUtils#escapeJavaScript(String)}.
111 *
112 * @param string the string to escape values, may be null
113 * @return String with escaped values, <code>null</code> if null string input
114 *
115 * @see StringEscapeUtils#escapeJavaScript(String)
116 */
117 public String javascript(Object string)
118 {
119 if (string == null)
120 {
121 return null;
122 }
123 return StringEscapeUtils.escapeJavaScript(String.valueOf(string));
124 }
125
126 /***
127 * Escapes the characters in a <code>String</code> using HTML entities.
128 * <br />
129 * Delegates the process to {@link StringEscapeUtils#escapeHtml(String)}.
130 *
131 * @param string the string to escape, may be null
132 * @return a new escaped <code>String</code>, <code>null</code> if null string input
133 *
134 * @see StringEscapeUtils#escapeHtml(String)
135 */
136 public String html(Object string)
137 {
138 if (string == null)
139 {
140 return null;
141 }
142 return StringEscapeUtils.escapeHtml(String.valueOf(string));
143 }
144
145 /***
146 * Escapes the characters in a <code>String</code> using XML entities.
147 * <br />
148 * Delegates the process to {@link StringEscapeUtils#escapeXml(String)}.
149 *
150 * @param string the string to escape, may be null
151 * @return a new escaped <code>String</code>, <code>null</code> if null string input
152 *
153 * @see StringEscapeUtils#escapeXml(String)
154 */
155 public String xml(Object string)
156 {
157 if (string == null)
158 {
159 return null;
160 }
161 return StringEscapeUtils.escapeXml(String.valueOf(string));
162 }
163
164 /***
165 * Escapes the characters in a <code>String</code> to be suitable to pass to an SQL query.
166 * <br />
167 * Delegates the process to {@link StringEscapeUtils#escapeSql(String)}.
168 *
169 * @param string the string to escape, may be null
170 * @return a new String, escaped for SQL, <code>null</code> if null string input
171 *
172 * @see StringEscapeUtils#escapeSql(String)
173 */
174 public String sql(Object string)
175 {
176 if (string == null)
177 {
178 return null;
179 }
180 return StringEscapeUtils.escapeSql(String.valueOf(string));
181 }
182
183 /***
184 * Renders a dollar sign ($).
185 * @return a dollar sign ($).
186 * @see #getD()
187 */
188 public String getDollar()
189 {
190 return "$";
191 }
192
193 /***
194 * Renders a dollar sign ($).
195 * @return a dollar sign ($).
196 * @see #getDollar()
197 */
198 public String getD()
199 {
200 return this.getDollar();
201 }
202
203 /***
204 * Renders a hash (#).
205 * @return a hash (#).
206 * @see #getH()
207 */
208 public String getHash()
209 {
210 return "#";
211 }
212
213 /***
214 * Renders a hash (#).
215 * @return a hash (#).
216 * @see #getHash()
217 */
218 public String getH()
219 {
220 return this.getHash();
221 }
222
223 /***
224 * Renders a backslash (\).
225 * @return a backslash (\).
226 * @see #getB()
227 */
228 public String getBackslash()
229 {
230 return "//";
231 }
232
233 /***
234 * Renders a backslash (\).
235 * @return a backslash (\).
236 * @see #getBackslash()
237 */
238 public String getB()
239 {
240 return this.getBackslash();
241 }
242
243 /***
244 * Renders a double quotation mark (").
245 * @return a double quotation mark (").
246 * @see #getQ()
247 */
248 public String getQuote()
249 {
250 return "\"";
251 }
252
253 /***
254 * Renders a double quotation mark (").
255 * @return a double quotation mark (").
256 * @see #getQuote()
257 */
258 public String getQ()
259 {
260 return this.getQuote();
261 }
262
263 /***
264 * Renders a single quotation mark (').
265 * @return a single quotation mark (').
266 * @see #getS()
267 */
268 public String getSingleQuote()
269 {
270 return "'";
271 }
272
273 /***
274 * Renders a single quotation mark (').
275 * @return a single quotation mark (').
276 * @see #getSingleQuote()
277 */
278 public String getS()
279 {
280 return this.getSingleQuote();
281 }
282
283 /***
284 * Renders an exclamation mark (!).
285 * @return an exclamation mark (!).
286 * @see #getE()
287 */
288 public String getExclamation()
289 {
290 return "!";
291 }
292
293 /***
294 * Renders an exclamation mark (!).
295 * @return an exclamation mark (!).
296 * @see #getExclamation()
297 */
298 public String getE()
299 {
300 return this.getExclamation();
301 }
302
303 }