1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.compress.utils; 19 20 import java.nio.charset.Charset; 21 import java.nio.charset.StandardCharsets; 22 23 /** 24 * Charsets required of every implementation of the Java platform. 25 * 26 * From the Java documentation <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a>: 27 * <p> 28 * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult the release documentation for your 29 * implementation to see if any other encodings are supported. Consult the release documentation for your implementation to see if any other encodings are 30 * supported. </cite> 31 * </p> 32 * 33 * <dl> 34 * <dt>{@code US-ASCII}</dt> 35 * <dd>Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</dd> 36 * <dt>{@code ISO-8859-1}</dt> 37 * <dd>ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</dd> 38 * <dt>{@code UTF-8}</dt> 39 * <dd>Eight-bit Unicode Transformation Format.</dd> 40 * <dt>{@code UTF-16BE}</dt> 41 * <dd>Sixteen-bit Unicode Transformation Format, big-endian byte order.</dd> 42 * <dt>{@code UTF-16LE}</dt> 43 * <dd>Sixteen-bit Unicode Transformation Format, little-endian byte order.</dd> 44 * <dt>{@code UTF-16}</dt> 45 * <dd>Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order accepted on input, big-endian used 46 * on output.)</dd> 47 * </dl> 48 * 49 * <p> 50 * This class best belongs in the Commons Lang or IO project. Even if a similar class is defined in another Commons component, it is not foreseen that Commons 51 * Compress would be made to depend on another Commons component. 52 * </p> 53 * 54 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 55 * @see StandardCharsets 56 * @since 1.4 57 * @deprecated Use {@link org.apache.commons.io.Charsets}. 58 */ 59 @Deprecated 60 public class Charsets { 61 62 // 63 // This class should only contain Charset instances for required encodings. This guarantees that it will load correctly and 64 // without delay on all Java platforms. 65 // 66 67 /** 68 * CharsetNamesISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1. 69 * <p> 70 * Every implementation of the Java platform is required to support this character encoding. 71 * </p> 72 * 73 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 74 * @deprecated replaced by {@link StandardCharsets} in Java 7 75 */ 76 @Deprecated 77 public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1; 78 79 /** 80 * <p> 81 * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set. 82 * </p> 83 * <p> 84 * Every implementation of the Java platform is required to support this character encoding. 85 * </p> 86 * 87 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 88 * @deprecated replaced by {@link StandardCharsets} in Java 7 89 */ 90 @Deprecated 91 public static final Charset US_ASCII = StandardCharsets.US_ASCII; 92 93 /** 94 * <p> 95 * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark (either order accepted on input, big-endian 96 * used on output) 97 * </p> 98 * <p> 99 * Every implementation of the Java platform is required to support this character encoding. 100 * </p> 101 * 102 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 103 * @deprecated replaced by {@link StandardCharsets} in Java 7 104 */ 105 @Deprecated 106 public static final Charset UTF_16 = StandardCharsets.UTF_16; 107 108 /** 109 * <p> 110 * Sixteen-bit Unicode Transformation Format, big-endian byte order. 111 * </p> 112 * <p> 113 * Every implementation of the Java platform is required to support this character encoding. 114 * </p> 115 * 116 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 117 * @deprecated replaced by {@link StandardCharsets} in Java 7 118 */ 119 @Deprecated 120 public static final Charset UTF_16BE = StandardCharsets.UTF_16BE; 121 122 /** 123 * <p> 124 * Sixteen-bit Unicode Transformation Format, little-endian byte order. 125 * </p> 126 * <p> 127 * Every implementation of the Java platform is required to support this character encoding. 128 * </p> 129 * 130 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 131 * @deprecated replaced by {@link StandardCharsets} in Java 7 132 */ 133 @Deprecated 134 public static final Charset UTF_16LE = StandardCharsets.UTF_16LE; 135 136 /** 137 * <p> 138 * Eight-bit Unicode Transformation Format. 139 * </p> 140 * <p> 141 * Every implementation of the Java platform is required to support this character encoding. 142 * </p> 143 * 144 * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Standard charsets</a> 145 * @deprecated replaced by {@link StandardCharsets} in Java 7 146 */ 147 @Deprecated 148 public static final Charset UTF_8 = StandardCharsets.UTF_8; 149 150 /** 151 * Returns the given Charset or the default Charset if the given Charset is null. 152 * 153 * @param charset A charset or null. 154 * @return the given Charset or the default Charset if the given Charset is null 155 */ 156 public static Charset toCharset(final Charset charset) { 157 return charset == null ? Charset.defaultCharset() : charset; 158 } 159 160 /** 161 * Returns a Charset for the named charset. If the name is null, return the default Charset. 162 * 163 * @param charset The name of the requested charset, may be null. 164 * @return a Charset for the named charset 165 * @throws java.nio.charset.UnsupportedCharsetException If the named charset is unavailable 166 * @throws java.nio.charset.IllegalCharsetNameException If the given charset name is illegal 167 */ 168 public static Charset toCharset(final String charset) { 169 return charset == null ? Charset.defaultCharset() : Charset.forName(charset); 170 } 171 }