Exposing the unescapeXml and escapeXml methods that take Writers - LANG-260. A recent thread did point out that there are problems with the concept of escaping Xml as a single method, and instead it needs to be an xml parser that escapes the body and the attribute content differently - however we're obviously not there yet and I don't think making the existing 80/20 good enough code more usable hurts.

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@412009 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/lang/StringEscapeUtils.java

@@ -559,6 +559,32 @@ public class StringEscapeUtils {
         Entities.HTML40.unescape(writer, string);
     }
 
+    /**
+     * <p>Escapes the characters in a <code>String</code> using XML entities.</p>
+     *
+     * <p>For example: <tt>"bread" & "butter"</tt> =>
+     * <tt>&amp;quot;bread&amp;quot; &amp;amp; &amp;quot;butter&amp;quot;</tt>.
+     * </p>
+     *
+     * <p>Supports only the five basic XML entities (gt, lt, quot, amp, apos).
+     * Does not support DTDs or external entities.</p>
+     *
+     * @param writer writer receiving the unescaped string
+     * @param str  the <code>String</code> to escape, may be null
+     * @return a new escaped <code>String</code>, <code>null</code> if null string input
+     * @see #unescapeXml(java.lang.String)
+     **/
+    public static void escapeXml(Writer writer, String str) throws IOException {
+        if (writer == null ) {
+            throw new IllegalArgumentException ("The Writer must not be null.");
+        }
+        
+        if (str == null) {
+            return;
+        }
+        Entities.XML.escape(writer, str);
+    }
+
     /**
      * <p>Escapes the characters in a <code>String</code> using XML entities.</p>
      *
@@ -580,6 +606,30 @@ public class StringEscapeUtils {
         return Entities.XML.escape(str);
     }
 
+    /**
+     * <p>Unescapes a string containing XML entity escapes to a string
+     * containing the actual Unicode characters corresponding to the
+     * escapes.</p>
+     *
+     * <p>Supports only the five basic XML entities (gt, lt, quot, amp, apos).
+     * Does not support DTDs or external entities.</p>
+     *
+     * @param writer writer receiving the unescaped string
+     * @param str  the <code>String</code> to unescape, may be null
+     * @return a new unescaped <code>String</code>, <code>null</code> if null string input
+     * @see #escapeXml(String)
+     **/
+    public static void unescapeXml(Writer writer, String str) throws IOException {
+        if (writer == null ) {
+            throw new IllegalArgumentException ("The Writer must not be null.");
+        }
+        
+        if (str == null) {
+            return;
+        }
+        Entities.XML.unescape(writer, str);
+    }
+
     /**
      * <p>Unescapes a string containing XML entity escapes to a string
      * containing the actual Unicode characters corresponding to the

src/test/org/apache/commons/lang/StringEscapeUtilsTest.java

@@ -290,6 +290,20 @@ public class StringEscapeUtilsTest extends TestCase {
         assertEquals("", StringEscapeUtils.escapeXml(""));
         assertEquals(null, StringEscapeUtils.escapeXml(null));
         assertEquals(null, StringEscapeUtils.unescapeXml(null));
+
+        StringWriter sw = new StringWriter();
+        try {
+            StringEscapeUtils.escapeXml(sw, "<abc>");
+        } catch (IOException e) {
+        }
+        assertEquals("XML was escaped incorrectly", "&lt;abc&gt;", sw.toString() );
+
+        sw = new StringWriter();
+        try {
+            StringEscapeUtils.unescapeXml(sw, "&lt;abc&gt;");
+        } catch (IOException e) {
+        }
+        assertEquals("XML was unescaped incorrectly", "<abc>", sw.toString() );
     }
 
     // SQL