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.nio.charset.UnsupportedCharsetException; 022import java.util.Collections; 023import java.util.SortedMap; 024import java.util.TreeMap; 025 026/** 027 * Charsets required of every implementation of the Java platform. 028 * 029 * From the Java documentation <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html"> 030 * Standard charsets</a>: 031 * <p> 032 * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult 033 * the release documentation for your implementation to see if any other encodings are supported. Consult the release 034 * documentation for your implementation to see if any other encodings are supported. </cite> 035 * </p> 036 * 037 * <ul> 038 * <li>{@code US-ASCII}<br> 039 * Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</li> 040 * <li>{@code ISO-8859-1}<br> 041 * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</li> 042 * <li>{@code UTF-8}<br> 043 * Eight-bit Unicode Transformation Format.</li> 044 * <li>{@code UTF-16BE}<br> 045 * Sixteen-bit Unicode Transformation Format, big-endian byte order.</li> 046 * <li>{@code UTF-16LE}<br> 047 * Sixteen-bit Unicode Transformation Format, little-endian byte order.</li> 048 * <li>{@code UTF-16}<br> 049 * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order 050 * accepted on input, big-endian used on output.)</li> 051 * </ul> 052 * 053 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 054 * @since 2.3 055 */ 056public class Charsets { 057 058 // 059 // This class should only contain Charset instances for required encodings. This guarantees that it will load 060 // correctly and without delay on all Java platforms. 061 // 062 063 private static final SortedMap<String, Charset> STANDARD_CHARSET_MAP; 064 065 static { 066 final SortedMap<String, Charset> standardCharsetMap = new TreeMap<>(String.CASE_INSENSITIVE_ORDER); 067 standardCharsetMap.put(StandardCharsets.ISO_8859_1.name(), StandardCharsets.ISO_8859_1); 068 standardCharsetMap.put(StandardCharsets.US_ASCII.name(), StandardCharsets.US_ASCII); 069 standardCharsetMap.put(StandardCharsets.UTF_16.name(), StandardCharsets.UTF_16); 070 standardCharsetMap.put(StandardCharsets.UTF_16BE.name(), StandardCharsets.UTF_16BE); 071 standardCharsetMap.put(StandardCharsets.UTF_16LE.name(), StandardCharsets.UTF_16LE); 072 standardCharsetMap.put(StandardCharsets.UTF_8.name(), StandardCharsets.UTF_8); 073 STANDARD_CHARSET_MAP = Collections.unmodifiableSortedMap(standardCharsetMap); 074 } 075 076 /** 077 * Constructs a sorted map from canonical charset names to charset objects required of every implementation of the 078 * Java platform. 079 * <p> 080 * From the Java documentation <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html"> 081 * Standard charsets</a>: 082 * </p> 083 * 084 * @return An immutable, case-insensitive map from canonical charset names to charset objects. 085 * @see Charset#availableCharsets() 086 * @since 2.5 087 */ 088 public static SortedMap<String, Charset> requiredCharsets() { 089 return STANDARD_CHARSET_MAP; 090 } 091 092 /** 093 * Returns the given Charset or the default Charset if the given Charset is null. 094 * 095 * @param charset 096 * A charset or null. 097 * @return the given Charset or the default Charset if the given Charset is null 098 */ 099 public static Charset toCharset(final Charset charset) { 100 return charset == null ? Charset.defaultCharset() : charset; 101 } 102 103 /** 104 * Returns a Charset for the named charset. If the name is null, return the default Charset. 105 * 106 * @param charsetName The name of the requested charset, may be null. 107 * @return a Charset for the named charset. 108 * @throws UnsupportedCharsetException If the named charset is unavailable (unchecked exception). 109 */ 110 public static Charset toCharset(final String charsetName) throws UnsupportedCharsetException { 111 return charsetName == null ? Charset.defaultCharset() : Charset.forName(charsetName); 112 } 113 114 /** 115 * CharEncodingISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1. 116 * <p> 117 * Every implementation of the Java platform is required to support this character encoding. 118 * </p> 119 * 120 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 121 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 122 */ 123 @Deprecated 124 public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1; 125 126 /** 127 * <p> 128 * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set. 129 * </p> 130 * <p> 131 * Every implementation of the Java platform is required to support this character encoding. 132 * </p> 133 * 134 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 135 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 136 */ 137 @Deprecated 138 public static final Charset US_ASCII = StandardCharsets.US_ASCII; 139 140 /** 141 * <p> 142 * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark 143 * (either order accepted on input, big-endian used on output) 144 * </p> 145 * <p> 146 * Every implementation of the Java platform is required to support this character encoding. 147 * </p> 148 * 149 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 150 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 151 */ 152 @Deprecated 153 public static final Charset UTF_16 = StandardCharsets.UTF_16; 154 155 /** 156 * <p> 157 * Sixteen-bit Unicode Transformation Format, big-endian byte order. 158 * </p> 159 * <p> 160 * Every implementation of the Java platform is required to support this character encoding. 161 * </p> 162 * 163 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 164 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 165 */ 166 @Deprecated 167 public static final Charset UTF_16BE = StandardCharsets.UTF_16BE; 168 169 /** 170 * <p> 171 * Sixteen-bit Unicode Transformation Format, little-endian byte order. 172 * </p> 173 * <p> 174 * Every implementation of the Java platform is required to support this character encoding. 175 * </p> 176 * 177 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 178 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 179 */ 180 @Deprecated 181 public static final Charset UTF_16LE = StandardCharsets.UTF_16LE; 182 183 /** 184 * <p> 185 * Eight-bit Unicode Transformation Format. 186 * </p> 187 * <p> 188 * Every implementation of the Java platform is required to support this character encoding. 189 * </p> 190 * 191 * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 192 * @deprecated Use Java 7's {@link java.nio.charset.StandardCharsets} 193 */ 194 @Deprecated 195 public static final Charset UTF_8 = StandardCharsets.UTF_8; 196}