001: package org.apache.velocity.tools.generic;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.net.URLEncoder;
023: import java.io.UnsupportedEncodingException;
024:
025: import org.apache.commons.lang.StringEscapeUtils;
026:
027: /**
028: * Tool for working with escaping in Velocity templates.
029: * It provides methods to escape outputs for Java, JavaScript, HTML, HTTP, XML and SQL.
030: * Also provides methods to render VTL characters that otherwise needs escaping.
031: *
032: * <p><pre>
033: * Example uses:
034: * $java -> He didn't say, "Stop!"
035: * $esc.java($java) -> He didn't say, \"Stop!\"
036: *
037: * $javascript -> He didn't say, "Stop!"
038: * $esc.javascript($javascript) -> He didn\'t say, \"Stop!\"
039: *
040: * $html -> "bread" & "butter"
041: * $esc.html($html) -> &quot;bread&quot; &amp; &quot;butter&quot;
042: *
043: * $xml -> "bread" & "butter"
044: * $esc.xml($xml) -> &quot;bread&quot; &amp; &quot;butter&quot;
045: *
046: * $sql -> McHale's Navy
047: * $esc.sql($sql) -> McHale''s Navy
048: *
049: * $http -> hello here & there
050: * $esc.http -> hello+here+%26+there
051: *
052: * $esc.dollar -> $
053: * $esc.d -> $
054: *
055: * $esc.hash -> #
056: * $esc.h -> #
057: *
058: * $esc.backslash -> \
059: * $esc.b -> \
060: *
061: * $esc.quote -> "
062: * $esc.q -> "
063: *
064: * $esc.singleQuote -> '
065: * $esc.s -> '
066: *
067: * $esc.exclamation -> !
068: * $esc.e -> !
069: *
070: * Example toolbox.xml config (if you want to use this with VelocityView):
071: * <tool>
072: * <key>esc</key>
073: * <scope>application</scope>
074: * <class>org.apache.velocity.tools.generic.EscapeTool</class>
075: * </tool>
076: * </pre></p>
077: *
078: * <p>This tool is entirely threadsafe, and has no instance members.
079: * It may be used in any scope (request, session, or application).
080: * </p>
081: *
082: * @author <a href="mailto:shinobu@ieee.org">Shinobu Kawai</a>
083: * @version $Id: $
084: * @since VelocityTools 1.2
085: * @see StringEscapeUtils
086: */
087: public class EscapeTool {
088:
089: /**
090: * Default constructor.
091: */
092: public EscapeTool() {
093: }
094:
095: /**
096: * Escapes the characters in a <code>String</code> using Java String rules.
097: * <br />
098: * Delegates the process to {@link StringEscapeUtils#escapeJava(String)}.
099: *
100: * @param string the string to escape values, may be null
101: * @return String with escaped values, <code>null</code> if null string input
102: *
103: * @see StringEscapeUtils#escapeJava(String)
104: */
105: public String java(Object string) {
106: if (string == null) {
107: return null;
108: }
109: return StringEscapeUtils.escapeJava(String.valueOf(string));
110: }
111:
112: /**
113: * Escapes the characters in a <code>String</code> using JavaScript String rules.
114: * <br />
115: * Delegates the process to {@link StringEscapeUtils#escapeJavaScript(String)}.
116: *
117: * @param string the string to escape values, may be null
118: * @return String with escaped values, <code>null</code> if null string input
119: *
120: * @see StringEscapeUtils#escapeJavaScript(String)
121: */
122: public String javascript(Object string) {
123: if (string == null) {
124: return null;
125: }
126: return StringEscapeUtils.escapeJavaScript(String
127: .valueOf(string));
128: }
129:
130: /**
131: * Escapes the characters in a <code>String</code> using HTML entities.
132: * <br />
133: * Delegates the process to {@link StringEscapeUtils#escapeHtml(String)}.
134: *
135: * @param string the string to escape, may be null
136: * @return a new escaped <code>String</code>, <code>null</code> if null string input
137: *
138: * @see StringEscapeUtils#escapeHtml(String)
139: */
140: public String html(Object string) {
141: if (string == null) {
142: return null;
143: }
144: return StringEscapeUtils.escapeHtml(String.valueOf(string));
145: }
146:
147: /**
148: * Escape the characters in a <code>String</code> to be suitable to use as an HTTP parameter value.
149: * <br/>
150: * Uses UTF-8 as default character encoding.
151: * @param string the string to escape, may be null
152: * @return a new escaped <code>String</code>, <code>null</code> if null string input
153: *
154: * See java.net.URLEncoder#encode(String,String).
155: * @since VelocityTools 1.3
156: */
157: public String url(Object string) {
158: if (string == null) {
159: return null;
160: }
161: try {
162: return URLEncoder.encode(String.valueOf(string), "UTF-8");
163: } catch (UnsupportedEncodingException uee) {
164: return null;
165: }
166: }
167:
168: /**
169: * Escapes the characters in a <code>String</code> using XML entities.
170: * <br />
171: * Delegates the process to {@link StringEscapeUtils#escapeXml(String)}.
172: *
173: * @param string the string to escape, may be null
174: * @return a new escaped <code>String</code>, <code>null</code> if null string input
175: *
176: * @see StringEscapeUtils#escapeXml(String)
177: */
178: public String xml(Object string) {
179: if (string == null) {
180: return null;
181: }
182: return StringEscapeUtils.escapeXml(String.valueOf(string));
183: }
184:
185: /**
186: * Escapes the characters in a <code>String</code> to be suitable to pass to an SQL query.
187: * <br />
188: * Delegates the process to {@link StringEscapeUtils#escapeSql(String)}.
189: *
190: * @param string the string to escape, may be null
191: * @return a new String, escaped for SQL, <code>null</code> if null string input
192: *
193: * @see StringEscapeUtils#escapeSql(String)
194: */
195: public String sql(Object string) {
196: if (string == null) {
197: return null;
198: }
199: return StringEscapeUtils.escapeSql(String.valueOf(string));
200: }
201:
202: /**
203: * Renders a dollar sign ($).
204: * @return a dollar sign ($).
205: * @see #getD()
206: */
207: public String getDollar() {
208: return "$";
209: }
210:
211: /**
212: * Renders a dollar sign ($).
213: * @return a dollar sign ($).
214: * @see #getDollar()
215: */
216: public String getD() {
217: return this .getDollar();
218: }
219:
220: /**
221: * Renders a hash (#).
222: * @return a hash (#).
223: * @see #getH()
224: */
225: public String getHash() {
226: return "#";
227: }
228:
229: /**
230: * Renders a hash (#).
231: * @return a hash (#).
232: * @see #getHash()
233: */
234: public String getH() {
235: return this .getHash();
236: }
237:
238: /**
239: * Renders a backslash (\).
240: * @return a backslash (\).
241: * @see #getB()
242: */
243: public String getBackslash() {
244: return "\\";
245: }
246:
247: /**
248: * Renders a backslash (\).
249: * @return a backslash (\).
250: * @see #getBackslash()
251: */
252: public String getB() {
253: return this .getBackslash();
254: }
255:
256: /**
257: * Renders a double quotation mark (").
258: * @return a double quotation mark (").
259: * @see #getQ()
260: */
261: public String getQuote() {
262: return "\"";
263: }
264:
265: /**
266: * Renders a double quotation mark (").
267: * @return a double quotation mark (").
268: * @see #getQuote()
269: */
270: public String getQ() {
271: return this .getQuote();
272: }
273:
274: /**
275: * Renders a single quotation mark (').
276: * @return a single quotation mark (').
277: * @see #getS()
278: */
279: public String getSingleQuote() {
280: return "'";
281: }
282:
283: /**
284: * Renders a single quotation mark (').
285: * @return a single quotation mark (').
286: * @see #getSingleQuote()
287: */
288: public String getS() {
289: return this .getSingleQuote();
290: }
291:
292: /**
293: * Renders an exclamation mark (!).
294: * @return an exclamation mark (!).
295: * @see #getE()
296: */
297: public String getExclamation() {
298: return "!";
299: }
300:
301: /**
302: * Renders an exclamation mark (!).
303: * @return an exclamation mark (!).
304: * @see #getExclamation()
305: */
306: public String getE() {
307: return this.getExclamation();
308: }
309:
310: }
|