001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.io; 018 019import java.nio.charset.Charset; 020import java.nio.charset.StandardCharsets; 021import java.util.Collections; 022import java.util.SortedMap; 023import java.util.TreeMap; 024 025/** 026 * Charsets required of every implementation of the Java platform. 027 * 028 * From the Java documentation <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html"> 029 * Standard charsets</a>: 030 * <p> 031 * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult 032 * the release documentation for your implementation to see if any other encodings are supported. Consult the release 033 * documentation for your implementation to see if any other encodings are supported. </cite> 034 * </p> 035 * 036 * <ul> 037 * <li><code>US-ASCII</code><br> 038 * Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</li> 039 * <li><code>ISO-8859-1</code><br> 040 * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</li> 041 * <li><code>UTF-8</code><br> 042 * Eight-bit Unicode Transformation Format.</li> 043 * <li><code>UTF-16BE</code><br> 044 * Sixteen-bit Unicode Transformation Format, big-endian byte order.</li> 045 * <li><code>UTF-16LE</code><br> 046 * Sixteen-bit Unicode Transformation Format, little-endian byte order.</li> 047 * <li><code>UTF-16</code><br> 048 * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order 049 * accepted on input, big-endian used on output.)</li> 050 * </ul> 051 * 052 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 053 * @since 2.3 054 */ 055public class Charsets { 056 057 // 058 // This class should only contain Charset instances for required encodings. This guarantees that it will load 059 // correctly and without delay on all Java platforms. 060 // 061 062 private static final SortedMap<String, Charset> STANDARD_CHARSET_MAP; 063 064 static { 065 final SortedMap<String, Charset> standardCharsetMap = new TreeMap<>(String.CASE_INSENSITIVE_ORDER); 066 standardCharsetMap.put(StandardCharsets.ISO_8859_1.name(), StandardCharsets.ISO_8859_1); 067 standardCharsetMap.put(StandardCharsets.US_ASCII.name(), StandardCharsets.US_ASCII); 068 standardCharsetMap.put(StandardCharsets.UTF_16.name(), StandardCharsets.UTF_16); 069 standardCharsetMap.put(StandardCharsets.UTF_16BE.name(), StandardCharsets.UTF_16BE); 070 standardCharsetMap.put(StandardCharsets.UTF_16LE.name(), StandardCharsets.UTF_16LE); 071 standardCharsetMap.put(StandardCharsets.UTF_8.name(), StandardCharsets.UTF_8); 072 STANDARD_CHARSET_MAP = Collections.unmodifiableSortedMap(standardCharsetMap); 073 } 074 075 /** 076 * Constructs a sorted map from canonical charset names to charset objects required of every implementation of the 077 * Java platform. 078 * <p> 079 * From the Java documentation <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html"> 080 * Standard charsets</a>: 081 * </p> 082 * 083 * @return An immutable, case-insensitive map from canonical charset names to charset objects. 084 * @see Charset#availableCharsets() 085 * @since 2.5 086 */ 087 public static SortedMap<String, Charset> requiredCharsets() { 088 return STANDARD_CHARSET_MAP; 089 } 090 091 /** 092 * Returns the given Charset or the default Charset if the given Charset is null. 093 * 094 * @param charset 095 * A charset or null. 096 * @return the given Charset or the default Charset if the given Charset is null 097 */ 098 public static Charset toCharset(final Charset charset) { 099 return charset == null ? Charset.defaultCharset() : charset; 100 } 101 102 /** 103 * Returns a Charset for the named charset. If the name is null, return the default Charset. 104 * 105 * @param charsetName 106 * The name of the requested charset, may be null. 107 * @return a Charset for the named charset 108 * @throws java.nio.charset.UnsupportedCharsetException 109 * If the named charset is unavailable 110 */ 111 public static Charset toCharset(final String charsetName) { 112 return charsetName == null ? Charset.defaultCharset() : Charset.forName(charsetName); 113 } 114 115 /** 116 * CharEncodingISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1. 117 * <p> 118 * Every implementation of the Java platform is required to support this character encoding. 119 * </p> 120 * 121 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 122 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 123 */ 124 @Deprecated 125 public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1; 126 127 /** 128 * <p> 129 * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set. 130 * </p> 131 * <p> 132 * Every implementation of the Java platform is required to support this character encoding. 133 * </p> 134 * 135 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 136 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 137 */ 138 @Deprecated 139 public static final Charset US_ASCII = StandardCharsets.US_ASCII; 140 141 /** 142 * <p> 143 * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark 144 * (either order accepted on input, big-endian used on output) 145 * </p> 146 * <p> 147 * Every implementation of the Java platform is required to support this character encoding. 148 * </p> 149 * 150 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 151 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 152 */ 153 @Deprecated 154 public static final Charset UTF_16 = StandardCharsets.UTF_16; 155 156 /** 157 * <p> 158 * Sixteen-bit Unicode Transformation Format, big-endian byte order. 159 * </p> 160 * <p> 161 * Every implementation of the Java platform is required to support this character encoding. 162 * </p> 163 * 164 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 165 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 166 */ 167 @Deprecated 168 public static final Charset UTF_16BE = StandardCharsets.UTF_16BE; 169 170 /** 171 * <p> 172 * Sixteen-bit Unicode Transformation Format, little-endian byte order. 173 * </p> 174 * <p> 175 * Every implementation of the Java platform is required to support this character encoding. 176 * </p> 177 * 178 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 179 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 180 */ 181 @Deprecated 182 public static final Charset UTF_16LE = StandardCharsets.UTF_16LE; 183 184 /** 185 * <p> 186 * Eight-bit Unicode Transformation Format. 187 * </p> 188 * <p> 189 * Every implementation of the Java platform is required to support this character encoding. 190 * </p> 191 * 192 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 193 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 194 */ 195 @Deprecated 196 public static final Charset UTF_8 = StandardCharsets.UTF_8; 197}