1 /*
2 * Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.nio.charset;
27
28 import java.lang.ref.WeakReference;
29 import java.nio.*;
30 import java.util.Map;
31 import java.util.HashMap;
32
33
34 /**
35 * A description of the result state of a coder.
36 *
37 * <p> A charset coder, that is, either a decoder or an encoder, consumes bytes
38 * (or characters) from an input buffer, translates them, and writes the
39 * resulting characters (or bytes) to an output buffer. A coding process
40 * terminates for one of four categories of reasons, which are described by
41 * instances of this class:
42 *
43 * <ul>
44 *
45 * <li><p> <i>Underflow</i> is reported when there is no more input to be
46 * processed, or there is insufficient input and additional input is
47 * required. This condition is represented by the unique result object
48 * {@link #UNDERFLOW}, whose {@link #isUnderflow() isUnderflow} method
49 * returns <tt>true</tt>. </p></li>
50 *
51 * <li><p> <i>Overflow</i> is reported when there is insufficient room
52 * remaining in the output buffer. This condition is represented by the
53 * unique result object {@link #OVERFLOW}, whose {@link #isOverflow()
54 * isOverflow} method returns <tt>true</tt>. </p></li>
55 *
56 * <li><p> A <i>malformed-input error</i> is reported when a sequence of
57 * input units is not well-formed. Such errors are described by instances of
58 * this class whose {@link #isMalformed() isMalformed} method returns
59 * <tt>true</tt> and whose {@link #length() length} method returns the length
60 * of the malformed sequence. There is one unique instance of this class for
61 * all malformed-input errors of a given length. </p></li>
62 *
63 * <li><p> An <i>unmappable-character error</i> is reported when a sequence
64 * of input units denotes a character that cannot be represented in the
65 * output charset. Such errors are described by instances of this class
66 * whose {@link #isUnmappable() isUnmappable} method returns <tt>true</tt> and
67 * whose {@link #length() length} method returns the length of the input
68 * sequence denoting the unmappable character. There is one unique instance
69 * of this class for all unmappable-character errors of a given length.
70 * </p></li>
71 *
72 * </ul>
73 *
74 * <p> For convenience, the {@link #isError() isError} method returns <tt>true</tt>
75 * for result objects that describe malformed-input and unmappable-character
76 * errors but <tt>false</tt> for those that describe underflow or overflow
77 * conditions. </p>
78 *
79 *
80 * @author Mark Reinhold
81 * @author JSR-51 Expert Group
82 * @since 1.4
83 */
84
85 public class CoderResult {
86
87 private static final int CR_UNDERFLOW = 0;
88 private static final int CR_OVERFLOW = 1;
89 private static final int CR_ERROR_MIN = 2;
90 private static final int CR_MALFORMED = 2;
91 private static final int CR_UNMAPPABLE = 3;
92
93 private static final String[] names
94 = { "UNDERFLOW", "OVERFLOW", "MALFORMED", "UNMAPPABLE" };
95
96 private final int type;
97 private final int length;
98
99 private CoderResult(int type, int length) {
100 this.type = type;
101 this.length = length;
102 }
103
104 /**
105 * Returns a string describing this coder result.
106 *
107 * @return A descriptive string
108 */
109 public String toString() {
110 String nm = names[type];
111 return isError() ? nm + "[" + length + "]" : nm;
112 }
113
114 /**
115 * Tells whether or not this object describes an underflow condition.
116 *
117 * @return <tt>true</tt> if, and only if, this object denotes underflow
118 */
119 public boolean isUnderflow() {
120 return (type == CR_UNDERFLOW);
121 }
122
123 /**
124 * Tells whether or not this object describes an overflow condition.
125 *
126 * @return <tt>true</tt> if, and only if, this object denotes overflow
127 */
128 public boolean isOverflow() {
129 return (type == CR_OVERFLOW);
130 }
131
132 /**
133 * Tells whether or not this object describes an error condition.
134 *
135 * @return <tt>true</tt> if, and only if, this object denotes either a
136 * malformed-input error or an unmappable-character error
137 */
138 public boolean isError() {
139 return (type >= CR_ERROR_MIN);
140 }
141
142 /**
143 * Tells whether or not this object describes a malformed-input error.
144 *
145 * @return <tt>true</tt> if, and only if, this object denotes a
146 * malformed-input error
147 */
148 public boolean isMalformed() {
149 return (type == CR_MALFORMED);
150 }
151
152 /**
153 * Tells whether or not this object describes an unmappable-character
154 * error.
155 *
156 * @return <tt>true</tt> if, and only if, this object denotes an
157 * unmappable-character error
158 */
159 public boolean isUnmappable() {
160 return (type == CR_UNMAPPABLE);
161 }
162
163 /**
164 * Returns the length of the erroneous input described by this
165 * object <i>(optional operation)</i>.
166 *
167 * @return The length of the erroneous input, a positive integer
168 *
169 * @throws UnsupportedOperationException
170 * If this object does not describe an error condition, that is,
171 * if the {@link #isError() isError} does not return <tt>true</tt>
172 */
173 public int length() {
174 if (!isError())
175 throw new UnsupportedOperationException();
176 return length;
177 }
178
179 /**
180 * Result object indicating underflow, meaning that either the input buffer
181 * has been completely consumed or, if the input buffer is not yet empty,
182 * that additional input is required.
183 */
184 public static final CoderResult UNDERFLOW
185 = new CoderResult(CR_UNDERFLOW, 0);
186
187 /**
188 * Result object indicating overflow, meaning that there is insufficient
189 * room in the output buffer.
190 */
191 public static final CoderResult OVERFLOW
192 = new CoderResult(CR_OVERFLOW, 0);
193
194 private static abstract class Cache {
195
196 private Map<Integer,WeakReference<CoderResult>> cache = null;
197
198 protected abstract CoderResult create(int len);
199
200 private synchronized CoderResult get(int len) {
201 if (len <= 0)
202 throw new IllegalArgumentException("Non-positive length");
203 Integer k = len;
204 WeakReference<CoderResult> w;
205 CoderResult e = null;
206 if (cache == null) {
207 cache = new HashMap<>();
208 } else if ((w = cache.get(k)) != null) {
209 e = w.get();
210 }
211 if (e == null) {
212 e = create(len);
213 cache.put(k, new WeakReference<>(e));
214 }
215 return e;
216 }
217
218 }
219
220 private static Cache malformedCache
221 = new Cache() {
222 public CoderResult create(int len) {
223 return new CoderResult(CR_MALFORMED, len);
224 }};
225
226 /**
227 * Static factory method that returns the unique object describing a
228 * malformed-input error of the given length.
229 *
230 * @param length
231 * The given length
232 *
233 * @return The requested coder-result object
234 */
235 public static CoderResult malformedForLength(int length) {
236 return malformedCache.get(length);
237 }
238
239 private static Cache unmappableCache
240 = new Cache() {
241 public CoderResult create(int len) {
242 return new CoderResult(CR_UNMAPPABLE, len);
243 }};
244
245 /**
246 * Static factory method that returns the unique result object describing
247 * an unmappable-character error of the given length.
248 *
249 * @param length
250 * The given length
251 *
252 * @return The requested coder-result object
253 */
254 public static CoderResult unmappableForLength(int length) {
255 return unmappableCache.get(length);
256 }
257
258 /**
259 * Throws an exception appropriate to the result described by this object.
260 *
261 * @throws BufferUnderflowException
262 * If this object is {@link #UNDERFLOW}
263 *
264 * @throws BufferOverflowException
265 * If this object is {@link #OVERFLOW}
266 *
267 * @throws MalformedInputException
268 * If this object represents a malformed-input error; the
269 * exception's length value will be that of this object
270 *
271 * @throws UnmappableCharacterException
272 * If this object represents an unmappable-character error; the
273 * exceptions length value will be that of this object
274 */
275 public void throwException()
276 throws CharacterCodingException
277 {
278 switch (type) {
279 case CR_UNDERFLOW: throw new BufferUnderflowException();
280 case CR_OVERFLOW: throw new BufferOverflowException();
281 case CR_MALFORMED: throw new MalformedInputException(length);
282 case CR_UNMAPPABLE: throw new UnmappableCharacterException(length);
283 default:
284 assert false;
285 }
286 }
287
288 }