Android 学习例子 源代码

/* 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.gdata.util.common.base; import static com.google.gdata.util.common.base.Preconditions.checkNotNull; 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. * * <p>For example, an XML escaper would convert the literal string {@code * "Foo<Bar>"} into {@code "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} 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<Bar>"}. * * <p><b>Note:</b> This class is similar to {@link CharEscaper} but with one * very important difference. A CharEscaper can only process Java * <a href="http://en.wikipedia.org/wiki/UTF-16">UTF16</a> characters in * isolation and may not cope when it encounters surrogate pairs. This class * facilitates the correct escaping of all Unicode characters. * * <p>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. * * <p>A {@code UnicodeEscaper} instance is required to be stateless, and safe * when used concurrently by multiple threads. * * <p>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. * * */ public abstract class UnicodeEscaper implements 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}. * * <p>If an empty array is returned, this effectively strips the input * character from the resulting text. * * <p>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. * * <p>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. * * <p><b>Note:</b> 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)}. * * <p>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. * * <p>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. * * <p>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 <a href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> before * calling this method or use an escaped {@link Appendable} (as returned by * {@link #escape(Appendable)}) which can cope with arbitrarily split input. * * <p><b>Note:</b> 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 */ public String escape(String 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. * * <p>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 = DEST_TL.get(); 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"); } char[] escaped = escape(cp); if (escaped != null) { int charsSkipped