1/* 2 * Copyright (C) 2006 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16package com.android.mail.lib.base; 17 18import static com.android.mail.lib.base.Preconditions.checkNotNull; 19 20import java.io.IOException; 21 22/** 23 * An object that converts literal text into a format safe for inclusion in a particular context 24 * (such as an XML document). Typically (but not always), the inverse process of "unescaping" the 25 * text is performed automatically by the relevant parser. 26 * 27 * <p>For example, an XML escaper would convert the literal string {@code "Foo<Bar>"} into {@code 28 * "Foo<Bar>"} to prevent {@code "<Bar>"} from being confused with an XML tag. When the 29 * resulting XML document is parsed, the parser API will return this text as the original literal 30 * string {@code "Foo<Bar>"}. 31 * 32 * <p>A {@code CharEscaper} instance is required to be stateless, and safe when used concurrently by 33 * multiple threads. 34 * 35 * <p>Several popular escapers are defined as constants in the class {@link CharEscapers}. To create 36 * your own escapers, use {@link CharEscaperBuilder}, or extend this class and implement the {@link 37 * #escape(char)} method. 38 * 39 * @author sven@google.com (Sven Mawson) 40 */ 41public abstract class CharEscaper extends Escaper { 42 /** 43 * Returns the escaped form of a given literal string. 44 * 45 * @param string the literal string to be escaped 46 * @return the escaped form of {@code string} 47 * @throws NullPointerException if {@code string} is null 48 */ 49 @Override public String escape(String string) { 50 checkNotNull(string); 51 // Inlineable fast-path loop which hands off to escapeSlow() only if needed 52 int length = string.length(); 53 for (int index = 0; index < length; index++) { 54 if (escape(string.charAt(index)) != null) { 55 return escapeSlow(string, index); 56 } 57 } 58 return string; 59 } 60 61 /** 62 * Returns an {@code Appendable} instance which automatically escapes all text appended to it 63 * before passing the resulting text to an underlying {@code Appendable}. 64 * 65 * <p>The methods of the returned object will propagate any exceptions thrown by the underlying 66 * {@code Appendable}, and will throw {@link NullPointerException} if asked to append {@code 67 * null}, but do not otherwise throw any exceptions. 68 * 69 * <p>The escaping behavior is identical to that of {@link #escape(String)}, so the following code 70 * is always equivalent to {@code escaper.escape(string)}: <pre> {@code 71 * 72 * StringBuilder sb = new StringBuilder(); 73 * escaper.escape(sb).append(string); 74 * return sb.toString();}</pre> 75 * 76 * @param out the underlying {@code Appendable} to append escaped output to 77 * @return an {@code Appendable} which passes text to {@code out} after escaping it 78 * @throws NullPointerException if {@code out} is null. 79 */ 80 @Override public Appendable escape(final Appendable out) { 81 checkNotNull(out); 82 83 return new Appendable() { 84 @Override public Appendable append(CharSequence csq) throws IOException { 85 out.append(escape(csq.toString())); 86 return this; 87 } 88 89 @Override public Appendable append(CharSequence csq, int start, int end) throws IOException { 90 out.append(escape(csq.subSequence(start, end).toString())); 91 return this; 92 } 93 94 @Override public Appendable append(char c) throws IOException { 95 char[] escaped = escape(c); 96 if (escaped == null) { 97 out.append(c); 98 } else { 99 for (char e : escaped) { 100 out.append(e); 101 } 102 } 103 return this; 104 } 105 }; 106 } 107 108 /** 109 * Returns the escaped form of a given literal string, starting at the given index. This method is 110 * called by the {@link #escape(String)} method when it discovers that escaping is required. It is 111 * protected to allow subclasses to override the fastpath escaping function to inline their 112 * escaping test. See {@link CharEscaperBuilder} for an example usage. 113 * 114 * @param s the literal string to be escaped 115 * @param index the index to start escaping from 116 * @return the escaped form of {@code string} 117 * @throws NullPointerException if {@code string} is null 118 */ 119 protected String escapeSlow(String s, int index) { 120 int slen = s.length(); 121 122 // Get a destination buffer and setup some loop variables. 123 char[] dest = Platform.charBufferFromThreadLocal(); 124 int destSize = dest.length; 125 int destIndex = 0; 126 int lastEscape = 0; 127 128 // Loop through the rest of the string, replacing when needed into the 129 // destination buffer, which gets grown as needed as well. 130 for (; index < slen; index++) { 131 132 // Get a replacement for the current character. 133 char[] r = escape(s.charAt(index)); 134 135 // If no replacement is needed, just continue. 136 if (r == null) continue; 137 138 int rlen = r.length; 139 int charsSkipped = index - lastEscape; 140 141 // This is the size needed to add the replacement, not the full size needed by the string. We 142 // only regrow when we absolutely must. 143 int sizeNeeded = destIndex + charsSkipped + rlen; 144 if (destSize < sizeNeeded) { 145 destSize = sizeNeeded + (slen - index) + DEST_PAD; 146 dest = growBuffer(dest, destIndex, destSize); 147 } 148 149 // If we have skipped any characters, we need to copy them now. 150 if (charsSkipped > 0) { 151 s.getChars(lastEscape, index, dest, destIndex); 152 destIndex += charsSkipped; 153 } 154 155 // Copy the replacement string into the dest buffer as needed. 156 if (rlen > 0) { 157 System.arraycopy(r, 0, dest, destIndex, rlen); 158 destIndex += rlen; 159 } 160 lastEscape = index + 1; 161 } 162 163 // Copy leftover characters if there are any. 164 int charsLeft = slen - lastEscape; 165 if (charsLeft > 0) { 166 int sizeNeeded = destIndex + charsLeft; 167 if (destSize < sizeNeeded) { 168 169 // Regrow and copy, expensive! No padding as this is the final copy. 170 dest = growBuffer(dest, destIndex, sizeNeeded); 171 } 172 s.getChars(lastEscape, slen, dest, destIndex); 173 destIndex = sizeNeeded; 174 } 175 return new String(dest, 0, destIndex); 176 } 177 178 /** 179 * Returns the escaped form of the given character, or {@code null} if this character does not 180 * need to be escaped. If an empty array is returned, this effectively strips the input character 181 * from the resulting text. 182 * 183 * <p>If the character does not need to be escaped, this method should return {@code null}, rather 184 * than a one-character array containing the character itself. This enables the escaping algorithm 185 * to perform more efficiently. 186 * 187 * <p>An escaper is expected to be able to deal with any {@code char} value, so this method should 188 * not throw any exceptions. 189 * 190 * @param c the character to escape if necessary 191 * @return the replacement characters, or {@code null} if no escaping was needed 192 */ 193 protected abstract char[] escape(char c); 194 195 /** 196 * Helper method to grow the character buffer as needed, this only happens once in a while so it's 197 * ok if it's in a method call. If the index passed in is 0 then no copying will be done. 198 */ 199 private static char[] growBuffer(char[] dest, int index, int size) { 200 char[] copy = new char[size]; 201 if (index > 0) { 202 System.arraycopy(dest, 0, copy, 0, index); 203 } 204 return copy; 205 } 206 207 /** 208 * The amount of padding to use when growing the escape buffer. 209 */ 210 private static final int DEST_PAD = 32; 211}