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 package org.apache.commons.codec;
18
19 import java.nio.charset.Charset;
20 import java.nio.charset.StandardCharsets;
21
22 /**
23 * Charsets required of every implementation of the Java platform.
24 *
25 * From the Java documentation <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard
26 * charsets</a>:
27 * <p>
28 * <cite>Every implementation of the Java platform is required to support the following character encodings. Consult the
29 * release documentation for your implementation to see if any other encodings are supported. Consult the release
30 * documentation for your implementation to see if any other encodings are supported. </cite>
31 * </p>
32 *
33 * <ul>
34 * <li>{@code US-ASCII}<p>
35 * Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set.</p></li>
36 * <li>{@code ISO-8859-1}<p>
37 * ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.</p></li>
38 * <li>{@code UTF-8}<p>
39 * Eight-bit Unicode Transformation Format.</p></li>
40 * <li>{@code UTF-16BE}<p>
41 * Sixteen-bit Unicode Transformation Format, big-endian byte order.</p></li>
42 * <li>{@code UTF-16LE}<p>
43 * Sixteen-bit Unicode Transformation Format, little-endian byte order.</p></li>
44 * <li>{@code UTF-16}<p>
45 * Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either order
46 * accepted on input, big-endian used on output.)</p></li>
47 * </ul>
48 *
49 * This perhaps would best belong in the Commons Lang project. Even if a similar class is defined in Commons Lang, it is
50 * not foreseen that Commons Codec would be made to depend on Commons Lang.
51 *
52 * <p>
53 * This class is immutable and thread-safe.
54 * </p>
55 *
56 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
57 * @since 1.7
58 */
59 public class Charsets {
60
61 //
62 // This class should only contain Charset instances for required encodings. This guarantees that it will load
63 // correctly and without delay on all Java platforms.
64 //
65
66 /**
67 * CharEncodingISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.
68 * <p>
69 * Every implementation of the Java platform is required to support this character encoding.
70 * </p>
71 *
72 * @deprecated Use {@link java.nio.charset.StandardCharsets#ISO_8859_1} instead.
73 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
74 */
75 @Deprecated
76 public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1;
77
78 /**
79 * Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
80 * <p>
81 * Every implementation of the Java platform is required to support this character encoding.
82 * </p>
83 *
84 * @deprecated Use {@link java.nio.charset.StandardCharsets#US_ASCII} instead.
85 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
86 */
87 @Deprecated
88 public static final Charset US_ASCII = StandardCharsets.US_ASCII;
89
90 /**
91 * Sixteen-bit Unicode Transformation Format, The byte order specified by a mandatory initial byte-order mark
92 * (either order accepted on input, big-endian used on output)
93 * <p>
94 * Every implementation of the Java platform is required to support this character encoding.
95 * </p>
96 *
97 * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_16} instead.
98 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
99 */
100 @Deprecated
101 public static final Charset UTF_16 = StandardCharsets.UTF_16;
102
103 /**
104 * Sixteen-bit Unicode Transformation Format, big-endian byte order.
105 * <p>
106 * Every implementation of the Java platform is required to support this character encoding.
107 * </p>
108 *
109 * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_16BE} instead.
110 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
111 */
112 @Deprecated
113 public static final Charset UTF_16BE = StandardCharsets.UTF_16BE;
114
115 /**
116 * Sixteen-bit Unicode Transformation Format, little-endian byte order.
117 * <p>
118 * Every implementation of the Java platform is required to support this character encoding.
119 * </p>
120 *
121 * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_16LE} instead.
122 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
123 */
124 @Deprecated
125 public static final Charset UTF_16LE = StandardCharsets.UTF_16LE;
126
127 /**
128 * Eight-bit Unicode Transformation Format.
129 * <p>
130 * Every implementation of the Java platform is required to support this character encoding.
131 * </p>
132 *
133 * @deprecated Use {@link java.nio.charset.StandardCharsets#UTF_8} instead.
134 * @see <a href="https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Standard charsets</a>
135 */
136 @Deprecated
137 public static final Charset UTF_8 = StandardCharsets.UTF_8;
138
139 /**
140 * Returns the given Charset or the default Charset if the given Charset is null.
141 *
142 * @param charset
143 * A charset or null.
144 * @return the given Charset or the default Charset if the given Charset is null
145 */
146 public static Charset toCharset(final Charset charset) {
147 return charset == null ? Charset.defaultCharset() : charset;
148 }
149
150 /**
151 * Returns a Charset for the named charset. If the name is null, return the default Charset.
152 *
153 * @param charset
154 * The name of the requested charset, may be null.
155 * @return a Charset for the named charset
156 * @throws java.nio.charset.UnsupportedCharsetException
157 * If the named charset is unavailable
158 */
159 public static Charset toCharset(final String charset) {
160 return charset == null ? Charset.defaultCharset() : Charset.forName(charset);
161 }
162
163 /**
164 * TODO Make private in 2.0.
165 *
166 * @deprecated TODO Make private in 2.0.
167 */
168 @Deprecated
169 public Charsets() {
170 // empty
171 }
172 }