Charset.java revision cb8d09e94846d073ee7b50bef89c0b33113697fb
1adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Licensed to the Apache Software Foundation (ASF) under one or more 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contributor license agreements. See the NOTICE file distributed with 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this work for additional information regarding copyright ownership. 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The ASF licenses this file to You under the Apache License, Version 2.0 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (the "License"); you may not use this file except in compliance with 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the License. You may obtain a copy of the License at 8adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 10adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Unless required by applicable law or agreed to in writing, software 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See the License for the specific language governing permissions and 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitations under the License. 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.nio.charset; 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 20ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughesimport com.ibm.icu4jni.charset.NativeConverter; 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.BufferedReader; 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.IOException; 23adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.InputStream; 24adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.io.InputStreamReader; 25adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.net.URL; 26adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.nio.ByteBuffer; 27adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.nio.CharBuffer; 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.nio.charset.spi.CharsetProvider; 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.security.AccessController; 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.security.PrivilegedAction; 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Collections; 32adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Comparator; 33adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Enumeration; 34adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.HashMap; 35adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.HashSet; 36adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Iterator; 37adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Locale; 38bcf7c66e617ad0c33bb320184bb2401def517342Elliott Hughesimport java.util.Map; 39cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughesimport java.util.ServiceLoader; 40adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.Set; 41adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.SortedMap; 42adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectimport java.util.TreeMap; 43adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 44adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 45c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * A charset is a named mapping between Unicode characters and byte sequences. Every 46c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * {@code Charset} can <i>decode</i>, converting a byte sequence into a sequence of characters, 47c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * and some can also <i>encode</i>, converting a sequence of characters into a byte sequence. 48c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Use the method {@link #canEncode} to find out whether a charset supports both. 49c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * 50c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <h4>Characters</h4> 51c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>In the context of this class, <i>character</i> always refers to a Java character: a Unicode 52c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * code point in the range U+0000 to U+FFFF. (Java represents supplementary characters using surrogates.) 53c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Not all byte sequences will represent a character, and not 54c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * all characters can necessarily be represented by a given charset. The method {@link #contains} 55c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * can be used to determine whether every character representable by one charset can also be 56c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * represented by another (meaning that a lossless transformation is possible from the contained 57c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * to the container). 58c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * 59c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <h4>Encodings</h4> 60c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>There are many possible ways to represent Unicode characters as byte sequences. 61c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * See <a href="http://www.unicode.org/reports/tr17/">UTR#17: Unicode Character Encoding Model</a> 62c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * for detailed discussion. 63c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 64c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>The most important mappings capable of representing every character are the Unicode 65c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Transformation Format (UTF) charsets. Of those, UTF-8 and the UTF-16 family are the most 66c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * common. UTF-8 (described in <a href="http://www.ietf.org/rfc/rfc3629.txt">RFC 3629</a>) 67c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * encodes a character using 1 to 4 bytes. UTF-16 uses exactly 2 bytes per character (potentially 68c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * wasting space, but allowing efficient random access into BMP text), and UTF-32 uses 69c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * exactly 4 bytes per character (trading off even more space for efficient random access into text 70c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * that includes supplementary characters). 71c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 72c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>UTF-16 and UTF-32 encode characters directly, using their code point as a two- or four-byte 73c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * integer. This means that any given UTF-16 or UTF-32 byte sequence is either big- or 74c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * little-endian. To assist decoders, Unicode includes a special <i>byte order mark</i> (BOM) 75c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * character U+FEFF used to determine the endianness of a sequence. The corresponding byte-swapped 76c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * code point U+FFFE is guaranteed never to be assigned. If a UTF-16 decoder sees 77c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * {@code 0xfe, 0xff}, for example, it knows it's reading a big-endian byte sequence, while 78c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * {@code 0xff, 0xfe}, would indicate a little-endian byte sequence. 79c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 80c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>UTF-8 can contain a BOM, but since the UTF-8 encoding of a character always uses the same 81c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * byte sequence, there is no information about endianness to convey. Seeing the bytes 82c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * corresponding to the UTF-8 encoding of U+FEFF ({@code 0xef, 0xbb, 0xbf}) would only serve to 83c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * suggest that you're reading UTF-8. Note that BOMs are decoded as the U+FEFF character, and 84c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * will appear in the output character sequence. This means that a disadvantage to including a BOM 85c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * in UTF-8 is that most applications that use UTF-8 do not expect to see a BOM. (This is also a 86c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * reason to prefer UTF-8: it's one less complication to worry about.) 87c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 88c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Because a BOM indicates how the data that follows should be interpreted, a BOM should occur 89c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * as the first character in a character sequence. 90c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 91c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>See the <a href="http://unicode.org/faq/utf_bom.html#BOM">Byte Order Mark (BOM) FAQ</a> for 92c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * more about dealing with BOMs. 93c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 94c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <h4>Endianness and BOM behavior</h4> 95c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 96c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>The following tables show the endianness and BOM behavior of the UTF-16 variants. 97c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 98c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>This table shows what the encoder writes. "BE" means that the byte sequence is big-endian, 99c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * "LE" means little-endian. "BE BOM" means a big-endian BOM (that is, {@code 0xfe, 0xff}). 100c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p><table width="100%"> 101c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <th>Charset</th> <th>Encoder writes</th> </tr> 102c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <td>UTF-16BE</td> <td>BE, no BOM</td> </tr> 103c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <td>UTF-16LE</td> <td>LE, no BOM</td> </tr> 104c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <td>UTF-16</td> <td>BE, with BE BOM</td> </tr> 105c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * </table> 106c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 107c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>The next table shows how each variant's decoder behaves when reading a byte sequence. 108c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * The exact meaning of "failure" in the table is dependent on the 109c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * {@link CodingErrorAction} supplied to {@link CharsetDecoder#malformedInputAction}, so 110c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * "BE, failure" means "the byte sequence is treated as big-endian, and a little-endian BOM 111c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * triggers the malformedInputAction". 112c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 113c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>The phrase "includes BOM" means that the output includes the U+FEFF byte order mark character. 114c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 115c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p><table width="100%"> 116c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <th>Charset</th> <th>BE BOM</th> <th>LE BOM</th> <th>No BOM</th> </tr> 117c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <td>UTF-16BE</td> <td>BE, includes BOM</td> <td>BE, failure</td> <td>BE</td> </tr> 118c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <tr> <td>UTF-16LE</td> <td>LE, failure</td> <td>LE, includes BOM</td> <td>LE</td> </tr> 1193784ab1a0eafa37f1181df2815075300ab1c60f6Elliott Hughes * <tr> <td>UTF-16</td> <td>BE</td> <td>LE</td> <td>BE</td> </tr> 120c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * </table> 121c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 122c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <h4>Charset names</h4> 123c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>A charset has a canonical name, returned by {@link #name}. Most charsets will 124c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * also have one or more aliases, returned by {@link #aliases}. A charset can be looked up 125c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * by canonical name or any of its aliases using {@link #forName}. 126c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 127c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <h4>Guaranteed-available charsets</h4> 128c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>The following charsets are available on every Java implementation: 129c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <ul> 130c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <li>ISO-8859-1 131c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <li>US-ASCII 132c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <li>UTF-16 133c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <li>UTF-16BE 134c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <li>UTF-16LE 135c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <li>UTF-8 136c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * </ul> 137c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>All of these charsets support both decoding and encoding. The charsets whose names begin 138c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * "UTF" can represent all characters, as mentioned above. The "ISO-8859-1" and "US-ASCII" charsets 139c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * can only represent small subsets of these characters. Except when required to do otherwise for 140c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * compatibility, new code should use one of the UTF charsets listed above. The platform's default 141c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * charset is UTF-8. (This is in contrast to some older implementations, where the default charset 142c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * depended on the user's locale.) 143c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 144c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Most implementations will support hundreds of charsets. Use {@link #availableCharsets} or 145c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * {@link #isSupported} to see what's available. If you intend to use the charset if it's 146c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * available, just call {@link #forName} and catch the exceptions it throws if the charset isn't 147c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * available. 148c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * 149c60bc1815dca549f3fb4e572f6aac749d7fa9fc6Elliott Hughes * <p>Additional charsets can be made available by configuring one or more charset 150adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * providers through provider configuration files. Such files are always named 151adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * as "java.nio.charset.spi.CharsetProvider" and located in the 152cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes * "META-INF/services" directory of one or more classpaths. The files should be 153adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * encoded in "UTF-8". Each line of their content specifies the class name of a 154c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * charset provider which extends {@link java.nio.charset.spi.CharsetProvider}. 155cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes * A line should end with '\r', '\n' or '\r\n'. Leading and trailing whitespace 156cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes * is trimmed. Blank lines, and lines (after trimming) starting with "#" which are 157c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * regarded as comments, are both ignored. Duplicates of names already found are also 158adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ignored. Both the configuration files and the provider classes will be loaded 159adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * using the thread context class loader. 160eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * 161c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Although class is thread-safe, the {@link CharsetDecoder} and {@link CharsetEncoder} instances 162c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * it returns are inherently stateful. 163adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 164adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic abstract class Charset implements Comparable<Charset> { 165cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes private static final HashMap<String, Charset> CACHED_CHARSETS = new HashMap<String, Charset>(); 166c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes 167d0628c5cb80e3c1270634c56a784329a4836b9aaElliott Hughes private static final Charset DEFAULT_CHARSET = getDefaultCharset(); 168d0628c5cb80e3c1270634c56a784329a4836b9aaElliott Hughes 169adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project private final String canonicalName; 170adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 171adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project private final HashSet<String> aliasesSet; 172adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 173adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 174adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Constructs a <code>Charset</code> object. Duplicated aliases are 175adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ignored. 176f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 177adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param canonicalName 178adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the canonical name of the charset. 179adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param aliases 180adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * an array containing all aliases of the charset. May be null. 181adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IllegalCharsetNameException 182adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * on an illegal value being supplied for either 183adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <code>canonicalName</code> or for any element of 184adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <code>aliases</code>. 185adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 186eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson protected Charset(String canonicalName, String[] aliases) { 187adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // check whether the given canonical name is legal 188adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project checkCharsetName(canonicalName); 189adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project this.canonicalName = canonicalName; 190adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project // check each alias and put into a set 191adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project this.aliasesSet = new HashSet<String>(); 192bcf7c66e617ad0c33bb320184bb2401def517342Elliott Hughes if (aliases != null) { 193cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes for (String alias : aliases) { 194cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes checkCharsetName(alias); 195cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes this.aliasesSet.add(alias); 196adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 197adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 198adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 199adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 200adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project private static void checkCharsetName(String name) { 201c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes if (name.isEmpty()) { 202adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throw new IllegalCharsetNameException(name); 203adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 204adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project int length = name.length(); 205cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes for (int i = 0; i < length; ++i) { 206cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes if (!isValidCharsetNameCharacter(name.charAt(i))) { 207adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throw new IllegalCharsetNameException(name); 208adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 209adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 210adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 211adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 212cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes private static boolean isValidCharsetNameCharacter(char c) { 213cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || 214cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes c == '-' || c == '.' || c == ':' || c == '_'; 215ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes } 216ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes 217adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 218ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes * Returns an immutable case-insensitive map from canonical names to {@code Charset} instances. 219ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes * If multiple charsets have the same canonical name, it is unspecified which is returned in 220ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes * the map. This method may be slow. If you know which charset you're looking for, use 221ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes * {@link #forName}. 222ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes * @return an immutable case-insensitive map from canonical names to {@code Charset} instances 223adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 224adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public static SortedMap<String, Charset> availableCharsets() { 225ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes // Start with a copy of the built-in charsets... 226ccb8b92211a3e87acaf6486c8d4423c2053b8b5eElliott Hughes TreeMap<String, Charset> charsets = new TreeMap<String, Charset>(String.CASE_INSENSITIVE_ORDER); 227cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes for (String charsetName : NativeConverter.getAvailableCharsetNames()) { 228cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes Charset charset = NativeConverter.charsetForName(charsetName); 229cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes charsets.put(charset.name(), charset); 230adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 231adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 232cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // Add all charsets provided by all charset providers... 233cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes for (CharsetProvider charsetProvider : ServiceLoader.load(CharsetProvider.class, null)) { 234cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes Iterator<Charset> it = charsetProvider.charsets(); 235cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes while (it.hasNext()) { 236cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes Charset cs = it.next(); 237cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // A CharsetProvider can't override a built-in Charset. 238cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes if (!charsets.containsKey(cs.name())) { 239cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes charsets.put(cs.name(), cs); 240adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 241adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 242adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 243adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 244cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return Collections.unmodifiableSortedMap(charsets); 245adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 246adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 247cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes private static Charset cacheCharset(String charsetName, Charset cs) { 248cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes synchronized (CACHED_CHARSETS) { 249cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // Get the canonical name for this charset, and the canonical instance from the table. 250cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes String canonicalName = cs.name(); 251cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes Charset canonicalCharset = CACHED_CHARSETS.get(canonicalName); 252cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes if (canonicalCharset == null) { 253cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes canonicalCharset = cs; 254cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 255bcf7c66e617ad0c33bb320184bb2401def517342Elliott Hughes 256cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // Cache the charset by its canonical name... 257cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes CACHED_CHARSETS.put(canonicalName, canonicalCharset); 258c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes 259cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // And the name the user used... (Section 1.4 of http://unicode.org/reports/tr22/ means 260cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // that many non-alias, non-canonical names are valid. For example, "utf8" isn't an 261cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // alias of the canonical name "UTF-8", but we shouldn't penalize consistent users of 262cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // such names unduly.) 263cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes CACHED_CHARSETS.put(charsetName, canonicalCharset); 264c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes 265cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // And all its aliases... 266cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes for (String alias : cs.aliasesSet) { 267cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes CACHED_CHARSETS.put(alias, canonicalCharset); 268cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 269c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes 270cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return canonicalCharset; 271adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 272adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 273adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 274adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 275cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes * Returns a {@code Charset} instance for the named charset. 276f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 277cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes * @param charsetName a charset name (either canonical or an alias) 278adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IllegalCharsetNameException 279adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if the specified charset name is illegal. 280adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws UnsupportedCharsetException 281adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if the desired charset is not supported by this runtime. 282adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 283eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson public static Charset forName(String charsetName) { 284cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // Is this charset in our cache? 285cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes Charset cs; 286cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes synchronized (CACHED_CHARSETS) { 287cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes cs = CACHED_CHARSETS.get(charsetName); 288cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes if (cs != null) { 289cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return cs; 290cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 291cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 292cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes 293cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // Is this a built-in charset supported by ICU? 294cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes if (charsetName == null) { 295cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes throw new IllegalCharsetNameException(charsetName); 296cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 297cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes checkCharsetName(charsetName); 298cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes cs = NativeConverter.charsetForName(charsetName); 299c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes if (cs != null) { 300cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return cacheCharset(charsetName, cs); 301cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 302cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes 303cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes // Does a configured CharsetProvider have this charset? 304cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes for (CharsetProvider charsetProvider : ServiceLoader.load(CharsetProvider.class, null)) { 305cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes cs = charsetProvider.charsetForName(charsetName); 306cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes if (cs != null) { 307cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return cacheCharset(charsetName, cs); 308cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes } 309adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 310cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes 311c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes throw new UnsupportedCharsetException(charsetName); 312adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 313adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 314adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 315adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Determines whether the specified charset is supported by this runtime. 316f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 317adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param charsetName 318adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the name of the charset. 319adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return true if the specified charset is supported, otherwise false. 320adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @throws IllegalCharsetNameException 321adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * if the specified charset name is illegal. 322adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 323c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes public static boolean isSupported(String charsetName) { 324c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes try { 325c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes Charset cs = forName(charsetName); 326c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes return true; 327c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes } catch (UnsupportedCharsetException ex) { 328c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes return false; 329c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes } 330adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 331adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 332adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 333c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Determines whether this charset is a superset of the given charset. A charset C1 contains 334c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * charset C2 if every character representable by C2 is also representable by C1. This means 335c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * that lossless conversion is possible from C2 to C1 (but not necessarily the other way 336c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * round). It does <i>not</i> imply that the two charsets use the same byte sequences for the 337c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * characters they share. 338c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 339c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Note that this method is allowed to be conservative, and some implementations may return 340c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * false when this charset does contain the other charset. Android's implementation is precise, 341c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * and will always return true in such cases. 342f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 343adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param charset 344adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a given charset. 345adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return true if this charset is a super set of the given charset, 346adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * false if it's unknown or this charset is not a superset of 347adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the given charset. 348adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 349adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract boolean contains(Charset charset); 350adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 351adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 352adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a new instance of an encoder for this charset. 353f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 354adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a new instance of an encoder for this charset. 355adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 356adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract CharsetEncoder newEncoder(); 357adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 358adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 359adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a new instance of a decoder for this charset. 360f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 361adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a new instance of a decoder for this charset. 362adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 363adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public abstract CharsetDecoder newDecoder(); 364adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 365adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 366adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the canonical name of this charset. 367f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 368adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return this charset's name in canonical form. 369adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 370adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final String name() { 371adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return this.canonicalName; 372adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 373adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 374adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 375adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the set of this charset's aliases. 376f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 377adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return an unmodifiable set of this charset's aliases. 378adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 379adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final Set<String> aliases() { 380adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return Collections.unmodifiableSet(this.aliasesSet); 381adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 382adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 383adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 384adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the name of this charset for the default locale. 385f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 386eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * <p>The default implementation returns the canonical name of this charset. 387eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * Subclasses may return a localized display name. 388eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * 389adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return the name of this charset for the default locale. 390adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 391adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public String displayName() { 392adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return this.canonicalName; 393adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 394adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 395adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 396adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the name of this charset for the specified locale. 397eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * 398eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * <p>The default implementation returns the canonical name of this charset. 399eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * Subclasses may return a localized display name. 400eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * 401adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param l 402adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * a certain locale 403eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * @return the name of this charset for the specified locale 404adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 405adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public String displayName(Locale l) { 406adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return this.canonicalName; 407adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 408adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 409adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 410adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Indicates whether this charset is known to be registered in the IANA 411adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Charset Registry. 412f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 413adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return true if the charset is known to be registered, otherwise returns 414adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * false. 415adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 416adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final boolean isRegistered() { 417cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return !canonicalName.startsWith("x-") && !canonicalName.startsWith("X-"); 418adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 419adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 420adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 421adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Returns true if this charset supports encoding, false otherwise. 422f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 423adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return true if this charset supports encoding, false otherwise. 424adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 425adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public boolean canEncode() { 426adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return true; 427adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 428adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 429adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 430c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Returns a new {@code ByteBuffer} containing the bytes encoding the characters from 431c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * {@code buffer}. 432c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * This method uses {@code CodingErrorAction.REPLACE}. 433c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 434c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Applications should generally create a {@link CharsetEncoder} using {@link #newEncoder} 435c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * for performance. 436eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * 437adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param buffer 438adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the character buffer containing the content to be encoded. 439adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return the result of the encoding. 440adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 441eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson public final ByteBuffer encode(CharBuffer buffer) { 442adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project try { 443c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes return newEncoder() 444eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson .onMalformedInput(CodingErrorAction.REPLACE) 445eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson .onUnmappableCharacter(CodingErrorAction.REPLACE).encode( 446eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson buffer); 447adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } catch (CharacterCodingException ex) { 448adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throw new Error(ex.getMessage(), ex); 449adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 450adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 451adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 452adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 453c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Returns a new {@code ByteBuffer} containing the bytes encoding the characters from {@code s}. 454c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * This method uses {@code CodingErrorAction.REPLACE}. 455eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson * 456c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Applications should generally create a {@link CharsetEncoder} using {@link #newEncoder} 457c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * for performance. 458c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 459c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * @param s the string to be encoded. 460adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return the result of the encoding. 461adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 462adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final ByteBuffer encode(String s) { 463adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return encode(CharBuffer.wrap(s)); 464adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 465adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 466adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 467c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Returns a new {@code CharBuffer} containing the characters decoded from {@code buffer}. 468c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * This method uses {@code CodingErrorAction.REPLACE}. 469c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * 470c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * <p>Applications should generally create a {@link CharsetDecoder} using {@link #newDecoder} 471c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * for performance. 472f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 473adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param buffer 474adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the byte buffer containing the content to be decoded. 475adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a character buffer containing the output of the decoding. 476adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 477adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final CharBuffer decode(ByteBuffer buffer) { 478adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project try { 479c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes return newDecoder() 480eaa2ff09069424b0f7a95c7cd831cef1b744fe67Jesse Wilson .onMalformedInput(CodingErrorAction.REPLACE) 481c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes .onUnmappableCharacter(CodingErrorAction.REPLACE).decode(buffer); 482adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } catch (CharacterCodingException ex) { 483adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project throw new Error(ex.getMessage(), ex); 484adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 485adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 486adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 487adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /* 488adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ------------------------------------------------------------------- 489adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Methods implementing parent interface Comparable 490adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ------------------------------------------------------------------- 491adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 492adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 493adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 494c89c180eb85cc0392c3a6c2eb4803594478e665cElliott Hughes * Compares this charset with the given charset. This comparison is 495adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * based on the case insensitive canonical names of the charsets. 496f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 497adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param charset 498adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the given object to be compared with. 499adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a negative integer if less than the given object, a positive 500adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * integer if larger than it, or 0 if equal to it. 501adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 502adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final int compareTo(Charset charset) { 503adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return this.canonicalName.compareToIgnoreCase(charset.canonicalName); 504adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 505adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 506adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /* 507adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ------------------------------------------------------------------- 508adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Methods overriding parent class Object 509adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * ------------------------------------------------------------------- 510adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 511adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 512adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 513adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Determines whether this charset equals to the given object. They are 514adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * considered to be equal if they have the same canonical name. 515f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 516adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param obj 517adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the given object to be compared with. 518adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return true if they have the same canonical name, otherwise false. 519adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 520adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project @Override 521adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final boolean equals(Object obj) { 522adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project if (obj instanceof Charset) { 523adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project Charset that = (Charset) obj; 524adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return this.canonicalName.equals(that.canonicalName); 525adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 526adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return false; 527adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 528adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 529adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 530adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets the hash code of this charset. 531f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 532adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return the hash code of this charset. 533adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 534adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project @Override 535adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final int hashCode() { 536adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project return this.canonicalName.hashCode(); 537adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 538adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 539adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 540adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Gets a string representation of this charset. Usually this contains the 541adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * canonical name of the charset. 542f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 543adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @return a string representation of this charset. 544adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 545adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project @Override 546adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public final String toString() { 547cb8d09e94846d073ee7b50bef89c0b33113697fbElliott Hughes return getClass().getName() + "[" + this.canonicalName + "]"; 548adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 549adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 550adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 551c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes * Returns the system's default charset. This is determined during VM startup, and will not 552c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes * change thereafter. On Android, the default charset is UTF-8. 553adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 554adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public static Charset defaultCharset() { 555d0628c5cb80e3c1270634c56a784329a4836b9aaElliott Hughes return DEFAULT_CHARSET; 556d0628c5cb80e3c1270634c56a784329a4836b9aaElliott Hughes } 557d0628c5cb80e3c1270634c56a784329a4836b9aaElliott Hughes 558d0628c5cb80e3c1270634c56a784329a4836b9aaElliott Hughes private static Charset getDefaultCharset() { 559c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes String encoding = AccessController.doPrivileged(new PrivilegedAction<String>() { 560c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes public String run() { 561c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes return System.getProperty("file.encoding", "UTF-8"); 562c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes } 563c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes }); 564adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project try { 565c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes return Charset.forName(encoding); 566adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } catch (UnsupportedCharsetException e) { 567c903e6720bbbf6540c29f141bd2fa559813ea20aElliott Hughes return Charset.forName("UTF-8"); 568adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 569adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 570adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 571