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.nio.charset.StandardCharsets;
26 import java.util.Map;
27
28 /**
29 * A utility class that provides various common operations and constants
30 * related with {@link Charset} and its relevant classes.
31 */
32 public final class CharsetUtil {
33
34 /**
35 * 16-bit UTF (UCS Transformation Format) whose byte order is identified by
36 * an optional byte-order mark
37 */
38 public static final Charset UTF_16 = StandardCharsets.UTF_16;
39
40 /**
41 * 16-bit UTF (UCS Transformation Format) whose byte order is big-endian
42 */
43 public static final Charset UTF_16BE = StandardCharsets.UTF_16BE;
44
45 /**
46 * 16-bit UTF (UCS Transformation Format) whose byte order is little-endian
47 */
48 public static final Charset UTF_16LE = StandardCharsets.UTF_16LE;
49
50 /**
51 * 8-bit UTF (UCS Transformation Format)
52 */
53 public static final Charset UTF_8 = StandardCharsets.UTF_8;
54
55 /**
56 * ISO Latin Alphabet No. 1, as known as <tt>ISO-LATIN-1</tt>
57 */
58 public static final Charset ISO_8859_1 = StandardCharsets.ISO_8859_1;
59
60 /**
61 * 7-bit ASCII, as known as ISO646-US or the Basic Latin block of the
62 * Unicode character set
63 */
64 public static final Charset US_ASCII = StandardCharsets.US_ASCII;
65
66 private static final Charset[] CHARSETS = new Charset[]
67 { UTF_16, UTF_16BE, UTF_16LE, UTF_8, ISO_8859_1, US_ASCII };
68
69 public static Charset[] values() {
70 return CHARSETS;
71 }
72
73 /**
74 * @deprecated Use {@link #encoder(Charset)}.
75 */
76 @Deprecated
77 public static CharsetEncoder getEncoder(Charset charset) {
78 return encoder(charset);
79 }
80
81 /**
82 * Returns a new {@link CharsetEncoder} for the {@link Charset} with specified error actions.
83 *
84 * @param charset The specified charset
85 * @param malformedInputAction The encoder's action for malformed-input errors
86 * @param unmappableCharacterAction The encoder's action for unmappable-character errors
87 * @return The encoder for the specified {@code charset}
88 */
89 public static CharsetEncoder encoder(Charset charset, CodingErrorAction malformedInputAction,
90 CodingErrorAction unmappableCharacterAction) {
91 checkNotNull(charset, "charset");
92 CharsetEncoder e = charset.newEncoder();
93 e.onMalformedInput(malformedInputAction).onUnmappableCharacter(unmappableCharacterAction);
94 return e;
95 }
96
97 /**
98 * Returns a new {@link CharsetEncoder} for the {@link Charset} with the specified error action.
99 *
100 * @param charset The specified charset
101 * @param codingErrorAction The encoder's action for malformed-input and unmappable-character errors
102 * @return The encoder for the specified {@code charset}
103 */
104 public static CharsetEncoder encoder(Charset charset, CodingErrorAction codingErrorAction) {
105 return encoder(charset, codingErrorAction, codingErrorAction);
106 }
107
108 /**
109 * Returns a cached thread-local {@link CharsetEncoder} for the specified {@link Charset}.
110 *
111 * @param charset The specified charset
112 * @return The encoder for the specified {@code charset}
113 */
114 public static CharsetEncoder encoder(Charset charset) {
115 checkNotNull(charset, "charset");
116
117 Map<Charset, CharsetEncoder> map = InternalThreadLocalMap.get().charsetEncoderCache();
118 CharsetEncoder e = map.get(charset);
119 if (e != null) {
120 e.reset().onMalformedInput(CodingErrorAction.REPLACE).onUnmappableCharacter(CodingErrorAction.REPLACE);
121 return e;
122 }
123
124 e = encoder(charset, CodingErrorAction.REPLACE, CodingErrorAction.REPLACE);
125 map.put(charset, e);
126 return e;
127 }
128
129 /**
130 * @deprecated Use {@link #decoder(Charset)}.
131 */
132 @Deprecated
133 public static CharsetDecoder getDecoder(Charset charset) {
134 return decoder(charset);
135 }
136
137 /**
138 * Returns a new {@link CharsetDecoder} for the {@link Charset} with specified error actions.
139 *
140 * @param charset The specified charset
141 * @param malformedInputAction The decoder's action for malformed-input errors
142 * @param unmappableCharacterAction The decoder's action for unmappable-character errors
143 * @return The decoder for the specified {@code charset}
144 */
145 public static CharsetDecoder decoder(Charset charset, CodingErrorAction malformedInputAction,
146 CodingErrorAction unmappableCharacterAction) {
147 checkNotNull(charset, "charset");
148 CharsetDecoder d = charset.newDecoder();
149 d.onMalformedInput(malformedInputAction).onUnmappableCharacter(unmappableCharacterAction);
150 return d;
151 }
152
153 /**
154 * Returns a new {@link CharsetDecoder} for the {@link Charset} with the specified error action.
155 *
156 * @param charset The specified charset
157 * @param codingErrorAction The decoder's action for malformed-input and unmappable-character errors
158 * @return The decoder for the specified {@code charset}
159 */
160 public static CharsetDecoder decoder(Charset charset, CodingErrorAction codingErrorAction) {
161 return decoder(charset, codingErrorAction, codingErrorAction);
162 }
163
164 /**
165 * Returns a cached thread-local {@link CharsetDecoder} for the specified {@link Charset}.
166 *
167 * @param charset The specified charset
168 * @return The decoder for the specified {@code charset}
169 */
170 public static CharsetDecoder decoder(Charset charset) {
171 checkNotNull(charset, "charset");
172
173 Map<Charset, CharsetDecoder> map = InternalThreadLocalMap.get().charsetDecoderCache();
174 CharsetDecoder d = map.get(charset);
175 if (d != null) {
176 d.reset().onMalformedInput(CodingErrorAction.REPLACE).onUnmappableCharacter(CodingErrorAction.REPLACE);
177 return d;
178 }
179
180 d = decoder(charset, CodingErrorAction.REPLACE, CodingErrorAction.REPLACE);
181 map.put(charset, d);
182 return d;
183 }
184
185 private CharsetUtil() { }
186 }