1/* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27// -- This file was mechanically generated: Do not edit! -- // 28 29package java.nio.charset; 30 31import java.nio.Buffer; 32import java.nio.ByteBuffer; 33import java.nio.CharBuffer; 34import java.nio.BufferOverflowException; 35import java.nio.BufferUnderflowException; 36import java.lang.ref.WeakReference; 37import java.nio.charset.CoderMalfunctionError; // javadoc 38 39 40/** 41 * An engine that can transform a sequence of bytes in a specific charset into a sequence of 42 * sixteen-bit Unicode characters. 43 * 44 * <a name="steps"> 45 * 46 * <p> The input byte sequence is provided in a byte buffer or a series 47 * of such buffers. The output character sequence is written to a character buffer 48 * or a series of such buffers. A decoder should always be used by making 49 * the following sequence of method invocations, hereinafter referred to as a 50 * <i>decoding operation</i>: 51 * 52 * <ol> 53 * 54 * <li><p> Reset the decoder via the {@link #reset reset} method, unless it 55 * has not been used before; </p></li> 56 * 57 * <li><p> Invoke the {@link #decode decode} method zero or more times, as 58 * long as additional input may be available, passing <tt>false</tt> for the 59 * <tt>endOfInput</tt> argument and filling the input buffer and flushing the 60 * output buffer between invocations; </p></li> 61 * 62 * <li><p> Invoke the {@link #decode decode} method one final time, passing 63 * <tt>true</tt> for the <tt>endOfInput</tt> argument; and then </p></li> 64 * 65 * <li><p> Invoke the {@link #flush flush} method so that the decoder can 66 * flush any internal state to the output buffer. </p></li> 67 * 68 * </ol> 69 * 70 * Each invocation of the {@link #decode decode} method will decode as many 71 * bytes as possible from the input buffer, writing the resulting characters 72 * to the output buffer. The {@link #decode decode} method returns when more 73 * input is required, when there is not enough room in the output buffer, or 74 * when a decoding error has occurred. In each case a {@link CoderResult} 75 * object is returned to describe the reason for termination. An invoker can 76 * examine this object and fill the input buffer, flush the output buffer, or 77 * attempt to recover from a decoding error, as appropriate, and try again. 78 * 79 * <a name="ce"> 80 * 81 * <p> There are two general types of decoding errors. If the input byte 82 * sequence is not legal for this charset then the input is considered <i>malformed</i>. If 83 * the input byte sequence is legal but cannot be mapped to a valid 84 * Unicode character then an <i>unmappable character</i> has been encountered. 85 * 86 * <a name="cae"> 87 * 88 * <p> How a decoding error is handled depends upon the action requested for 89 * that type of error, which is described by an instance of the {@link 90 * CodingErrorAction} class. The possible error actions are to {@link 91 * CodingErrorAction#IGNORE </code>ignore<code>} the erroneous input, {@link 92 * CodingErrorAction#REPORT </code>report<code>} the error to the invoker via 93 * the returned {@link CoderResult} object, or {@link CodingErrorAction#REPLACE 94 * </code>replace<code>} the erroneous input with the current value of the 95 * replacement string. The replacement 96 * 97 98 99 100 101 102 * has the initial value <tt>"\uFFFD"</tt>; 103 104 * 105 * its value may be changed via the {@link #replaceWith(java.lang.String) 106 * replaceWith} method. 107 * 108 * <p> The default action for malformed-input and unmappable-character errors 109 * is to {@link CodingErrorAction#REPORT </code>report<code>} them. The 110 * malformed-input error action may be changed via the {@link 111 * #onMalformedInput(CodingErrorAction) onMalformedInput} method; the 112 * unmappable-character action may be changed via the {@link 113 * #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter} method. 114 * 115 * <p> This class is designed to handle many of the details of the decoding 116 * process, including the implementation of error actions. A decoder for a 117 * specific charset, which is a concrete subclass of this class, need only 118 * implement the abstract {@link #decodeLoop decodeLoop} method, which 119 * encapsulates the basic decoding loop. A subclass that maintains internal 120 * state should, additionally, override the {@link #implFlush implFlush} and 121 * {@link #implReset implReset} methods. 122 * 123 * <p> Instances of this class are not safe for use by multiple concurrent 124 * threads. </p> 125 * 126 * 127 * @author Mark Reinhold 128 * @author JSR-51 Expert Group 129 * @since 1.4 130 * 131 * @see ByteBuffer 132 * @see CharBuffer 133 * @see Charset 134 * @see CharsetEncoder 135 */ 136 137public abstract class CharsetDecoder { 138 139 private final Charset charset; 140 private final float averageCharsPerByte; 141 private final float maxCharsPerByte; 142 143 private String replacement; 144 private CodingErrorAction malformedInputAction 145 = CodingErrorAction.REPORT; 146 private CodingErrorAction unmappableCharacterAction 147 = CodingErrorAction.REPORT; 148 149 // Internal states 150 // 151 private static final int ST_RESET = 0; 152 private static final int ST_CODING = 1; 153 private static final int ST_END = 2; 154 private static final int ST_FLUSHED = 3; 155 156 private int state = ST_RESET; 157 158 private static String stateNames[] 159 = { "RESET", "CODING", "CODING_END", "FLUSHED" }; 160 161 162 /** 163 * Initializes a new decoder. The new decoder will have the given 164 * chars-per-byte and replacement values. </p> 165 * 166 * @param averageCharsPerByte 167 * A positive float value indicating the expected number of 168 * characters that will be produced for each input byte 169 * 170 * @param maxCharsPerByte 171 * A positive float value indicating the maximum number of 172 * characters that will be produced for each input byte 173 * 174 * @param replacement 175 * The initial replacement; must not be <tt>null</tt>, must have 176 * non-zero length, must not be longer than maxCharsPerByte, 177 * and must be {@link #isLegalReplacement </code>legal<code>} 178 * 179 * @throws IllegalArgumentException 180 * If the preconditions on the parameters do not hold 181 */ 182 private 183 CharsetDecoder(Charset cs, 184 float averageCharsPerByte, 185 float maxCharsPerByte, 186 String replacement) 187 { 188 this.charset = cs; 189 if (averageCharsPerByte <= 0.0f) 190 throw new IllegalArgumentException("Non-positive " 191 + "averageCharsPerByte"); 192 if (maxCharsPerByte <= 0.0f) 193 throw new IllegalArgumentException("Non-positive " 194 + "maxCharsPerByte"); 195 if (!Charset.atBugLevel("1.4")) { 196 if (averageCharsPerByte > maxCharsPerByte) 197 throw new IllegalArgumentException("averageCharsPerByte" 198 + " exceeds " 199 + "maxCharsPerByte"); 200 } 201 this.replacement = replacement; 202 this.averageCharsPerByte = averageCharsPerByte; 203 this.maxCharsPerByte = maxCharsPerByte; 204 /* ----- BEGIN android ----- 205 replaceWith(replacement); 206 ----- END android ----- */ 207 } 208 209 /** 210 * Initializes a new decoder. The new decoder will have the given 211 * chars-per-byte values and its replacement will be the 212 * string <tt>"\uFFFD"</tt>. </p> 213 * 214 * @param averageCharsPerByte 215 * A positive float value indicating the expected number of 216 * characters that will be produced for each input byte 217 * 218 * @param maxCharsPerByte 219 * A positive float value indicating the maximum number of 220 * characters that will be produced for each input byte 221 * 222 * @throws IllegalArgumentException 223 * If the preconditions on the parameters do not hold 224 */ 225 protected CharsetDecoder(Charset cs, 226 float averageCharsPerByte, 227 float maxCharsPerByte) 228 { 229 this(cs, 230 averageCharsPerByte, maxCharsPerByte, 231 "\uFFFD"); 232 } 233 234 /** 235 * Returns the charset that created this decoder. </p> 236 * 237 * @return This decoder's charset 238 */ 239 public final Charset charset() { 240 return charset; 241 } 242 243 /** 244 * Returns this decoder's replacement value. </p> 245 * 246 * @return This decoder's current replacement, 247 * which is never <tt>null</tt> and is never empty 248 */ 249 public final String replacement() { 250 return replacement; 251 } 252 253 /** 254 * Changes this decoder's replacement value. 255 * 256 * <p> This method invokes the {@link #implReplaceWith implReplaceWith} 257 * method, passing the new replacement, after checking that the new 258 * replacement is acceptable. </p> 259 * 260 * @param newReplacement 261 * 262 263 * The new replacement; must not be <tt>null</tt> 264 * and must have non-zero length 265 266 267 268 269 270 271 272 * 273 * @return This decoder 274 * 275 * @throws IllegalArgumentException 276 * If the preconditions on the parameter do not hold 277 */ 278 public final CharsetDecoder replaceWith(String newReplacement) { 279 if (newReplacement == null) 280 throw new IllegalArgumentException("Null replacement"); 281 int len = newReplacement.length(); 282 if (len == 0) 283 throw new IllegalArgumentException("Empty replacement"); 284 if (len > maxCharsPerByte) 285 throw new IllegalArgumentException("Replacement too long"); 286 287 288 289 290 this.replacement = newReplacement; 291 implReplaceWith(newReplacement); 292 return this; 293 } 294 295 /** 296 * Reports a change to this decoder's replacement value. 297 * 298 * <p> The default implementation of this method does nothing. This method 299 * should be overridden by decoders that require notification of changes to 300 * the replacement. </p> 301 * 302 * @param newReplacement 303 */ 304 protected void implReplaceWith(String newReplacement) { 305 } 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 /** 348 * Returns this decoder's current action for malformed-input errors. </p> 349 * 350 * @return The current malformed-input action, which is never <tt>null</tt> 351 */ 352 public CodingErrorAction malformedInputAction() { 353 return malformedInputAction; 354 } 355 356 /** 357 * Changes this decoder's action for malformed-input errors. </p> 358 * 359 * <p> This method invokes the {@link #implOnMalformedInput 360 * implOnMalformedInput} method, passing the new action. </p> 361 * 362 * @param newAction The new action; must not be <tt>null</tt> 363 * 364 * @return This decoder 365 * 366 * @throws IllegalArgumentException 367 * If the precondition on the parameter does not hold 368 */ 369 public final CharsetDecoder onMalformedInput(CodingErrorAction newAction) { 370 if (newAction == null) 371 throw new IllegalArgumentException("Null action"); 372 malformedInputAction = newAction; 373 implOnMalformedInput(newAction); 374 return this; 375 } 376 377 /** 378 * Reports a change to this decoder's malformed-input action. 379 * 380 * <p> The default implementation of this method does nothing. This method 381 * should be overridden by decoders that require notification of changes to 382 * the malformed-input action. </p> 383 */ 384 protected void implOnMalformedInput(CodingErrorAction newAction) { } 385 386 /** 387 * Returns this decoder's current action for unmappable-character errors. 388 * </p> 389 * 390 * @return The current unmappable-character action, which is never 391 * <tt>null</tt> 392 */ 393 public CodingErrorAction unmappableCharacterAction() { 394 return unmappableCharacterAction; 395 } 396 397 /** 398 * Changes this decoder's action for unmappable-character errors. 399 * 400 * <p> This method invokes the {@link #implOnUnmappableCharacter 401 * implOnUnmappableCharacter} method, passing the new action. </p> 402 * 403 * @param newAction The new action; must not be <tt>null</tt> 404 * 405 * @return This decoder 406 * 407 * @throws IllegalArgumentException 408 * If the precondition on the parameter does not hold 409 */ 410 public final CharsetDecoder onUnmappableCharacter(CodingErrorAction 411 newAction) 412 { 413 if (newAction == null) 414 throw new IllegalArgumentException("Null action"); 415 unmappableCharacterAction = newAction; 416 implOnUnmappableCharacter(newAction); 417 return this; 418 } 419 420 /** 421 * Reports a change to this decoder's unmappable-character action. 422 * 423 * <p> The default implementation of this method does nothing. This method 424 * should be overridden by decoders that require notification of changes to 425 * the unmappable-character action. </p> 426 */ 427 protected void implOnUnmappableCharacter(CodingErrorAction newAction) { } 428 429 /** 430 * Returns the average number of characters that will be produced for each 431 * byte of input. This heuristic value may be used to estimate the size 432 * of the output buffer required for a given input sequence. </p> 433 * 434 * @return The average number of characters produced 435 * per byte of input 436 */ 437 public final float averageCharsPerByte() { 438 return averageCharsPerByte; 439 } 440 441 /** 442 * Returns the maximum number of characters that will be produced for each 443 * byte of input. This value may be used to compute the worst-case size 444 * of the output buffer required for a given input sequence. </p> 445 * 446 * @return The maximum number of characters that will be produced per 447 * byte of input 448 */ 449 public final float maxCharsPerByte() { 450 return maxCharsPerByte; 451 } 452 453 /** 454 * Decodes as many bytes as possible from the given input buffer, 455 * writing the results to the given output buffer. 456 * 457 * <p> The buffers are read from, and written to, starting at their current 458 * positions. At most {@link Buffer#remaining in.remaining()} bytes 459 * will be read and at most {@link Buffer#remaining out.remaining()} 460 * characters will be written. The buffers' positions will be advanced to 461 * reflect the bytes read and the characters written, but their marks and 462 * limits will not be modified. 463 * 464 * <p> In addition to reading bytes from the input buffer and writing 465 * characters to the output buffer, this method returns a {@link CoderResult} 466 * object to describe its reason for termination: 467 * 468 * <ul> 469 * 470 * <li><p> {@link CoderResult#UNDERFLOW} indicates that as much of the 471 * input buffer as possible has been decoded. If there is no further 472 * input then the invoker can proceed to the next step of the 473 * <a href="#steps">decoding operation</a>. Otherwise this method 474 * should be invoked again with further input. </p></li> 475 * 476 * <li><p> {@link CoderResult#OVERFLOW} indicates that there is 477 * insufficient space in the output buffer to decode any more bytes. 478 * This method should be invoked again with an output buffer that has 479 * more {@linkplain Buffer#remaining remaining} characters. This is 480 * typically done by draining any decoded characters from the output 481 * buffer. </p></li> 482 * 483 * <li><p> A {@link CoderResult#malformedForLength 484 * </code>malformed-input<code>} result indicates that a malformed-input 485 * error has been detected. The malformed bytes begin at the input 486 * buffer's (possibly incremented) position; the number of malformed 487 * bytes may be determined by invoking the result object's {@link 488 * CoderResult#length() length} method. This case applies only if the 489 * {@link #onMalformedInput </code>malformed action<code>} of this decoder 490 * is {@link CodingErrorAction#REPORT}; otherwise the malformed input 491 * will be ignored or replaced, as requested. </p></li> 492 * 493 * <li><p> An {@link CoderResult#unmappableForLength 494 * </code>unmappable-character<code>} result indicates that an 495 * unmappable-character error has been detected. The bytes that 496 * decode the unmappable character begin at the input buffer's (possibly 497 * incremented) position; the number of such bytes may be determined 498 * by invoking the result object's {@link CoderResult#length() length} 499 * method. This case applies only if the {@link #onUnmappableCharacter 500 * </code>unmappable action<code>} of this decoder is {@link 501 * CodingErrorAction#REPORT}; otherwise the unmappable character will be 502 * ignored or replaced, as requested. </p></li> 503 * 504 * </ul> 505 * 506 * In any case, if this method is to be reinvoked in the same decoding 507 * operation then care should be taken to preserve any bytes remaining 508 * in the input buffer so that they are available to the next invocation. 509 * 510 * <p> The <tt>endOfInput</tt> parameter advises this method as to whether 511 * the invoker can provide further input beyond that contained in the given 512 * input buffer. If there is a possibility of providing additional input 513 * then the invoker should pass <tt>false</tt> for this parameter; if there 514 * is no possibility of providing further input then the invoker should 515 * pass <tt>true</tt>. It is not erroneous, and in fact it is quite 516 * common, to pass <tt>false</tt> in one invocation and later discover that 517 * no further input was actually available. It is critical, however, that 518 * the final invocation of this method in a sequence of invocations always 519 * pass <tt>true</tt> so that any remaining undecoded input will be treated 520 * as being malformed. 521 * 522 * <p> This method works by invoking the {@link #decodeLoop decodeLoop} 523 * method, interpreting its results, handling error conditions, and 524 * reinvoking it as necessary. </p> 525 * 526 * 527 * @param in 528 * The input byte buffer 529 * 530 * @param out 531 * The output character buffer 532 * 533 * @param endOfInput 534 * <tt>true</tt> if, and only if, the invoker can provide no 535 * additional input bytes beyond those in the given buffer 536 * 537 * @return A coder-result object describing the reason for termination 538 * 539 * @throws IllegalStateException 540 * If a decoding operation is already in progress and the previous 541 * step was an invocation neither of the {@link #reset reset} 542 * method, nor of this method with a value of <tt>false</tt> for 543 * the <tt>endOfInput</tt> parameter, nor of this method with a 544 * value of <tt>true</tt> for the <tt>endOfInput</tt> parameter 545 * but a return value indicating an incomplete decoding operation 546 * 547 * @throws CoderMalfunctionError 548 * If an invocation of the decodeLoop method threw 549 * an unexpected exception 550 */ 551 public final CoderResult decode(ByteBuffer in, CharBuffer out, 552 boolean endOfInput) 553 { 554 int newState = endOfInput ? ST_END : ST_CODING; 555 if ((state != ST_RESET) && (state != ST_CODING) 556 && !(endOfInput && (state == ST_END))) 557 throwIllegalStateException(state, newState); 558 state = newState; 559 560 for (;;) { 561 562 CoderResult cr; 563 try { 564 cr = decodeLoop(in, out); 565 } catch (BufferUnderflowException x) { 566 throw new CoderMalfunctionError(x); 567 } catch (BufferOverflowException x) { 568 throw new CoderMalfunctionError(x); 569 } 570 571 if (cr.isOverflow()) 572 return cr; 573 574 if (cr.isUnderflow()) { 575 if (endOfInput && in.hasRemaining()) { 576 cr = CoderResult.malformedForLength(in.remaining()); 577 // Fall through to malformed-input case 578 } else { 579 return cr; 580 } 581 } 582 583 CodingErrorAction action = null; 584 if (cr.isMalformed()) 585 action = malformedInputAction; 586 else if (cr.isUnmappable()) 587 action = unmappableCharacterAction; 588 else 589 assert false : cr.toString(); 590 591 if (action == CodingErrorAction.REPORT) 592 return cr; 593 594 if (action == CodingErrorAction.REPLACE) { 595 if (out.remaining() < replacement.length()) 596 return CoderResult.OVERFLOW; 597 out.put(replacement); 598 } 599 600 if ((action == CodingErrorAction.IGNORE) 601 || (action == CodingErrorAction.REPLACE)) { 602 // Skip erroneous input either way 603 in.position(in.position() + cr.length()); 604 continue; 605 } 606 607 assert false; 608 } 609 610 } 611 612 /** 613 * Flushes this decoder. 614 * 615 * <p> Some decoders maintain internal state and may need to write some 616 * final characters to the output buffer once the overall input sequence has 617 * been read. 618 * 619 * <p> Any additional output is written to the output buffer beginning at 620 * its current position. At most {@link Buffer#remaining out.remaining()} 621 * characters will be written. The buffer's position will be advanced 622 * appropriately, but its mark and limit will not be modified. 623 * 624 * <p> If this method completes successfully then it returns {@link 625 * CoderResult#UNDERFLOW}. If there is insufficient room in the output 626 * buffer then it returns {@link CoderResult#OVERFLOW}. If this happens 627 * then this method must be invoked again, with an output buffer that has 628 * more room, in order to complete the current <a href="#steps">decoding 629 * operation</a>. 630 * 631 * <p> If this decoder has already been flushed then invoking this method 632 * has no effect. 633 * 634 * <p> This method invokes the {@link #implFlush implFlush} method to 635 * perform the actual flushing operation. </p> 636 * 637 * @param out 638 * The output character buffer 639 * 640 * @return A coder-result object, either {@link CoderResult#UNDERFLOW} or 641 * {@link CoderResult#OVERFLOW} 642 * 643 * @throws IllegalStateException 644 * If the previous step of the current decoding operation was an 645 * invocation neither of the {@link #flush flush} method nor of 646 * the three-argument {@link 647 * #decode(ByteBuffer,CharBuffer,boolean) decode} method 648 * with a value of <tt>true</tt> for the <tt>endOfInput</tt> 649 * parameter 650 */ 651 public final CoderResult flush(CharBuffer out) { 652 if (state == ST_END) { 653 CoderResult cr = implFlush(out); 654 if (cr.isUnderflow()) 655 state = ST_FLUSHED; 656 return cr; 657 } 658 659 if (state != ST_FLUSHED) 660 throwIllegalStateException(state, ST_FLUSHED); 661 662 return CoderResult.UNDERFLOW; // Already flushed 663 } 664 665 /** 666 * Flushes this decoder. 667 * 668 * <p> The default implementation of this method does nothing, and always 669 * returns {@link CoderResult#UNDERFLOW}. This method should be overridden 670 * by decoders that may need to write final characters to the output buffer 671 * once the entire input sequence has been read. </p> 672 * 673 * @param out 674 * The output character buffer 675 * 676 * @return A coder-result object, either {@link CoderResult#UNDERFLOW} or 677 * {@link CoderResult#OVERFLOW} 678 */ 679 protected CoderResult implFlush(CharBuffer out) { 680 return CoderResult.UNDERFLOW; 681 } 682 683 /** 684 * Resets this decoder, clearing any internal state. 685 * 686 * <p> This method resets charset-independent state and also invokes the 687 * {@link #implReset() implReset} method in order to perform any 688 * charset-specific reset actions. </p> 689 * 690 * @return This decoder 691 * 692 */ 693 public final CharsetDecoder reset() { 694 implReset(); 695 state = ST_RESET; 696 return this; 697 } 698 699 /** 700 * Resets this decoder, clearing any charset-specific internal state. 701 * 702 * <p> The default implementation of this method does nothing. This method 703 * should be overridden by decoders that maintain internal state. </p> 704 */ 705 protected void implReset() { } 706 707 /** 708 * Decodes one or more bytes into one or more characters. 709 * 710 * <p> This method encapsulates the basic decoding loop, decoding as many 711 * bytes as possible until it either runs out of input, runs out of room 712 * in the output buffer, or encounters a decoding error. This method is 713 * invoked by the {@link #decode decode} method, which handles result 714 * interpretation and error recovery. 715 * 716 * <p> The buffers are read from, and written to, starting at their current 717 * positions. At most {@link Buffer#remaining in.remaining()} bytes 718 * will be read, and at most {@link Buffer#remaining out.remaining()} 719 * characters will be written. The buffers' positions will be advanced to 720 * reflect the bytes read and the characters written, but their marks and 721 * limits will not be modified. 722 * 723 * <p> This method returns a {@link CoderResult} object to describe its 724 * reason for termination, in the same manner as the {@link #decode decode} 725 * method. Most implementations of this method will handle decoding errors 726 * by returning an appropriate result object for interpretation by the 727 * {@link #decode decode} method. An optimized implementation may instead 728 * examine the relevant error action and implement that action itself. 729 * 730 * <p> An implementation of this method may perform arbitrary lookahead by 731 * returning {@link CoderResult#UNDERFLOW} until it receives sufficient 732 * input. </p> 733 * 734 * @param in 735 * The input byte buffer 736 * 737 * @param out 738 * The output character buffer 739 * 740 * @return A coder-result object describing the reason for termination 741 */ 742 protected abstract CoderResult decodeLoop(ByteBuffer in, 743 CharBuffer out); 744 745 /** 746 * Convenience method that decodes the remaining content of a single input 747 * byte buffer into a newly-allocated character buffer. 748 * 749 * <p> This method implements an entire <a href="#steps">decoding 750 * operation</a>; that is, it resets this decoder, then it decodes the 751 * bytes in the given byte buffer, and finally it flushes this 752 * decoder. This method should therefore not be invoked if a decoding 753 * operation is already in progress. </p> 754 * 755 * @param in 756 * The input byte buffer 757 * 758 * @return A newly-allocated character buffer containing the result of the 759 * decoding operation. The buffer's position will be zero and its 760 * limit will follow the last character written. 761 * 762 * @throws IllegalStateException 763 * If a decoding operation is already in progress 764 * 765 * @throws MalformedInputException 766 * If the byte sequence starting at the input buffer's current 767 * position is not legal for this charset and the current malformed-input action 768 * is {@link CodingErrorAction#REPORT} 769 * 770 * @throws UnmappableCharacterException 771 * If the byte sequence starting at the input buffer's current 772 * position cannot be mapped to an equivalent character sequence and 773 * the current unmappable-character action is {@link 774 * CodingErrorAction#REPORT} 775 */ 776 public final CharBuffer decode(ByteBuffer in) 777 throws CharacterCodingException 778 { 779 int n = (int)(in.remaining() * averageCharsPerByte()); 780 CharBuffer out = CharBuffer.allocate(n); 781 782 if ((n == 0) && (in.remaining() == 0)) 783 return out; 784 reset(); 785 for (;;) { 786 CoderResult cr = in.hasRemaining() ? 787 decode(in, out, true) : CoderResult.UNDERFLOW; 788 if (cr.isUnderflow()) 789 cr = flush(out); 790 791 if (cr.isUnderflow()) 792 break; 793 if (cr.isOverflow()) { 794 n = 2*n + 1; // Ensure progress; n might be 0! 795 CharBuffer o = CharBuffer.allocate(n); 796 out.flip(); 797 o.put(out); 798 out = o; 799 continue; 800 } 801 cr.throwException(); 802 } 803 out.flip(); 804 return out; 805 } 806 807 808 809 /** 810 * Tells whether or not this decoder implements an auto-detecting charset. 811 * 812 * <p> The default implementation of this method always returns 813 * <tt>false</tt>; it should be overridden by auto-detecting decoders to 814 * return <tt>true</tt>. </p> 815 * 816 * @return <tt>true</tt> if, and only if, this decoder implements an 817 * auto-detecting charset 818 */ 819 public boolean isAutoDetecting() { 820 return false; 821 } 822 823 /** 824 * Tells whether or not this decoder has yet detected a 825 * charset <i>(optional operation)</i>. 826 * 827 * <p> If this decoder implements an auto-detecting charset then at a 828 * single point during a decoding operation this method may start returning 829 * <tt>true</tt> to indicate that a specific charset has been detected in 830 * the input byte sequence. Once this occurs, the {@link #detectedCharset 831 * detectedCharset} method may be invoked to retrieve the detected charset. 832 * 833 * <p> That this method returns <tt>false</tt> does not imply that no bytes 834 * have yet been decoded. Some auto-detecting decoders are capable of 835 * decoding some, or even all, of an input byte sequence without fixing on 836 * a particular charset. 837 * 838 * <p> The default implementation of this method always throws an {@link 839 * UnsupportedOperationException}; it should be overridden by 840 * auto-detecting decoders to return <tt>true</tt> once the input charset 841 * has been determined. </p> 842 * 843 * @return <tt>true</tt> if, and only if, this decoder has detected a 844 * specific charset 845 * 846 * @throws UnsupportedOperationException 847 * If this decoder does not implement an auto-detecting charset 848 */ 849 public boolean isCharsetDetected() { 850 throw new UnsupportedOperationException(); 851 } 852 853 /** 854 * Retrieves the charset that was detected by this 855 * decoder <i>(optional operation)</i>. 856 * 857 * <p> If this decoder implements an auto-detecting charset then this 858 * method returns the actual charset once it has been detected. After that 859 * point, this method returns the same value for the duration of the 860 * current decoding operation. If not enough input bytes have yet been 861 * read to determine the actual charset then this method throws an {@link 862 * IllegalStateException}. 863 * 864 * <p> The default implementation of this method always throws an {@link 865 * UnsupportedOperationException}; it should be overridden by 866 * auto-detecting decoders to return the appropriate value. </p> 867 * 868 * @return The charset detected by this auto-detecting decoder, 869 * or <tt>null</tt> if the charset has not yet been determined 870 * 871 * @throws IllegalStateException 872 * If insufficient bytes have been read to determine a charset 873 * 874 * @throws UnsupportedOperationException 875 * If this decoder does not implement an auto-detecting charset 876 */ 877 public Charset detectedCharset() { 878 throw new UnsupportedOperationException(); 879 } 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 private void throwIllegalStateException(int from, int to) { 971 throw new IllegalStateException("Current state = " + stateNames[from] 972 + ", new state = " + stateNames[to]); 973 } 974 975} 976