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 *
017 */
018
019package org.apache.commons.compress.utils;
020
021import java.nio.charset.Charset;
022import java.nio.charset.StandardCharsets;
023
024/**
025 * Charsets required of every implementation of the Java platform.
026 *
027 * From the Java documentation <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard
028 * charsets</a>:
029 * <p>
030 * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult the
031 * release documentation for your implementation to see if any other encodings are supported. Consult the release
032 * documentation for your implementation to see if any other encodings are supported. </cite>
033 * </p>
034 *
035 * <dl>
036 * <dt>{@code US-ASCII}</dt>
037 * <dd>Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</dd>
038 * <dt>{@code ISO-8859-1}</dt>
039 * <dd>ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</dd>
040 * <dt>{@code UTF-8}</dt>
041 * <dd>Eight-bit Unicode Transformation Format.</dd>
042 * <dt>{@code UTF-16BE}</dt>
043 * <dd>Sixteen-bit Unicode Transformation Format, big-endian byte order.</dd>
044 * <dt>{@code UTF-16LE}</dt>
045 * <dd>Sixteen-bit Unicode Transformation Format, little-endian byte order.</dd>
046 * <dt>{@code UTF-16}</dt>
047 * <dd>Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order
048 * accepted on input, big-endian used on output.)</dd>
049 * </dl>
050 *
051 * <p>This class best belongs in the Commons Lang or IO project. Even if a similar class is defined in another Commons
052 * component, it is not foreseen that Commons Compress would be made to depend on another Commons component.</p>
053 *
054 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
055 * @see StandardCharsets
056 * @since 1.4
057 */
058public class Charsets {
059
060    //
061    // This class should only contain Charset instances for required encodings. This guarantees that it will load correctly and
062    // without delay on all Java platforms.
063    //
064
065    /**
066     * CharsetNamesISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.
067     * <p>
068     * Every implementation of the Java platform is required to support this character encoding.
069     * </p>
070     *
071     * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
072     * @deprecated replaced by {@link StandardCharsets} in Java 7
073     */
074    @Deprecated
075    public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1;
076
077    /**
078     * <p>
079     * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
080     * </p>
081     * <p>
082     * Every implementation of the Java platform is required to support this character encoding.
083     * </p>
084     *
085     * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
086     * @deprecated replaced by {@link StandardCharsets} in Java 7
087     */
088    @Deprecated
089    public static final Charset US_ASCII = StandardCharsets.US_ASCII;
090
091    /**
092     * <p>
093     * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark
094     * (either order accepted on input, big-endian used on output)
095     * </p>
096     * <p>
097     * Every implementation of the Java platform is required to support this character encoding.
098     * </p>
099     *
100     * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
101     * @deprecated replaced by {@link StandardCharsets} in Java 7
102     */
103    @Deprecated
104    public static final Charset UTF_16 = StandardCharsets.UTF_16;
105
106    /**
107     * <p>
108     * Sixteen-bit Unicode Transformation Format, big-endian byte order.
109     * </p>
110     * <p>
111     * Every implementation of the Java platform is required to support this character encoding.
112     * </p>
113     *
114     * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
115     * @deprecated replaced by {@link StandardCharsets} in Java 7
116     */
117    @Deprecated
118    public static final Charset UTF_16BE = StandardCharsets.UTF_16BE;
119
120    /**
121     * <p>
122     * Sixteen-bit Unicode Transformation Format, little-endian byte order.
123     * </p>
124     * <p>
125     * Every implementation of the Java platform is required to support this character encoding.
126     * </p>
127     *
128     * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
129     * @deprecated replaced by {@link StandardCharsets} in Java 7
130     */
131    @Deprecated
132    public static final Charset UTF_16LE = StandardCharsets.UTF_16LE;
133
134    /**
135     * <p>
136     * Eight-bit Unicode Transformation Format.
137     * </p>
138     * <p>
139     * Every implementation of the Java platform is required to support this character encoding.
140     * </p>
141     *
142     * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
143     * @deprecated replaced by {@link StandardCharsets} in Java 7
144     */
145    @Deprecated
146    public static final Charset UTF_8 = StandardCharsets.UTF_8;
147
148    /**
149     * Returns the given Charset or the default Charset if the given Charset is null.
150     *
151     * @param charset
152     *            A charset or null.
153     * @return the given Charset or the default Charset if the given Charset is null
154     */
155    public static Charset toCharset(final Charset charset) {
156        return charset == null ? Charset.defaultCharset() : charset;
157    }
158
159    /**
160     * Returns a Charset for the named charset. If the name is null, return the default Charset.
161     *
162     * @param charset
163     *            The name of the requested charset, may be null.
164     * @return a Charset for the named charset
165     * @throws java.nio.charset.UnsupportedCharsetException
166     *             If the named charset is unavailable
167     * @throws java.nio.charset.IllegalCharsetNameException
168     *             If the given charset name is illegal
169     */
170    public static Charset toCharset(final String charset) {
171        return charset == null ? Charset.defaultCharset() : Charset.forName(charset);
172    }
173}