This class is primarily used for creating URI escapers in UrlEscapers + * but can be used directly if required. While URI escapers impose + * specific semantics on which characters are considered 'safe', this class has + * a minimal set of restrictions. + * + *
When escaping a String, the following rules apply: + *
For performance reasons the only currently supported character encoding of + * this class is UTF-8. + * + *
Note: This escaper produces uppercase hexadecimal sequences. From
+ * RFC 3986:
+ * "URI producers and normalizers should use uppercase hexadecimal digits
+ * for all percent-encodings."
+ *
+ * @author David Beaumont
+ * @since 15.0
+ */
+public final class PercentEscaper extends UnicodeEscaper {
+
+ // In some escapers spaces are escaped to '+'
+ private static final char[] PLUS_SIGN = { '+' };
+
+ // Percent escapers output upper case hex digits (uri escapers require this).
+ private static final char[] UPPER_HEX_DIGITS =
+ "0123456789ABCDEF".toCharArray();
+
+ /**
+ * If true we should convert space to the {@code +} character.
+ */
+ private final boolean plusForSpace;
+
+ /**
+ * An array of flags where for any {@code char c} if {@code safeOctets[c]} is
+ * true then {@code c} should remain unmodified in the output. If
+ * {@code c > safeOctets.length} then it should be escaped.
+ */
+ private final boolean[] safeOctets;
+
+ /**
+ * Constructs a percent escaper with the specified safe characters and
+ * optional handling of the space character.
+ *
+ *
Not that it is allowed, but not necessarily desirable to specify {@code %} + * as a safe character. This has the effect of creating an escaper which has no + * well defined inverse but it can be useful when escaping additional characters. + * + * @param safeChars a non null string specifying additional safe characters + * for this escaper (the ranges 0..9, a..z and A..Z are always safe and + * should not be specified here) + * @param plusForSpace true if ASCII space should be escaped to {@code +} + * rather than {@code %20} + * @throws IllegalArgumentException if any of the parameters were invalid + */ + public PercentEscaper(String safeChars, boolean plusForSpace) { + // TODO(user): Switch to static factory methods for creation now that class is final. + // TODO(user): Support escapers where alphanumeric chars are not safe. + Preconditions.checkNotNull(safeChars); // eager for GWT. + // Avoid any misunderstandings about the behavior of this escaper + if (safeChars.matches(".*[0-9A-Za-z].*")) { + throw new IllegalArgumentException( + "Alphanumeric characters are always 'safe' and should not be " + + "explicitly specified"); + } + safeChars += "abcdefghijklmnopqrstuvwxyz" + + "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + + "0123456789"; + // Avoid ambiguous parameters. Safe characters are never modified so if + // space is a safe character then setting plusForSpace is meaningless. + if (plusForSpace && safeChars.contains(" ")) { + throw new IllegalArgumentException( + "plusForSpace cannot be specified when space is a 'safe' character"); + } + this.plusForSpace = plusForSpace; + this.safeOctets = createSafeOctets(safeChars); + } + + /** + * Creates a boolean array with entries corresponding to the character values + * specified in safeChars set to true. The array is as small as is required to + * hold the given character information. + */ + private static boolean[] createSafeOctets(String safeChars) { + int maxChar = -1; + char[] safeCharArray = safeChars.toCharArray(); + for (char c : safeCharArray) { + maxChar = Math.max(c, maxChar); + } + boolean[] octets = new boolean[maxChar + 1]; + for (char c : safeCharArray) { + octets[c] = true; + } + return octets; + } + + /* + * Overridden for performance. For unescaped strings this improved the + * performance of the uri escaper from ~760ns to ~400ns as measured by + * CharEscapersBenchmark. + */ + @Override + protected int nextEscapeIndex(CharSequence csq, int index, int end) { + Preconditions.checkNotNull(csq); + for (; index < end; index++) { + char c = csq.charAt(index); + if (c >= safeOctets.length || !safeOctets[c]) { + break; + } + } + return index; + } + + /* + * Overridden for performance. For unescaped strings this improved the + * performance of the uri escaper from ~400ns to ~170ns as measured by + * CharEscapersBenchmark. + */ + @Override + public String escape(String s) { + Preconditions.checkNotNull(s); + int slen = s.length(); + for (int index = 0; index < slen; index++) { + char c = s.charAt(index); + if (c >= safeOctets.length || !safeOctets[c]) { + return escapeSlow(s, index); + } + } + return s; + } + + /** + * Escapes the given Unicode code point in UTF-8. + */ + @Override + protected char[] escape(int cp) { + // We should never get negative values here but if we do it will throw an + // IndexOutOfBoundsException, so at least it will get spotted. + if (cp < safeOctets.length && safeOctets[cp]) { + return null; + } else if (cp == ' ' && plusForSpace) { + return PLUS_SIGN; + } else if (cp <= 0x7F) { + // Single byte UTF-8 characters + // Start with "%--" and fill in the blanks + char[] dest = new char[3]; + dest[0] = '%'; + dest[2] = UPPER_HEX_DIGITS[cp & 0xF]; + dest[1] = UPPER_HEX_DIGITS[cp >>> 4]; + return dest; + } else if (cp <= 0x7ff) { + // Two byte UTF-8 characters [cp >= 0x80 && cp <= 0x7ff] + // Start with "%--%--" and fill in the blanks + char[] dest = new char[6]; + dest[0] = '%'; + dest[3] = '%'; + dest[5] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[4] = UPPER_HEX_DIGITS[0x8 | (cp & 0x3)]; + cp >>>= 2; + dest[2] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[1] = UPPER_HEX_DIGITS[0xC | cp]; + return dest; + } else if (cp <= 0xffff) { + // Three byte UTF-8 characters [cp >= 0x800 && cp <= 0xffff] + // Start with "%E-%--%--" and fill in the blanks + char[] dest = new char[9]; + dest[0] = '%'; + dest[1] = 'E'; + dest[3] = '%'; + dest[6] = '%'; + dest[8] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[7] = UPPER_HEX_DIGITS[0x8 | (cp & 0x3)]; + cp >>>= 2; + dest[5] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[4] = UPPER_HEX_DIGITS[0x8 | (cp & 0x3)]; + cp >>>= 2; + dest[2] = UPPER_HEX_DIGITS[cp]; + return dest; + } else if (cp <= 0x10ffff) { + char[] dest = new char[12]; + // Four byte UTF-8 characters [cp >= 0xffff && cp <= 0x10ffff] + // Start with "%F-%--%--%--" and fill in the blanks + dest[0] = '%'; + dest[1] = 'F'; + dest[3] = '%'; + dest[6] = '%'; + dest[9] = '%'; + dest[11] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[10] = UPPER_HEX_DIGITS[0x8 | (cp & 0x3)]; + cp >>>= 2; + dest[8] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[7] = UPPER_HEX_DIGITS[0x8 | (cp & 0x3)]; + cp >>>= 2; + dest[5] = UPPER_HEX_DIGITS[cp & 0xF]; + cp >>>= 4; + dest[4] = UPPER_HEX_DIGITS[0x8 | (cp & 0x3)]; + cp >>>= 2; + dest[2] = UPPER_HEX_DIGITS[cp & 0x7]; + return dest; + } else { + // If this ever happens it is due to bug in UnicodeEscaper, not bad input. + throw new IllegalArgumentException( + "Invalid unicode character value " + cp); + } + } +} diff --git a/src/main/java/com/github/dockerjava/jaxrs/util/guava/UnicodeEscaper.java b/src/main/java/com/github/dockerjava/jaxrs/util/guava/UnicodeEscaper.java new file mode 100644 index 000000000..a58239484 --- /dev/null +++ b/src/main/java/com/github/dockerjava/jaxrs/util/guava/UnicodeEscaper.java @@ -0,0 +1,304 @@ +/* + * Copyright (C) 2008 The Guava Authors + * + * 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.github.dockerjava.jaxrs.util.guava; + + +import com.github.dockerjava.Preconditions; + +/** + * An 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 Note: This class is similar to 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 classes like
+ * com.google.common.html.HtmlEscapers, com.google.common.xml.XmlEscapers,
+ * and SourceCodeEscapers. To create
+ * your own escapers extend this class and implement the #escape(int)
+ * method.
+ *
+ * @author David Beaumont
+ * @since 15.0
+ */
+public 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}.
+ *
+ * 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 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 #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 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 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.
+ *
+ * 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
+ * IllegalArgumentException. You should ensure your input is valid UTF-16 before calling this
+ * method.
+ *
+ * Note: When implementing an escaper it is a good idea to override
+ * this method for efficiency by inlining the implementation of
+ * #nextEscapeIndex(CharSequence, int, int) directly. Doing this for
+ * com.google.common.net.PercentEscaper more than doubled the
+ * performance for unescaped strings (as measured by 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) {
+ Preconditions.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 #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 CharEscaperBuilder for an example usage.
+ *
+ * This method is not reentrant and may only be invoked by the top level
+ * #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.
+ *
+ * Unlike Character#codePointAt(CharSequence, int) or
+ * String#codePointAt(int) this method will never fail silently when
+ * encountering an invalid surrogate pair.
+ *
+ * The behaviour of this method is as follows:
+ *
+ *
+ *
+ * @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) {
+ Preconditions.checkNotNull(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) {
+ char[] copy = new char[size];
+ if (index > 0) {
+ System.arraycopy(dest, 0, copy, 0, index);
+ }
+ return copy;
+ }
+}
+ *
+ *