Java tutorial
/* * Copyright (C) 2008 The Guava Authors * * Modifications copyright 2017 Daniel Sawano * * 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 se.sawano.java.security.otp.google.keyuri; import static org.apache.commons.lang3.Validate.notNull; /** * This class is derived from com.google.common.escape.UnicodeEscaper * * <p> * 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> * * <p>For example, an XML escaper would convert the literal string {@code * "Foo<Bar>"} into {@code "Foo<Bar>"} 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>Popular escapers are defined as constants in classes like * {@link com.google.common.html.HtmlEscapers} and {@link com.google.common.xml.XmlEscapers}. To * create your own escapers extend this class and implement the {@link #escape(int)} method. * * @author David Beaumont * @since 15.0 */ abstract class UnicodeEscaper { /** * The amount of padding (chars) to use when growing the escape buffer. */ private static final int DEST_PAD = 32; /** * Constructor for use by subclasses. */ protected UnicodeEscaper() { } /** * 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 com.google.common.net.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 ensure your input is valid * <a href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> before calling this method. * * <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 com.google.common.net.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) { notNull(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 = new char[1024]; 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 the Unicode code point of the character at the given index. * * <p>Unlike {@link Character#codePointAt(CharSequence, int)} or {@link String#codePointAt(int)} * this method will never fail silently when encountering an invalid surrogate pair. * * <p>The behaviour of this method is as follows: * <ol> * <li>If {@code index >= end}, {@link IndexOutOfBoundsException} is thrown. * <li><b>If the character at the specified index is not a surrogate, it is returned.</b> * <li>If the first character was a high surrogate value, then an attempt is made to read the next * character. * <ol> * <li><b>If the end of the sequence was reached, the negated value of the trailing high * surrogate is returned.</b> * <li><b>If the next character was a valid low surrogate, the code point value of the * high/low surrogate pair is returned.</b> * <li>If the next character was not a low surrogate value, then {@link * IllegalArgumentException} is thrown. * </ol> * <li>If the first character was a low surrogate value, {@link IllegalArgumentException} is * thrown. * </ol> * * @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 int codePointAt(CharSequence seq, int index, int end) { notNull(seq); 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 + " in '" + seq + "'"); } else { throw new IllegalArgumentException("Unexpected low surrogate character '" + c1 + "' with value " + (int) c1 + " at index " + (index - 1) + " in '" + seq + "'"); } } 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 char[] growBuffer(char[] dest, int index, int size) { if (size < 0) { // overflow - should be OutOfMemoryError but GWT/j2cl don't support it throw new AssertionError("Cannot increase internal buffer any further"); } char[] copy = new char[size]; if (index > 0) { System.arraycopy(dest, 0, copy, 0, index); } return copy; } }