1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.util;
17
18 import io.netty.util.internal.InternalThreadLocalMap;
19 import static io.netty.util.internal.ObjectUtil.checkNotNull;
20
21 import java.nio.charset.Charset;
22 import java.nio.charset.CharsetDecoder;
23 import java.nio.charset.CharsetEncoder;
24 import java.nio.charset.CodingErrorAction;
25 import java.util.Map;
26
27 /**
28 * A utility class that provides various common operations and constants
29 * related with {@link Charset} and its relevant classes.
30 */
31 public final class CharsetUtil {
32
33 /**
34 * 16-bit UTF (UCS Transformation Format) whose byte order is identified by
35 * an optional byte-order mark
36 */
37 public static final Charset UTF_16 = Charset.forName("UTF-16");
38
39 /**
40 * 16-bit UTF (UCS Transformation Format) whose byte order is big-endian
41 */
42 public static final Charset UTF_16BE = Charset.forName("UTF-16BE");
43
44 /**
45 * 16-bit UTF (UCS Transformation Format) whose byte order is little-endian
46 */
47 public static final Charset UTF_16LE = Charset.forName("UTF-16LE");
48
49 /**
50 * 8-bit UTF (UCS Transformation Format)
51 */
52 public static final Charset UTF_8 = Charset.forName("UTF-8");
53
54 /**
55 * ISO Latin Alphabet No. 1, as known as <tt>ISO-LATIN-1</tt>
56 */
57 public static final Charset ISO_8859_1 = Charset.forName("ISO-8859-1");
58
59 /**
60 * 7-bit ASCII, as known as ISO646-US or the Basic Latin block of the
61 * Unicode character set
62 */
63 public static final Charset US_ASCII = Charset.forName("US-ASCII");
64
65 private static final Charset[] CHARSETS = new Charset[]
66 { UTF_16, UTF_16BE, UTF_16LE, UTF_8, ISO_8859_1, US_ASCII };
67
68 public static Charset[] values() {
69 return CHARSETS;
70 }
71
72 /**
73 * @deprecated Use {@link #encoder(Charset)}.
74 */
75 @Deprecated
76 public static CharsetEncoder getEncoder(Charset charset) {
77 return encoder(charset);
78 }
79
80 /**
81 * Returns a new {@link CharsetEncoder} for the {@link Charset} with specified error actions.
82 *
83 * @param charset The specified charset
84 * @param malformedInputAction The encoder's action for malformed-input errors
85 * @param unmappableCharacterAction The encoder's action for unmappable-character errors
86 * @return The encoder for the specified {@code charset}
87 */
88 public static CharsetEncoder encoder(Charset charset, CodingErrorAction malformedInputAction,
89 CodingErrorAction unmappableCharacterAction) {
90 checkNotNull(charset, "charset");
91 CharsetEncoder e = charset.newEncoder();
92 e.onMalformedInput(malformedInputAction).onUnmappableCharacter(unmappableCharacterAction);
93 return e;
94 }
95
96 /**
97 * Returns a new {@link CharsetEncoder} for the {@link Charset} with the specified error action.
98 *
99 * @param charset The specified charset
100 * @param codingErrorAction The encoder's action for malformed-input and unmappable-character errors
101 * @return The encoder for the specified {@code charset}
102 */
103 public static CharsetEncoder encoder(Charset charset, CodingErrorAction codingErrorAction) {
104 return encoder(charset, codingErrorAction, codingErrorAction);
105 }
106
107 /**
108 * Returns a cached thread-local {@link CharsetEncoder} for the specified {@link Charset}.
109 *
110 * @param charset The specified charset
111 * @return The encoder for the specified {@code charset}
112 */
113 public static CharsetEncoder encoder(Charset charset) {
114 checkNotNull(charset, "charset");
115
116 Map<Charset, CharsetEncoder> map = InternalThreadLocalMap.get().charsetEncoderCache();
117 CharsetEncoder e = map.get(charset);
118 if (e != null) {
119 e.reset().onMalformedInput(CodingErrorAction.REPLACE).onUnmappableCharacter(CodingErrorAction.REPLACE);
120 return e;
121 }
122
123 e = encoder(charset, CodingErrorAction.REPLACE, CodingErrorAction.REPLACE);
124 map.put(charset, e);
125 return e;
126 }
127
128 /**
129 * @deprecated Use {@link #decoder(Charset)}.
130 */
131 @Deprecated
132 public static CharsetDecoder getDecoder(Charset charset) {
133 return decoder(charset);
134 }
135
136 /**
137 * Returns a new {@link CharsetDecoder} for the {@link Charset} with specified error actions.
138 *
139 * @param charset The specified charset
140 * @param malformedInputAction The decoder's action for malformed-input errors
141 * @param unmappableCharacterAction The decoder's action for unmappable-character errors
142 * @return The decoder for the specified {@code charset}
143 */
144 public static CharsetDecoder decoder(Charset charset, CodingErrorAction malformedInputAction,
145 CodingErrorAction unmappableCharacterAction) {
146 checkNotNull(charset, "charset");
147 CharsetDecoder d = charset.newDecoder();
148 d.onMalformedInput(malformedInputAction).onUnmappableCharacter(unmappableCharacterAction);
149 return d;
150 }
151
152 /**
153 * Returns a new {@link CharsetDecoder} for the {@link Charset} with the specified error action.
154 *
155 * @param charset The specified charset
156 * @param codingErrorAction The decoder's action for malformed-input and unmappable-character errors
157 * @return The decoder for the specified {@code charset}
158 */
159 public static CharsetDecoder decoder(Charset charset, CodingErrorAction codingErrorAction) {
160 return decoder(charset, codingErrorAction, codingErrorAction);
161 }
162
163 /**
164 * Returns a cached thread-local {@link CharsetDecoder} for the specified {@link Charset}.
165 *
166 * @param charset The specified charset
167 * @return The decoder for the specified {@code charset}
168 */
169 public static CharsetDecoder decoder(Charset charset) {
170 checkNotNull(charset, "charset");
171
172 Map<Charset, CharsetDecoder> map = InternalThreadLocalMap.get().charsetDecoderCache();
173 CharsetDecoder d = map.get(charset);
174 if (d != null) {
175 d.reset().onMalformedInput(CodingErrorAction.REPLACE).onUnmappableCharacter(CodingErrorAction.REPLACE);
176 return d;
177 }
178
179 d = decoder(charset, CodingErrorAction.REPLACE, CodingErrorAction.REPLACE);
180 map.put(charset, d);
181 return d;
182 }
183
184 private CharsetUtil() { }
185 }