KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > nio > charset > CoderResult


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