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