Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 2D652200D69 for ; Tue, 12 Dec 2017 15:34:03 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id 2B59C160BFC; Tue, 12 Dec 2017 14:34:03 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id A5F18160C2C for ; Tue, 12 Dec 2017 15:34:00 +0100 (CET) Received: (qmail 93340 invoked by uid 500); 12 Dec 2017 14:33:59 -0000 Mailing-List: contact notifications-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list notifications@commons.apache.org Received: (qmail 93320 invoked by uid 99); 12 Dec 2017 14:33:59 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 12 Dec 2017 14:33:59 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id 6F61C3A07F1 for ; Tue, 12 Dec 2017 14:33:56 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1022144 [14/19] - in /websites/production/commons/content/proper/commons-text/javadocs/api-release: ./ org/apache/commons/text/ org/apache/commons/text/class-use/ org/apache/commons/text/diff/ org/apache/commons/text/diff/class-use/ org/ap... Date: Tue, 12 Dec 2017 14:33:52 -0000 To: notifications@commons.apache.org From: chtompki@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20171212143356.6F61C3A07F1@svn01-us-west.apache.org> archived-at: Tue, 12 Dec 2017 14:34:03 -0000 Modified: websites/production/commons/content/proper/commons-text/javadocs/api-release/src-html/org/apache/commons/text/StringEscapeUtils.Builder.html ============================================================================== --- websites/production/commons/content/proper/commons-text/javadocs/api-release/src-html/org/apache/commons/text/StringEscapeUtils.Builder.html (original) +++ websites/production/commons/content/proper/commons-text/javadocs/api-release/src-html/org/apache/commons/text/StringEscapeUtils.Builder.html Tue Dec 12 14:33:51 2017 @@ -69,7 +69,7 @@ 061 */ 062 public static final CharSequenceTranslator ESCAPE_JAVA; 063 static { -064 Map<CharSequence, CharSequence> escapeJavaMap = new HashMap<>(); +064 final Map<CharSequence, CharSequence> escapeJavaMap = new HashMap<>(); 065 escapeJavaMap.put("\"", "\\\""); 066 escapeJavaMap.put("\\", "\\\\"); 067 ESCAPE_JAVA = new AggregateTranslator( @@ -88,7 +88,7 @@ 080 */ 081 public static final CharSequenceTranslator ESCAPE_ECMASCRIPT; 082 static { -083 Map<CharSequence, CharSequence> escapeEcmaScriptMap = new HashMap<>(); +083 final Map<CharSequence, CharSequence> escapeEcmaScriptMap = new HashMap<>(); 084 escapeEcmaScriptMap.put("'", "\\'"); 085 escapeEcmaScriptMap.put("\"", "\\\""); 086 escapeEcmaScriptMap.put("\\", "\\\\"); @@ -109,7 +109,7 @@ 101 */ 102 public static final CharSequenceTranslator ESCAPE_JSON; 103 static { -104 Map<CharSequence, CharSequence> escapeJsonMap = new HashMap<>(); +104 final Map<CharSequence, CharSequence> escapeJsonMap = new HashMap<>(); 105 escapeJsonMap.put("\"", "\\\""); 106 escapeJsonMap.put("\\", "\\\\"); 107 escapeJsonMap.put("/", "\\/"); @@ -129,7 +129,7 @@ 121 */ 122 public static final CharSequenceTranslator ESCAPE_XML10; 123 static { -124 Map<CharSequence, CharSequence> escapeXml10Map = new HashMap<>(); +124 final Map<CharSequence, CharSequence> escapeXml10Map = new HashMap<>(); 125 escapeXml10Map.put("\u0000", StringUtils.EMPTY); 126 escapeXml10Map.put("\u0001", StringUtils.EMPTY); 127 escapeXml10Map.put("\u0002", StringUtils.EMPTY); @@ -180,7 +180,7 @@ 172 */ 173 public static final CharSequenceTranslator ESCAPE_XML11; 174 static { -175 Map<CharSequence, CharSequence> escapeXml11Map = new HashMap<>(); +175 final Map<CharSequence, CharSequence> escapeXml11Map = new HashMap<>(); 176 escapeXml11Map.put("\u0000", StringUtils.EMPTY); 177 escapeXml11Map.put("\u000b", ""); 178 escapeXml11Map.put("\u000c", ""); @@ -241,7 +241,7 @@ 233 */ 234 public static final CharSequenceTranslator ESCAPE_XSI; 235 static { -236 Map<CharSequence, CharSequence> escapeXsiMap = new HashMap<>(); +236 final Map<CharSequence, CharSequence> escapeXsiMap = new HashMap<>(); 237 escapeXsiMap.put("|", "\\|"); 238 escapeXsiMap.put("&", "\\&"); 239 escapeXsiMap.put(";", "\\;"); @@ -281,7 +281,7 @@ 273 */ 274 public static final CharSequenceTranslator UNESCAPE_JAVA; 275 static { -276 Map<CharSequence, CharSequence> unescapeJavaMap = new HashMap<>(); +276 final Map<CharSequence, CharSequence> unescapeJavaMap = new HashMap<>(); 277 unescapeJavaMap.put("\\\\", "\\"); 278 unescapeJavaMap.put("\\\"", "\""); 279 unescapeJavaMap.put("\\'", "'"); @@ -310,569 +310,576 @@ 302 * object allows the Json unescaping functionality to be used 303 * as the foundation for a custom translator. 304 */ -305 public static final CharSequenceTranslator UNESCAPE_JSON = UNESCAPE_JAVA; -306 -307 /** -308 * Translator object for unescaping escaped HTML 3.0. -309 * -310 * While {@link #unescapeHtml3(String)} is the expected method of use, this -311 * object allows the HTML unescaping functionality to be used -312 * as the foundation for a custom translator. -313 */ -314 public static final CharSequenceTranslator UNESCAPE_HTML3 = -315 new AggregateTranslator( -316 new LookupTranslator(EntityArrays.BASIC_UNESCAPE), -317 new LookupTranslator(EntityArrays.ISO8859_1_UNESCAPE), -318 new NumericEntityUnescaper() -319 ); -320 -321 /** -322 * Translator object for unescaping escaped HTML 4.0. -323 * -324 * While {@link #unescapeHtml4(String)} is the expected method of use, this -325 * object allows the HTML unescaping functionality to be used -326 * as the foundation for a custom translator. -327 */ -328 public static final CharSequenceTranslator UNESCAPE_HTML4 = -329 new AggregateTranslator( -330 new LookupTranslator(EntityArrays.BASIC_UNESCAPE), -331 new LookupTranslator(EntityArrays.ISO8859_1_UNESCAPE), -332 new LookupTranslator(EntityArrays.HTML40_EXTENDED_UNESCAPE), -333 new NumericEntityUnescaper() -334 ); -335 -336 /** -337 * Translator object for unescaping escaped XML. -338 * -339 * While {@link #unescapeXml(String)} is the expected method of use, this -340 * object allows the XML unescaping functionality to be used -341 * as the foundation for a custom translator. -342 */ -343 public static final CharSequenceTranslator UNESCAPE_XML = -344 new AggregateTranslator( -345 new LookupTranslator(EntityArrays.BASIC_UNESCAPE), -346 new LookupTranslator(EntityArrays.APOS_UNESCAPE), -347 new NumericEntityUnescaper() -348 ); -349 -350 /** -351 * Translator object for unescaping escaped Comma Separated Value entries. -352 * -353 * While {@link #unescapeCsv(String)} is the expected method of use, this -354 * object allows the CSV unescaping functionality to be used -355 * as the foundation for a custom translator. -356 */ -357 public static final CharSequenceTranslator UNESCAPE_CSV = new CsvTranslators.CsvUnescaper(); -358 -359 /** -360 * Translator object for unescaping escaped XSI Value entries. -361 * -362 * While {@link #unescapeXSI(String)} is the expected method of use, this -363 * object allows the XSI unescaping functionality to be used -364 * as the foundation for a custom translator. -365 */ -366 public static final CharSequenceTranslator UNESCAPE_XSI = new XsiUnescaper(); -367 -368 /** -369 * Translator object for unescaping backslash escaped entries. -370 */ -371 static class XsiUnescaper extends CharSequenceTranslator { -372 -373 /** -374 * Escaped backslash constant. -375 */ -376 private static final char BACKSLASH = '\\'; -377 -378 @Override -379 public int translate(final CharSequence input, final int index, final Writer out) throws IOException { -380 -381 if (index != 0) { -382 throw new IllegalStateException("XsiUnescaper should never reach the [1] index"); -383 } +305 public static final CharSequenceTranslator UNESCAPE_JSON; +306 static { +307 UNESCAPE_JSON = new AggregateTranslator( +308 new OctalUnescaper(), // .between('\1', '\377'), +309 new UnicodeUnescaper(), +310 new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_UNESCAPE) +311 ); +312 } +313 +314 /** +315 * Translator object for unescaping escaped HTML 3.0. +316 * +317 * While {@link #unescapeHtml3(String)} is the expected method of use, this +318 * object allows the HTML unescaping functionality to be used +319 * as the foundation for a custom translator. +320 */ +321 public static final CharSequenceTranslator UNESCAPE_HTML3 = +322 new AggregateTranslator( +323 new LookupTranslator(EntityArrays.BASIC_UNESCAPE), +324 new LookupTranslator(EntityArrays.ISO8859_1_UNESCAPE), +325 new NumericEntityUnescaper() +326 ); +327 +328 /** +329 * Translator object for unescaping escaped HTML 4.0. +330 * +331 * While {@link #unescapeHtml4(String)} is the expected method of use, this +332 * object allows the HTML unescaping functionality to be used +333 * as the foundation for a custom translator. +334 */ +335 public static final CharSequenceTranslator UNESCAPE_HTML4 = +336 new AggregateTranslator( +337 new LookupTranslator(EntityArrays.BASIC_UNESCAPE), +338 new LookupTranslator(EntityArrays.ISO8859_1_UNESCAPE), +339 new LookupTranslator(EntityArrays.HTML40_EXTENDED_UNESCAPE), +340 new NumericEntityUnescaper() +341 ); +342 +343 /** +344 * Translator object for unescaping escaped XML. +345 * +346 * While {@link #unescapeXml(String)} is the expected method of use, this +347 * object allows the XML unescaping functionality to be used +348 * as the foundation for a custom translator. +349 */ +350 public static final CharSequenceTranslator UNESCAPE_XML = +351 new AggregateTranslator( +352 new LookupTranslator(EntityArrays.BASIC_UNESCAPE), +353 new LookupTranslator(EntityArrays.APOS_UNESCAPE), +354 new NumericEntityUnescaper() +355 ); +356 +357 /** +358 * Translator object for unescaping escaped Comma Separated Value entries. +359 * +360 * While {@link #unescapeCsv(String)} is the expected method of use, this +361 * object allows the CSV unescaping functionality to be used +362 * as the foundation for a custom translator. +363 */ +364 public static final CharSequenceTranslator UNESCAPE_CSV = new CsvTranslators.CsvUnescaper(); +365 +366 /** +367 * Translator object for unescaping escaped XSI Value entries. +368 * +369 * While {@link #unescapeXSI(String)} is the expected method of use, this +370 * object allows the XSI unescaping functionality to be used +371 * as the foundation for a custom translator. +372 */ +373 public static final CharSequenceTranslator UNESCAPE_XSI = new XsiUnescaper(); +374 +375 /** +376 * Translator object for unescaping backslash escaped entries. +377 */ +378 static class XsiUnescaper extends CharSequenceTranslator { +379 +380 /** +381 * Escaped backslash constant. +382 */ +383 private static final char BACKSLASH = '\\'; 384 -385 String s = input.toString(); -386 -387 int segmentStart = 0; -388 int searchOffset = 0; -389 while (true) { -390 int pos = s.indexOf(BACKSLASH, searchOffset); -391 if (pos == -1) { -392 if (segmentStart < s.length()) { -393 out.write(s.substring(segmentStart)); -394 } -395 break; -396 } -397 if (pos > segmentStart) { -398 out.write(s.substring(segmentStart, pos)); -399 } -400 segmentStart = pos + 1; -401 searchOffset = pos + 2; -402 } -403 -404 return Character.codePointCount(input, 0, input.length()); -405 } -406 } -407 -408 /* Helper functions */ -409 -410 /** -411 * {@code StringEscapeUtils} instances should NOT be constructed in -412 * standard programming. -413 * -414 * Instead, the class should be used as: -415 * <pre>StringEscapeUtils.escapeJava("foo");</pre> -416 * -417 * This constructor is public to permit tools that require a JavaBean -418 * instance to operate. -419 */ -420 public StringEscapeUtils() { -421 super(); -422 } -423 -424 /** -425 * Convenience wrapper for {@link java.lang.StringBuilder} providing escape methods. -426 * -427 * Example: -428 * <pre> -429 * new Builder(ESCAPE_HTML4) -430 * .append("") -431 * .escape("This is paragraph 1 and special chars like & get escaped.") -432 * .append("") -433 * .escape("This is paragraph 2 & more...") -434 * .append("") -435 * .toString() -436 * </pre> -437 * -438 */ -439 public static final class Builder { -440 -441 /** -442 * StringBuilder to be used in the Builder class. -443 */ -444 private final StringBuilder sb; -445 -446 /** -447 * CharSequenceTranslator to be used in the Builder class. -448 */ -449 private final CharSequenceTranslator translator; -450 -451 /** -452 * Builder constructor. -453 * -454 * @param translator a CharSequenceTranslator. +385 @Override +386 public int translate(final CharSequence input, final int index, final Writer out) throws IOException { +387 +388 if (index != 0) { +389 throw new IllegalStateException("XsiUnescaper should never reach the [1] index"); +390 } +391 +392 final String s = input.toString(); +393 +394 int segmentStart = 0; +395 int searchOffset = 0; +396 while (true) { +397 final int pos = s.indexOf(BACKSLASH, searchOffset); +398 if (pos == -1) { +399 if (segmentStart < s.length()) { +400 out.write(s.substring(segmentStart)); +401 } +402 break; +403 } +404 if (pos > segmentStart) { +405 out.write(s.substring(segmentStart, pos)); +406 } +407 segmentStart = pos + 1; +408 searchOffset = pos + 2; +409 } +410 +411 return Character.codePointCount(input, 0, input.length()); +412 } +413 } +414 +415 /* Helper functions */ +416 +417 /** +418 * {@code StringEscapeUtils} instances should NOT be constructed in +419 * standard programming. +420 * +421 * Instead, the class should be used as: +422 * <pre>StringEscapeUtils.escapeJava("foo");</pre> +423 * +424 * This constructor is public to permit tools that require a JavaBean +425 * instance to operate. +426 */ +427 public StringEscapeUtils() { +428 super(); +429 } +430 +431 /** +432 * Convenience wrapper for {@link java.lang.StringBuilder} providing escape methods. +433 * +434 * Example: +435 * <pre> +436 * new Builder(ESCAPE_HTML4) +437 * .append("") +438 * .escape("This is paragraph 1 and special chars like & get escaped.") +439 * .append("") +440 * .escape("This is paragraph 2 & more...") +441 * .append("") +442 * .toString() +443 * </pre> +444 * +445 */ +446 public static final class Builder { +447 +448 /** +449 * StringBuilder to be used in the Builder class. +450 */ +451 private final StringBuilder sb; +452 +453 /** +454 * CharSequenceTranslator to be used in the Builder class. 455 */ -456 private Builder(final CharSequenceTranslator translator) { -457 this.sb = new StringBuilder(); -458 this.translator = translator; -459 } -460 -461 /** -462 * Escape {@code input} according to the given {@link CharSequenceTranslator}. -463 * -464 * @param input the String to escape -465 * @return {@code this}, to enable chaining -466 */ -467 public Builder escape(final String input) { -468 sb.append(translator.translate(input)); -469 return this; -470 } -471 -472 /** -473 * Literal append, no escaping being done. -474 * -475 * @param input the String to append -476 * @return {@code this}, to enable chaining -477 */ -478 public Builder append(final String input) { -479 sb.append(input); -480 return this; -481 } -482 -483 /** -484 * Return the escaped string. -485 * -486 * @return the escaped string -487 */ -488 @Override -489 public String toString() { -490 return sb.toString(); -491 } -492 } -493 -494 /** -495 * Get a {@link Builder}. -496 * @param translator the text translator -497 * @return {@link Builder} -498 */ -499 public static StringEscapeUtils.Builder builder(final CharSequenceTranslator translator) { -500 return new Builder(translator); -501 } -502 -503 // Java and JavaScript -504 //-------------------------------------------------------------------------- -505 /** -506 * Escapes the characters in a {@code String} using Java String rules. -507 * -508 * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) -509 * -510 * So a tab becomes the characters {@code '\\'} and -511 * {@code 't'}. -512 * -513 * The only difference between Java strings and JavaScript strings -514 * is that in JavaScript, a single quote and forward-slash (/) are escaped. -515 * -516 * Example: -517 * <pre> -518 * input string: He didn't say, "Stop!" -519 * output string: He didn't say, \"Stop!\" -520 * </pre> -521 * -522 * @param input String to escape values in, may be null -523 * @return String with escaped values, {@code null} if null string input -524 */ -525 public static final String escapeJava(final String input) { -526 return ESCAPE_JAVA.translate(input); -527 } -528 -529 /** -530 * Escapes the characters in a {@code String} using EcmaScript String rules. -531 * Escapes any values it finds into their EcmaScript String form. -532 * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) -533 * -534 * So a tab becomes the characters {@code '\\'} and -535 * {@code 't'}. -536 * -537 * The only difference between Java strings and EcmaScript strings -538 * is that in EcmaScript, a single quote and forward-slash (/) are escaped. -539 * -540 * Note that EcmaScript is best known by the JavaScript and ActionScript dialects. -541 * -542 * Example: -543 * <pre> -544 * input string: He didn't say, "Stop!" -545 * output string: He didn\'t say, \"Stop!\" -546 * </pre> -547 * -548 * Security Note. We only provide backslash escaping in this method. For example, {@code '\"'} has the output -549 * {@code '\\\"'} which could result in potential issues in the case where the string being escaped is being used -550 * in an HTML tag like {@code <select onmouseover="..." />}. If you wish to have more rigorous string escaping, you -551 * may consider the -552 * <a href="https://www.owasp.org/index.php/Category:OWASP_Enterprise_Security_API_JAVA">ESAPI Libraries</a>. -553 * Further, you can view the <a href="https://github.com/esapi">ESAPI GitHub Org</a>. +456 private final CharSequenceTranslator translator; +457 +458 /** +459 * Builder constructor. +460 * +461 * @param translator a CharSequenceTranslator. +462 */ +463 private Builder(final CharSequenceTranslator translator) { +464 this.sb = new StringBuilder(); +465 this.translator = translator; +466 } +467 +468 /** +469 * Escape {@code input} according to the given {@link CharSequenceTranslator}. +470 * +471 * @param input the String to escape +472 * @return {@code this}, to enable chaining +473 */ +474 public Builder escape(final String input) { +475 sb.append(translator.translate(input)); +476 return this; +477 } +478 +479 /** +480 * Literal append, no escaping being done. +481 * +482 * @param input the String to append +483 * @return {@code this}, to enable chaining +484 */ +485 public Builder append(final String input) { +486 sb.append(input); +487 return this; +488 } +489 +490 /** +491 * Return the escaped string. +492 * +493 * @return the escaped string +494 */ +495 @Override +496 public String toString() { +497 return sb.toString(); +498 } +499 } +500 +501 /** +502 * Get a {@link Builder}. +503 * @param translator the text translator +504 * @return {@link Builder} +505 */ +506 public static StringEscapeUtils.Builder builder(final CharSequenceTranslator translator) { +507 return new Builder(translator); +508 } +509 +510 // Java and JavaScript +511 //-------------------------------------------------------------------------- +512 /** +513 * Escapes the characters in a {@code String} using Java String rules. +514 * +515 * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) +516 * +517 * So a tab becomes the characters {@code '\\'} and +518 * {@code 't'}. +519 * +520 * The only difference between Java strings and JavaScript strings +521 * is that in JavaScript, a single quote and forward-slash (/) are escaped. +522 * +523 * Example: +524 * <pre> +525 * input string: He didn't say, "Stop!" +526 * output string: He didn't say, \"Stop!\" +527 * </pre> +528 * +529 * @param input String to escape values in, may be null +530 * @return String with escaped values, {@code null} if null string input +531 */ +532 public static final String escapeJava(final String input) { +533 return ESCAPE_JAVA.translate(input); +534 } +535 +536 /** +537 * Escapes the characters in a {@code String} using EcmaScript String rules. +538 * Escapes any values it finds into their EcmaScript String form. +539 * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) +540 * +541 * So a tab becomes the characters {@code '\\'} and +542 * {@code 't'}. +543 * +544 * The only difference between Java strings and EcmaScript strings +545 * is that in EcmaScript, a single quote and forward-slash (/) are escaped. +546 * +547 * Note that EcmaScript is best known by the JavaScript and ActionScript dialects. +548 * +549 * Example: +550 * <pre> +551 * input string: He didn't say, "Stop!" +552 * output string: He didn\'t say, \"Stop!\" +553 * </pre> 554 * -555 * @param input String to escape values in, may be null -556 * @return String with escaped values, {@code null} if null string input -557 */ -558 public static final String escapeEcmaScript(final String input) { -559 return ESCAPE_ECMASCRIPT.translate(input); -560 } -561 -562 /** -563 * Escapes the characters in a {@code String} using Json String rules. -564 * Escapes any values it finds into their Json String form. -565 * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) -566 * -567 * So a tab becomes the characters {@code '\\'} and -568 * {@code 't'}. -569 * -570 * The only difference between Java strings and Json strings -571 * is that in Json, forward-slash (/) is escaped. -572 * -573 * See http://www.ietf.org/rfc/rfc4627.txt for further details. -574 * -575 * Example: -576 * <pre> -577 * input string: He didn't say, "Stop!" -578 * output string: He didn't say, \"Stop!\" -579 * </pre> -580 * -581 * @param input String to escape values in, may be null -582 * @return String with escaped values, {@code null} if null string input -583 */ -584 public static final String escapeJson(final String input) { -585 return ESCAPE_JSON.translate(input); -586 } -587 -588 /** -589 * Unescapes any Java literals found in the {@code String}. -590 * For example, it will turn a sequence of {@code '\'} and -591 * {@code 'n'} into a newline character, unless the {@code '\'} -592 * is preceded by another {@code '\'}. -593 * -594 * @param input the {@code String} to unescape, may be null -595 * @return a new unescaped {@code String}, {@code null} if null string input -596 */ -597 public static final String unescapeJava(final String input) { -598 return UNESCAPE_JAVA.translate(input); -599 } -600 -601 /** -602 * Unescapes any EcmaScript literals found in the {@code String}. -603 * -604 * For example, it will turn a sequence of {@code '\'} and {@code 'n'} -605 * into a newline character, unless the {@code '\'} is preceded by another -606 * {@code '\'}. -607 * -608 * @see #unescapeJava(String) -609 * @param input the {@code String} to unescape, may be null -610 * @return A new unescaped {@code String}, {@code null} if null string input -611 */ -612 public static final String unescapeEcmaScript(final String input) { -613 return UNESCAPE_ECMASCRIPT.translate(input); -614 } -615 -616 /** -617 * Unescapes any Json literals found in the {@code String}. -618 * -619 * For example, it will turn a sequence of {@code '\'} and {@code 'n'} -620 * into a newline character, unless the {@code '\'} is preceded by another -621 * {@code '\'}. -622 * -623 * @see #unescapeJava(String) -624 * @param input the {@code String} to unescape, may be null -625 * @return A new unescaped {@code String}, {@code null} if null string input -626 */ -627 public static final String unescapeJson(final String input) { -628 return UNESCAPE_JSON.translate(input); -629 } -630 -631 // HTML and XML -632 //-------------------------------------------------------------------------- -633 /** -634 * Escapes the characters in a {@code String} using HTML entities. -635 * -636 * -637 * For example: -638 * -639 * <code>"bread" & "butter"</code> -640 * becomes: -641 * -642 * <code>&quot;bread&quot; &amp; &quot;butter&quot;</code>. -643 * -644 * -645 * Supports all known HTML 4.0 entities, including funky accents. -646 * Note that the commonly used apostrophe escape character (&apos;) -647 * is not a legal entity and so is not supported). -648 * -649 * @param input the {@code String} to escape, may be null -650 * @return a new escaped {@code String}, {@code null} if null string input +555 * Security Note. We only provide backslash escaping in this method. For example, {@code '\"'} has the output +556 * {@code '\\\"'} which could result in potential issues in the case where the string being escaped is being used +557 * in an HTML tag like {@code <select onmouseover="..." />}. If you wish to have more rigorous string escaping, you +558 * may consider the +559 * <a href="https://www.owasp.org/index.php/Category:OWASP_Enterprise_Security_API_JAVA">ESAPI Libraries</a>. +560 * Further, you can view the <a href="https://github.com/esapi">ESAPI GitHub Org</a>. +561 * +562 * @param input String to escape values in, may be null +563 * @return String with escaped values, {@code null} if null string input +564 */ +565 public static final String escapeEcmaScript(final String input) { +566 return ESCAPE_ECMASCRIPT.translate(input); +567 } +568 +569 /** +570 * Escapes the characters in a {@code String} using Json String rules. +571 * Escapes any values it finds into their Json String form. +572 * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) +573 * +574 * So a tab becomes the characters {@code '\\'} and +575 * {@code 't'}. +576 * +577 * The only difference between Java strings and Json strings +578 * is that in Json, forward-slash (/) is escaped. +579 * +580 * See http://www.ietf.org/rfc/rfc4627.txt for further details. +581 * +582 * Example: +583 * <pre> +584 * input string: He didn't say, "Stop!" +585 * output string: He didn't say, \"Stop!\" +586 * </pre> +587 * +588 * @param input String to escape values in, may be null +589 * @return String with escaped values, {@code null} if null string input +590 */ +591 public static final String escapeJson(final String input) { +592 return ESCAPE_JSON.translate(input); +593 } +594 +595 /** +596 * Unescapes any Java literals found in the {@code String}. +597 * For example, it will turn a sequence of {@code '\'} and +598 * {@code 'n'} into a newline character, unless the {@code '\'} +599 * is preceded by another {@code '\'}. +600 * +601 * @param input the {@code String} to unescape, may be null +602 * @return a new unescaped {@code String}, {@code null} if null string input +603 */ +604 public static final String unescapeJava(final String input) { +605 return UNESCAPE_JAVA.translate(input); +606 } +607 +608 /** +609 * Unescapes any EcmaScript literals found in the {@code String}. +610 * +611 * For example, it will turn a sequence of {@code '\'} and {@code 'n'} +612 * into a newline character, unless the {@code '\'} is preceded by another +613 * {@code '\'}. +614 * +615 * @see #unescapeJava(String) +616 * @param input the {@code String} to unescape, may be null +617 * @return A new unescaped {@code String}, {@code null} if null string input +618 */ +619 public static final String unescapeEcmaScript(final String input) { +620 return UNESCAPE_ECMASCRIPT.translate(input); +621 } +622 +623 /** +624 * Unescapes any Json literals found in the {@code String}. +625 * +626 * For example, it will turn a sequence of {@code '\'} and {@code 'n'} +627 * into a newline character, unless the {@code '\'} is preceded by another +628 * {@code '\'}. +629 * +630 * @see #unescapeJava(String) +631 * @param input the {@code String} to unescape, may be null +632 * @return A new unescaped {@code String}, {@code null} if null string input +633 */ +634 public static final String unescapeJson(final String input) { +635 return UNESCAPE_JSON.translate(input); +636 } +637 +638 // HTML and XML +639 //-------------------------------------------------------------------------- +640 /** +641 * Escapes the characters in a {@code String} using HTML entities. +642 * +643 * +644 * For example: +645 * +646 * <code>"bread" & "butter"</code> +647 * becomes: +648 * +649 * <code>&quot;bread&quot; &amp; &quot;butter&quot;</code>. +650 * 651 * -652 * @see <a href="http://hotwired.lycos.com/webmonkey/reference/special_characters/">ISO Entities</a> -653 * @see <a href="http://www.w3.org/TR/REC-html32#latin1">HTML 3.2 Character Entities for ISO Latin-1</a> -654 * @see <a href="http://www.w3.org/TR/REC-html40/sgml/entities.html">HTML 4.0 Character entity references</a> -655 * @see <a href="http://www.w3.org/TR/html401/charset.html#h-5.3">HTML 4.01 Character References</a> -656 * @see <a href="http://www.w3.org/TR/html401/charset.html#code-position">HTML 4.01 Code positions</a> -657 */ -658 public static final String escapeHtml4(final String input) { -659 return ESCAPE_HTML4.translate(input); -660 } -661 -662 /** -663 * Escapes the characters in a {@code String} using HTML entities. -664 * Supports only the HTML 3.0 entities. -665 * -666 * @param input the {@code String} to escape, may be null -667 * @return a new escaped {@code String}, {@code null} if null string input -668 */ -669 public static final String escapeHtml3(final String input) { -670 return ESCAPE_HTML3.translate(input); -671 } -672 -673 //----------------------------------------------------------------------- -674 /** -675 * Unescapes a string containing entity escapes to a string -676 * containing the actual Unicode characters corresponding to the -677 * escapes. Supports HTML 4.0 entities. -678 * -679 * For example, the string {@code "<Français>"} -680 * will become {@code "<Franï¿½ais>"} -681 * -682 * If an entity is unrecognized, it is left alone, and inserted -683 * verbatim into the result string. e.g. {@code ">&zzzz;x"} will -684 * become {@code ">&zzzz;x"}. +652 * Supports all known HTML 4.0 entities, including funky accents. +653 * Note that the commonly used apostrophe escape character (&apos;) +654 * is not a legal entity and so is not supported). +655 * +656 * @param input the {@code String} to escape, may be null +657 * @return a new escaped {@code String}, {@code null} if null string input +658 * +659 * @see <a href="http://hotwired.lycos.com/webmonkey/reference/special_characters/">ISO Entities</a> +660 * @see <a href="http://www.w3.org/TR/REC-html32#latin1">HTML 3.2 Character Entities for ISO Latin-1</a> +661 * @see <a href="http://www.w3.org/TR/REC-html40/sgml/entities.html">HTML 4.0 Character entity references</a> +662 * @see <a href="http://www.w3.org/TR/html401/charset.html#h-5.3">HTML 4.01 Character References</a> +663 * @see <a href="http://www.w3.org/TR/html401/charset.html#code-position">HTML 4.01 Code positions</a> +664 */ +665 public static final String escapeHtml4(final String input) { +666 return ESCAPE_HTML4.translate(input); +667 } +668 +669 /** +670 * Escapes the characters in a {@code String} using HTML entities. +671 * Supports only the HTML 3.0 entities. +672 * +673 * @param input the {@code String} to escape, may be null +674 * @return a new escaped {@code String}, {@code null} if null string input +675 */ +676 public static final String escapeHtml3(final String input) { +677 return ESCAPE_HTML3.translate(input); +678 } +679 +680 //----------------------------------------------------------------------- +681 /** +682 * Unescapes a string containing entity escapes to a string +683 * containing the actual Unicode characters corresponding to the +684 * escapes. Supports HTML 4.0 entities. 685 * -686 * @param input the {@code String} to unescape, may be null -687 * @return a new unescaped {@code String}, {@code null} if null string input -688 */ -689 public static final String unescapeHtml4(final String input) { -690 return UNESCAPE_HTML4.translate(input); -691 } -692 -693 /** -694 * Unescapes a string containing entity escapes to a string -695 * containing the actual Unicode characters corresponding to the -696 * escapes. Supports only HTML 3.0 entities. -697 * -698 * @param input the {@code String} to unescape, may be null -699 * @return a new unescaped {@code String}, {@code null} if null string input -700 */ -701 public static final String unescapeHtml3(final String input) { -702 return UNESCAPE_HTML3.translate(input); -703 } -704 -705 /** -706 * Escapes the characters in a {@code String} using XML entities. -707 * -708 * For example: {@code "bread" & "butter"} => -709 * {@code "bread" & "butter"}. -710 * -711 * -712 * Note that XML 1.0 is a text-only format: it cannot represent control -713 * characters or unpaired Unicode surrogate codepoints, even after escaping. -714 * {@code escapeXml10} will remove characters that do not fit in the -715 * following ranges: -716 * -717 * {@code #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]} +686 * For example, the string {@code "<Français>"} +687 * will become {@code "<Franï¿½ais>"} +688 * +689 * If an entity is unrecognized, it is left alone, and inserted +690 * verbatim into the result string. e.g. {@code ">&zzzz;x"} will +691 * become {@code ">&zzzz;x"}. +692 * +693 * @param input the {@code String} to unescape, may be null +694 * @return a new unescaped {@code String}, {@code null} if null string input +695 */ +696 public static final String unescapeHtml4(final String input) { +697 return UNESCAPE_HTML4.translate(input); +698 } +699 +700 /** +701 * Unescapes a string containing entity escapes to a string +702 * containing the actual Unicode characters corresponding to the +703 * escapes. Supports only HTML 3.0 entities. +704 * +705 * @param input the {@code String} to unescape, may be null +706 * @return a new unescaped {@code String}, {@code null} if null string input +707 */ +708 public static final String unescapeHtml3(final String input) { +709 return UNESCAPE_HTML3.translate(input); +710 } +711 +712 /** +713 * Escapes the characters in a {@code String} using XML entities. +714 * +715 * For example: {@code "bread" & "butter"} => [... 308 lines stripped ...]