svn commit: r490474 - in /velocity/tools/trunk: src/java/org/apache/velocity/tools/generic/EscapeTool.java xdocs/generic/EscapeTool.xml

[cb...@apache.org]

Author: cbrisson
Date: Wed Dec 27 01:58:09 2006
New Revision: 490474

URL: http://svn.apache.org/viewvc?view=rev&rev=490474
Log:
added HTTP escaping abilities to the escape tool

Modified:
    velocity/tools/trunk/src/java/org/apache/velocity/tools/generic/EscapeTool.java
    velocity/tools/trunk/xdocs/generic/EscapeTool.xml

Modified: velocity/tools/trunk/src/java/org/apache/velocity/tools/generic/EscapeTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/java/org/apache/velocity/tools/generic/EscapeTool.java?view=diff&rev=490474&r1=490473&r2=490474
==============================================================================
--- velocity/tools/trunk/src/java/org/apache/velocity/tools/generic/EscapeTool.java (original)
+++ velocity/tools/trunk/src/java/org/apache/velocity/tools/generic/EscapeTool.java Wed Dec 27 01:58:09 2006
@@ -19,11 +19,14 @@
  * under the License.
  */
 
+import java.net.URLEncoder;
+import java.io.UnsupportedEncodingException;
+
 import org.apache.commons.lang.StringEscapeUtils;
 
 /**
  * Tool for working with escaping in Velocity templates.
- * It provides methods to escape outputs for Java, JavaScript, HTML, XML and SQL.
+ * It provides methods to escape outputs for Java, JavaScript, HTML, HTTP, XML and SQL.
  * Also provides methods to render VTL characters that otherwise needs escaping.
  *
  * <p><pre>
@@ -43,6 +46,9 @@
  *  $sql                         -> McHale's Navy
  *  $esc.sql($sql)               -> McHale''s Navy
  *
+ *  $http                        -> hello here & there
+ *  $esc.http                    -> hello+here+%26+there
+ *
  *  $esc.dollar                  -> $
  *  $esc.d                       -> $
  *
@@ -143,6 +149,26 @@
             return null;
         }
         return StringEscapeUtils.escapeHtml(String.valueOf(string));
+    }
+
+    /**
+     * Escape the characters in a <code>String</code> to be suitable to use as an HTTP parameter value.
+     * <br/>
+     * Uses UTF-8 as default character encoding.
+     * @param string the string to escape, may be null
+     * @return a new escaped <code>String</code>, <code>null</code> if null string input
+     *
+     * See java.net.URLEncoder#encode(String,String).
+     */
+    public String http(Object string) {
+        if (string == null) {
+            return null;
+        }
+        try {
+            return URLEncoder.encode(String.valueOf(string),"UTF-8");
+        } catch(UnsupportedEncodingException uee) {
+            return null;
+        }
     }
 
     /**

Modified: velocity/tools/trunk/xdocs/generic/EscapeTool.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/generic/EscapeTool.xml?view=diff&rev=490474&r1=490473&r2=490474
==============================================================================
--- velocity/tools/trunk/xdocs/generic/EscapeTool.xml (original)
+++ velocity/tools/trunk/xdocs/generic/EscapeTool.xml Wed Dec 27 01:58:09 2006
@@ -24,6 +24,7 @@
     <properties>
         <title>EscapeTool</title>
         <author email="shinobu@ieee.org">Shinobu Kawai</author>
+        <author email="claude.brisson@gmail.com">Claude Brisson</author>
         <projectfile>xdocs/generic/menu.xml</projectfile>
     </properties>
 
@@ -166,6 +167,43 @@
 
 <p>produces this output:</p>
 <sourcecode>&amp;quot;bread&amp;quot; &amp;amp; &amp;quot;butter&amp;quot;</sourcecode>
+            </description>
+
+        </method>
+    </section>
+
+    <section>
+        <method name="http()">
+            <abstract>
+                Escapes the characters in a <code>String</code> to be suitable to use as an HTTP parameter value.
+            </abstract>
+
+            <signature>
+                String http(Object string)
+            </signature>
+
+            <parameters>
+                <parameter name="string">
+                    the string to escape values, may be null.
+                </parameter>
+            </parameters>
+
+            <returns>
+                a new escaped <code>String</code>, <code>null</code> if null string input
+            </returns>
+
+            <description>
+                <p>Delegates the process to
+                <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/URLEncoder.html">java.net.URLEncoder#encodeURL(String,"UTF-8")</a>.
+                </p>
+                <p>If <code>$http</code> had the following value:</p>
+                <sourcecode>Hello here &amp; there</sourcecode>
+                <p>then the following Velocity script:</p>
+                <sourcecode>$esc.http($http)</sourcecode>
+
+                <p>produces this output:</p>
+                <sourcecode>hello+here+%26+there</sourcecode>
+
             </description>
 
         </method>