/** * Copyright (c) 2008, Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.android.mail.common.base; import static com.google.android.mail.common.base.Preconditions.checkNotNull; import static com.google.android.mail.common.base.Preconditions.checkPositionIndexes; import java.io.IOException; /** * An {@link Escaper} that converts literal text into a format safe for * inclusion in a particular context (such as an XML document). Typically (but * not always), the inverse process of "unescaping" the text is performed * automatically by the relevant parser. * *

For example, an XML escaper would convert the literal string {@code * "Foo"} into {@code "Foo<Bar>"} to prevent {@code ""} from * being confused with an XML tag. When the resulting XML document is parsed, * the parser API will return this text as the original literal string {@code * "Foo"}. * *

Note: This class is similar to {@link CharEscaper} but with one * very important difference. A CharEscaper can only process Java * UTF16 characters in * isolation and may not cope when it encounters surrogate pairs. This class * facilitates the correct escaping of all Unicode characters. * *

As there are important reasons, including potential security issues, to * handle Unicode correctly if you are considering implementing a new escaper * you should favor using UnicodeEscaper wherever possible. * *

A {@code UnicodeEscaper} instance is required to be stateless, and safe * when used concurrently by multiple threads. * *

Several popular escapers are defined as constants in the class {@link * CharEscapers}. To create your own escapers extend this class and implement * the {@link #escape(int)} method. * * @author dbeaumont@google.com (David Beaumont) */ public abstract class UnicodeEscaper extends Escaper { /** The amount of padding (chars) to use when growing the escape buffer. */ private static final int DEST_PAD = 32; /** * Returns the escaped form of the given Unicode code point, or {@code null} * if this code point does not need to be escaped. When called as part of an * escaping operation, the given code point is guaranteed to be in the range * {@code 0 <= cp <= Character#MAX_CODE_POINT}. * *

If an empty array is returned, this effectively strips the input * character from the resulting text. * *

If the character does not need to be escaped, this method should return * {@code null}, rather than an array containing the character representation * of the code point. This enables the escaping algorithm to perform more * efficiently. * *

If the implementation of this method cannot correctly handle a * particular code point then it should either throw an appropriate runtime * exception or return a suitable replacement character. It must never * silently discard invalid input as this may constitute a security risk. * * @param cp the Unicode code point to escape if necessary * @return the replacement characters, or {@code null} if no escaping was * needed */ protected abstract char[] escape(int cp); /** * Scans a sub-sequence of characters from a given {@link CharSequence}, * returning the index of the next character that requires escaping. * *

Note: When implementing an escaper, it is a good idea to override * this method for efficiency. The base class implementation determines * successive Unicode code points and invokes {@link #escape(int)} for each of * them. If the semantics of your escaper are such that code points in the * supplementary range are either all escaped or all unescaped, this method * can be implemented more efficiently using {@link CharSequence#charAt(int)}. * *

Note however that if your escaper does not escape characters in the * supplementary range, you should either continue to validate the correctness * of any surrogate characters encountered or provide a clear warning to users * that your escaper does not validate its input. * *

See {@link PercentEscaper} for an example. * * @param csq a sequence of characters * @param start the index of the first character to be scanned * @param end the index immediately after the last character to be scanned * @throws IllegalArgumentException if the scanned sub-sequence of {@code csq} * contains invalid surrogate pairs */ protected int nextEscapeIndex(CharSequence csq, int start, int end) { int index = start; while (index < end) { int cp = codePointAt(csq, index, end); if (cp < 0 || escape(cp) != null) { break; } index += Character.isSupplementaryCodePoint(cp) ? 2 : 1; } return index; } /** * Returns the escaped form of a given literal string. * *

If you are escaping input in arbitrary successive chunks, then it is not * generally safe to use this method. If an input string ends with an * unmatched high surrogate character, then this method will throw * {@link IllegalArgumentException}. You should either ensure your input is * valid UTF-16 before * calling this method or use an escaped {@link Appendable} (as returned by * {@link #escape(Appendable)}) which can cope with arbitrarily split input. * *

Note: When implementing an escaper it is a good idea to override * this method for efficiency by inlining the implementation of * {@link #nextEscapeIndex(CharSequence, int, int)} directly. Doing this for * {@link PercentEscaper} more than doubled the performance for unescaped * strings (as measured by {@link CharEscapersBenchmark}). * * @param string the literal string to be escaped * @return the escaped form of {@code string} * @throws NullPointerException if {@code string} is null * @throws IllegalArgumentException if invalid surrogate characters are * encountered */ @Override public String escape(String string) { checkNotNull(string); int end = string.length(); int index = nextEscapeIndex(string, 0, end); return index == end ? string : escapeSlow(string, index); } /** * Returns the escaped form of a given literal string, starting at the given * index. This method is called by the {@link #escape(String)} method when it * discovers that escaping is required. It is protected to allow subclasses * to override the fastpath escaping function to inline their escaping test. * See {@link CharEscaperBuilder} for an example usage. * *

This method is not reentrant and may only be invoked by the top level * {@link #escape(String)} method. * * @param s the literal string to be escaped * @param index the index to start escaping from * @return the escaped form of {@code string} * @throws NullPointerException if {@code string} is null * @throws IllegalArgumentException if invalid surrogate characters are * encountered */ protected final String escapeSlow(String s, int index) { int end = s.length(); // Get a destination buffer and setup some loop variables. char[] dest = Platform.charBufferFromThreadLocal(); int destIndex = 0; int unescapedChunkStart = 0; while (index < end) { int cp = codePointAt(s, index, end); if (cp < 0) { throw new IllegalArgumentException( "Trailing high surrogate at end of input"); } // It is possible for this to return null because nextEscapeIndex() may // (for performance reasons) yield some false positives but it must never // give false negatives. char[] escaped = escape(cp); int nextIndex = index + (Character.isSupplementaryCodePoint(cp) ? 2 : 1); if (escaped != null) { int charsSkipped = index - unescapedChunkStart; // This is the size needed to add the replacement, not the full // size needed by the string. We only regrow when we absolutely must. int sizeNeeded = destIndex + charsSkipped + escaped.length; if (dest.length < sizeNeeded) { int destLength = sizeNeeded + (end - index) + DEST_PAD; dest = growBuffer(dest, destIndex, destLength); } // If we have skipped any characters, we need to copy them now. if (charsSkipped > 0) { s.getChars(unescapedChunkStart, index, dest, destIndex); destIndex += charsSkipped; } if (escaped.length > 0) { System.arraycopy(escaped, 0, dest, destIndex, escaped.length); destIndex += escaped.length; } // If we dealt with an escaped character, reset the unescaped range. unescapedChunkStart = nextIndex; } index = nextEscapeIndex(s, nextIndex, end); } // Process trailing unescaped characters - no need to account for escaped // length or padding the allocation. int charsSkipped = end - unescapedChunkStart; if (charsSkipped > 0) { int endIndex = destIndex + charsSkipped; if (dest.length < endIndex) { dest = growBuffer(dest, destIndex, endIndex); } s.getChars(unescapedChunkStart, end, dest, destIndex); destIndex = endIndex; } return new String(dest, 0, destIndex); } /** * Returns an {@code Appendable} instance which automatically escapes all * text appended to it before passing the resulting text to an underlying * {@code Appendable}. * *

Unlike {@link #escape(String)} it is permitted to append arbitrarily * split input to this Appendable, including input that is split over a * surrogate pair. In this case the pending high surrogate character will not * be processed until the corresponding low surrogate is appended. This means * that a trailing high surrogate character at the end of the input cannot be * detected and will be silently ignored. This is unavoidable since the * Appendable interface has no {@code close()} method, and it is impossible to * determine when the last characters have been appended. * *

The methods of the returned object will propagate any exceptions thrown * by the underlying {@code Appendable}. * *

For well formed UTF-16 * the escaping behavior is identical to that of {@link #escape(String)} and * the following code is equivalent to (but much slower than) * {@code escaper.escape(string)}:

{@code
   *
   *   StringBuilder sb = new StringBuilder();
   *   escaper.escape(sb).append(string);
   *   return sb.toString();}
* * @param out the underlying {@code Appendable} to append escaped output to * @return an {@code Appendable} which passes text to {@code out} after * escaping it * @throws NullPointerException if {@code out} is null * @throws IllegalArgumentException if invalid surrogate characters are * encountered * * TODO(dbeaumont): Maybe return a Writer here so we have a close() method */ @Override public Appendable escape(final Appendable out) { checkNotNull(out); return new Appendable() { char pendingHighSurrogate = 0; @Override public Appendable append(CharSequence csq) throws IOException { return append(csq, 0, csq.length()); } @Override public Appendable append(CharSequence csq, int start, int end) throws IOException { checkNotNull(csq); checkPositionIndexes(start, end, csq.length()); // If there is a pending high surrogate, handle it and start at the // next character. if (pendingHighSurrogate != 0 && start < end) { completeSurrogatePair(csq.charAt(start++)); } if (start < end) { // If the string ends with a high surrogate, store it for the next // append, and skip that character from the current escaping. char last = csq.charAt(end - 1); if (Character.isHighSurrogate(last)) { pendingHighSurrogate = last; end--; } // Escape the subsequence from start to end, which cannot legally // contain an unpaired surrogate out.append(escape(csq.subSequence(start, end).toString())); } return this; } @Override public Appendable append(char c) throws IOException { if (pendingHighSurrogate != 0) { completeSurrogatePair(c); } else if (Character.isHighSurrogate(c)) { pendingHighSurrogate = c; } else { if (Character.isLowSurrogate(c)) { throw new IllegalArgumentException( "Unexpected low surrogate character '" + c + "' with value " + (int) c); } // This is a normal (non surrogate) char. char[] escaped = escape(c); if (escaped != null) { outputChars(escaped); } else { out.append(c); } } return this; } /** * Our last append operation ended halfway through a surrogate pair so we * complete the surrogate pair using {@code c}, which must be a low * surrogate. */ private void completeSurrogatePair(char c) throws IOException { if (!Character.isLowSurrogate(c)) { throw new IllegalArgumentException( "Expected low surrogate character but got '" + c + "' with value " + (int) c); } char[] escaped = escape( Character.toCodePoint(pendingHighSurrogate, c)); if (escaped != null) { outputChars(escaped); } else { out.append(pendingHighSurrogate); out.append(c); } pendingHighSurrogate = 0; } /** * Output some characters to the underlying appendable. */ private void outputChars(char[] chars) throws IOException { for (int n = 0; n < chars.length; n++) { out.append(chars[n]); } } }; } /** * Returns the Unicode code point of the character at the given index. * *

Unlike {@link Character#codePointAt(CharSequence, int)} or * {@link String#codePointAt(int)} this method will never fail silently when * encountering an invalid surrogate pair. * *

The behaviour of this method is as follows: *

    *
  1. If {@code index >= end}, {@link IndexOutOfBoundsException} is thrown. *
  2. If the character at the specified index is not a surrogate, it is * returned. *
  3. If the first character was a high surrogate value, then an attempt is * made to read the next character. *
      *
    1. If the end of the sequence was reached, the negated value of * the trailing high surrogate is returned. *
    2. If the next character was a valid low surrogate, the code point * value of the high/low surrogate pair is returned. *
    3. If the next character was not a low surrogate value, then * {@link IllegalArgumentException} is thrown. *
    *
  4. If the first character was a low surrogate value, * {@link IllegalArgumentException} is thrown. *
* * @param seq the sequence of characters from which to decode the code point * @param index the index of the first character to decode * @param end the index beyond the last valid character to decode * @return the Unicode code point for the given index or the negated value of * the trailing high surrogate character at the end of the sequence */ protected static final int codePointAt(CharSequence seq, int index, int end) { if (index < end) { char c1 = seq.charAt(index++); if (c1 < Character.MIN_HIGH_SURROGATE || c1 > Character.MAX_LOW_SURROGATE) { // Fast path (first test is probably all we need to do) return c1; } else if (c1 <= Character.MAX_HIGH_SURROGATE) { // If the high surrogate was the last character, return its inverse if (index == end) { return -c1; } // Otherwise look for the low surrogate following it char c2 = seq.charAt(index); if (Character.isLowSurrogate(c2)) { return Character.toCodePoint(c1, c2); } throw new IllegalArgumentException( "Expected low surrogate but got char '" + c2 + "' with value " + (int) c2 + " at index " + index); } else { throw new IllegalArgumentException( "Unexpected low surrogate character '" + c1 + "' with value " + (int) c1 + " at index " + (index - 1)); } } throw new IndexOutOfBoundsException("Index exceeds specified range"); } /** * Helper method to grow the character buffer as needed, this only happens * once in a while so it's ok if it's in a method call. If the index passed * in is 0 then no copying will be done. */ private static final char[] growBuffer(char[] dest, int index, int size) { char[] copy = new char[size]; if (index > 0) { System.arraycopy(dest, 0, copy, 0, index); } return copy; } }