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