1133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski/* 22c87ad3a45cecf9e344487cad1abfdebe79f2c7cNarayan Kamath * Copyright (C) 2014 The Android Open Source Project 3133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved. 4133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 6133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 7133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 8133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 9133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 10133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 11133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 12133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 13133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 16133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * accompanied this code). 17133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 18133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * You should have received a copy of the GNU General Public License version 19133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 20133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 22133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 24133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * questions. 25133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 26133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 27133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski// -- This file was mechanically generated: Do not edit! -- // 28133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 29133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskipackage java.nio.charset; 30133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 31133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.nio.Buffer; 32133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.nio.ByteBuffer; 33133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.nio.CharBuffer; 34133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.nio.BufferOverflowException; 35133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.nio.BufferUnderflowException; 36133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.lang.ref.WeakReference; 37133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskiimport java.nio.charset.CoderMalfunctionError; // javadoc 38133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 39133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 40133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski/** 41133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * An engine that can transform a sequence of bytes in a specific charset into a sequence of 42133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * sixteen-bit Unicode characters. 43133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 44133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <a name="steps"> 45133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 46133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The input byte sequence is provided in a byte buffer or a series 47133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * of such buffers. The output character sequence is written to a character buffer 48133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * or a series of such buffers. A decoder should always be used by making 49133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the following sequence of method invocations, hereinafter referred to as a 50133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <i>decoding operation</i>: 51133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 52133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <ol> 53133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 54133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> Reset the decoder via the {@link #reset reset} method, unless it 55133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * has not been used before; </p></li> 56133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 57133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> Invoke the {@link #decode decode} method zero or more times, as 58133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * long as additional input may be available, passing <tt>false</tt> for the 59133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <tt>endOfInput</tt> argument and filling the input buffer and flushing the 60133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * output buffer between invocations; </p></li> 61133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 62133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> Invoke the {@link #decode decode} method one final time, passing 63133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <tt>true</tt> for the <tt>endOfInput</tt> argument; and then </p></li> 64133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 65133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> Invoke the {@link #flush flush} method so that the decoder can 66133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * flush any internal state to the output buffer. </p></li> 67133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 68133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </ol> 69133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 70133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Each invocation of the {@link #decode decode} method will decode as many 71133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * bytes as possible from the input buffer, writing the resulting characters 72133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * to the output buffer. The {@link #decode decode} method returns when more 73133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * input is required, when there is not enough room in the output buffer, or 74133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * when a decoding error has occurred. In each case a {@link CoderResult} 75133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * object is returned to describe the reason for termination. An invoker can 76133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * examine this object and fill the input buffer, flush the output buffer, or 77133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * attempt to recover from a decoding error, as appropriate, and try again. 78133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 79133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <a name="ce"> 80133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 81133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> There are two general types of decoding errors. If the input byte 82133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * sequence is not legal for this charset then the input is considered <i>malformed</i>. If 83133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the input byte sequence is legal but cannot be mapped to a valid 84133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Unicode character then an <i>unmappable character</i> has been encountered. 85133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 86133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <a name="cae"> 87133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 88133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> How a decoding error is handled depends upon the action requested for 89133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * that type of error, which is described by an instance of the {@link 90133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CodingErrorAction} class. The possible error actions are to {@link 91133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CodingErrorAction#IGNORE </code>ignore<code>} the erroneous input, {@link 92133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CodingErrorAction#REPORT </code>report<code>} the error to the invoker via 93133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the returned {@link CoderResult} object, or {@link CodingErrorAction#REPLACE 94133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </code>replace<code>} the erroneous input with the current value of the 95133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * replacement string. The replacement 96133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 97133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 98133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 99133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 100133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 101133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 102133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * has the initial value <tt>"\uFFFD"</tt>; 103133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 104133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 105133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * its value may be changed via the {@link #replaceWith(java.lang.String) 106133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * replaceWith} method. 107133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 108133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default action for malformed-input and unmappable-character errors 109133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * is to {@link CodingErrorAction#REPORT </code>report<code>} them. The 110133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * malformed-input error action may be changed via the {@link 111133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * #onMalformedInput(CodingErrorAction) onMalformedInput} method; the 112133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * unmappable-character action may be changed via the {@link 113133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter} method. 114133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 115133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This class is designed to handle many of the details of the decoding 116133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * process, including the implementation of error actions. A decoder for a 117133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * specific charset, which is a concrete subclass of this class, need only 118133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * implement the abstract {@link #decodeLoop decodeLoop} method, which 119133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * encapsulates the basic decoding loop. A subclass that maintains internal 120133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * state should, additionally, override the {@link #implFlush implFlush} and 121133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * {@link #implReset implReset} methods. 122133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 123133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> Instances of this class are not safe for use by multiple concurrent 124133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * threads. </p> 125133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 126133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 127133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @author Mark Reinhold 128133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @author JSR-51 Expert Group 129133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @since 1.4 130133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 131133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @see ByteBuffer 132133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @see CharBuffer 133133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @see Charset 134133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @see CharsetEncoder 135133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 136133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 137133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebskipublic abstract class CharsetDecoder { 138133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 139133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private final Charset charset; 140133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private final float averageCharsPerByte; 141133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private final float maxCharsPerByte; 142133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 143133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private String replacement; 144133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private CodingErrorAction malformedInputAction 145133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski = CodingErrorAction.REPORT; 146133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private CodingErrorAction unmappableCharacterAction 147133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski = CodingErrorAction.REPORT; 148133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 149133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski // Internal states 150133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski // 151133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private static final int ST_RESET = 0; 152133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private static final int ST_CODING = 1; 153133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private static final int ST_END = 2; 154133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private static final int ST_FLUSHED = 3; 155133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 156133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private int state = ST_RESET; 157133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 158133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private static String stateNames[] 159133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski = { "RESET", "CODING", "CODING_END", "FLUSHED" }; 160133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 161133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 162133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 163133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Initializes a new decoder. The new decoder will have the given 164133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * chars-per-byte and replacement values. </p> 165133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 166133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param averageCharsPerByte 167133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * A positive float value indicating the expected number of 168133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters that will be produced for each input byte 169133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 170133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param maxCharsPerByte 171133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * A positive float value indicating the maximum number of 172133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters that will be produced for each input byte 173133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 174133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param replacement 175133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The initial replacement; must not be <tt>null</tt>, must have 176133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * non-zero length, must not be longer than maxCharsPerByte, 177133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * and must be {@link #isLegalReplacement </code>legal<code>} 178133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 179133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalArgumentException 180133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the preconditions on the parameters do not hold 181133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 182133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private 183133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CharsetDecoder(Charset cs, 184133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski float averageCharsPerByte, 185133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski float maxCharsPerByte, 186133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski String replacement) 187133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski { 188133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski this.charset = cs; 189133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (averageCharsPerByte <= 0.0f) 190133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Non-positive " 191133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski + "averageCharsPerByte"); 192133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (maxCharsPerByte <= 0.0f) 193133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Non-positive " 194133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski + "maxCharsPerByte"); 195133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (!Charset.atBugLevel("1.4")) { 196133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (averageCharsPerByte > maxCharsPerByte) 197133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("averageCharsPerByte" 198133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski + " exceeds " 199133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski + "maxCharsPerByte"); 200133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 201133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski this.replacement = replacement; 202133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski this.averageCharsPerByte = averageCharsPerByte; 203133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski this.maxCharsPerByte = maxCharsPerByte; 204133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /* ----- BEGIN android ----- 205133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski replaceWith(replacement); 206133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski ----- END android ----- */ 207133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 208133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 209133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 210133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Initializes a new decoder. The new decoder will have the given 211133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * chars-per-byte values and its replacement will be the 212133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * string <tt>"\uFFFD"</tt>. </p> 213133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 214133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param averageCharsPerByte 215133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * A positive float value indicating the expected number of 216133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters that will be produced for each input byte 217133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 218133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param maxCharsPerByte 219133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * A positive float value indicating the maximum number of 220133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters that will be produced for each input byte 221133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 222133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalArgumentException 223133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the preconditions on the parameters do not hold 224133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 225133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected CharsetDecoder(Charset cs, 226133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski float averageCharsPerByte, 227133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski float maxCharsPerByte) 228133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski { 229133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski this(cs, 230133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski averageCharsPerByte, maxCharsPerByte, 231133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski "\uFFFD"); 232133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 233133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 234133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 235133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Returns the charset that created this decoder. </p> 236133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 237133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return This decoder's charset 238133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 239133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final Charset charset() { 240133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return charset; 241133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 242133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 243133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 244133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Returns this decoder's replacement value. </p> 245133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 246133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return This decoder's current replacement, 247133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * which is never <tt>null</tt> and is never empty 248133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 249133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final String replacement() { 250133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return replacement; 251133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 252133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 253133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 254133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Changes this decoder's replacement value. 255133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 256133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method invokes the {@link #implReplaceWith implReplaceWith} 257133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * method, passing the new replacement, after checking that the new 258133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * replacement is acceptable. </p> 259133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 260133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param newReplacement 261133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 262133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 263133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The new replacement; must not be <tt>null</tt> 264133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * and must have non-zero length 265133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 266133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 267133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 268133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 269133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 270133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 271133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 272133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 273133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return This decoder 274133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 275133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalArgumentException 276133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the preconditions on the parameter do not hold 277133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 278133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CharsetDecoder replaceWith(String newReplacement) { 279133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (newReplacement == null) 280133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Null replacement"); 281133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski int len = newReplacement.length(); 282133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (len == 0) 283133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Empty replacement"); 284133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (len > maxCharsPerByte) 285133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Replacement too long"); 286133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 287133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 288133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 289133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 290133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski this.replacement = newReplacement; 291133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski implReplaceWith(newReplacement); 292133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return this; 293133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 294133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 295133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 296133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Reports a change to this decoder's replacement value. 297133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 298133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method does nothing. This method 299133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * should be overridden by decoders that require notification of changes to 300133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the replacement. </p> 301133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 302133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param newReplacement 303133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 304133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected void implReplaceWith(String newReplacement) { 305133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 306133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 307133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 308133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 309133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 310133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 311133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 312133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 313133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 314133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 315133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 316133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 317133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 318133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 319133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 320133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 321133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 322133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 323133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 324133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 325133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 326133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 327133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 328133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 329133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 330133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 331133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 332133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 333133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 334133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 335133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 336133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 337133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 338133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 339133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 340133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 341133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 342133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 343133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 344133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 345133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 346133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 347133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 348133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Returns this decoder's current action for malformed-input errors. </p> 349133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 350133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return The current malformed-input action, which is never <tt>null</tt> 351133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 352133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public CodingErrorAction malformedInputAction() { 353133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return malformedInputAction; 354133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 355133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 356133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 357133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Changes this decoder's action for malformed-input errors. </p> 358133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 359133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method invokes the {@link #implOnMalformedInput 360133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * implOnMalformedInput} method, passing the new action. </p> 361133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 362133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param newAction The new action; must not be <tt>null</tt> 363133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 364133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return This decoder 365133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 366133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalArgumentException 367133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the precondition on the parameter does not hold 368133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 369133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CharsetDecoder onMalformedInput(CodingErrorAction newAction) { 370133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (newAction == null) 371133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Null action"); 372133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski malformedInputAction = newAction; 373133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski implOnMalformedInput(newAction); 374133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return this; 375133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 376133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 377133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 378133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Reports a change to this decoder's malformed-input action. 379133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 380133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method does nothing. This method 381133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * should be overridden by decoders that require notification of changes to 382133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the malformed-input action. </p> 383133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 384133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected void implOnMalformedInput(CodingErrorAction newAction) { } 385133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 386133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 387133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Returns this decoder's current action for unmappable-character errors. 388133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </p> 389133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 390133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return The current unmappable-character action, which is never 391133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <tt>null</tt> 392133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 393133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public CodingErrorAction unmappableCharacterAction() { 394133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return unmappableCharacterAction; 395133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 396133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 397133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 398133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Changes this decoder's action for unmappable-character errors. 399133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 400133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method invokes the {@link #implOnUnmappableCharacter 401133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * implOnUnmappableCharacter} method, passing the new action. </p> 402133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 403133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param newAction The new action; must not be <tt>null</tt> 404133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 405133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return This decoder 406133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 407133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalArgumentException 408133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the precondition on the parameter does not hold 409133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 410133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CharsetDecoder onUnmappableCharacter(CodingErrorAction 411133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski newAction) 412133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski { 413133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (newAction == null) 414133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalArgumentException("Null action"); 415133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski unmappableCharacterAction = newAction; 416133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski implOnUnmappableCharacter(newAction); 417133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return this; 418133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 419133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 420133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 421133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Reports a change to this decoder's unmappable-character action. 422133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 423133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method does nothing. This method 424133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * should be overridden by decoders that require notification of changes to 425133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the unmappable-character action. </p> 426133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 427133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected void implOnUnmappableCharacter(CodingErrorAction newAction) { } 428133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 429133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 430133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Returns the average number of characters that will be produced for each 431133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * byte of input. This heuristic value may be used to estimate the size 432133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * of the output buffer required for a given input sequence. </p> 433133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 434133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return The average number of characters produced 435133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * per byte of input 436133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 437133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final float averageCharsPerByte() { 438133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return averageCharsPerByte; 439133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 440133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 441133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 442133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Returns the maximum number of characters that will be produced for each 443133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * byte of input. This value may be used to compute the worst-case size 444133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * of the output buffer required for a given input sequence. </p> 445133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 446133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return The maximum number of characters that will be produced per 447133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * byte of input 448133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 449133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final float maxCharsPerByte() { 450133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return maxCharsPerByte; 451133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 452133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 453133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 454133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Decodes as many bytes as possible from the given input buffer, 455133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * writing the results to the given output buffer. 456133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 457133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The buffers are read from, and written to, starting at their current 458133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * positions. At most {@link Buffer#remaining in.remaining()} bytes 459133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * will be read and at most {@link Buffer#remaining out.remaining()} 460133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters will be written. The buffers' positions will be advanced to 461133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * reflect the bytes read and the characters written, but their marks and 462133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * limits will not be modified. 463133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 464133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> In addition to reading bytes from the input buffer and writing 465133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters to the output buffer, this method returns a {@link CoderResult} 466133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * object to describe its reason for termination: 467133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 468133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <ul> 469133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 470133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> {@link CoderResult#UNDERFLOW} indicates that as much of the 471133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * input buffer as possible has been decoded. If there is no further 472133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * input then the invoker can proceed to the next step of the 473133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <a href="#steps">decoding operation</a>. Otherwise this method 474133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * should be invoked again with further input. </p></li> 475133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 476133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> {@link CoderResult#OVERFLOW} indicates that there is 477133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * insufficient space in the output buffer to decode any more bytes. 478133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * This method should be invoked again with an output buffer that has 479133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * more {@linkplain Buffer#remaining remaining} characters. This is 480133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * typically done by draining any decoded characters from the output 481133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * buffer. </p></li> 482133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 483133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> A {@link CoderResult#malformedForLength 484133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </code>malformed-input<code>} result indicates that a malformed-input 485133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * error has been detected. The malformed bytes begin at the input 486133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * buffer's (possibly incremented) position; the number of malformed 487133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * bytes may be determined by invoking the result object's {@link 488133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CoderResult#length() length} method. This case applies only if the 489133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * {@link #onMalformedInput </code>malformed action<code>} of this decoder 490133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * is {@link CodingErrorAction#REPORT}; otherwise the malformed input 491133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * will be ignored or replaced, as requested. </p></li> 492133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 493133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <li><p> An {@link CoderResult#unmappableForLength 494133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </code>unmappable-character<code>} result indicates that an 495133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * unmappable-character error has been detected. The bytes that 496133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * decode the unmappable character begin at the input buffer's (possibly 497133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * incremented) position; the number of such bytes may be determined 498133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * by invoking the result object's {@link CoderResult#length() length} 499133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * method. This case applies only if the {@link #onUnmappableCharacter 500133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </code>unmappable action<code>} of this decoder is {@link 501133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CodingErrorAction#REPORT}; otherwise the unmappable character will be 502133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * ignored or replaced, as requested. </p></li> 503133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 504133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * </ul> 505133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 506133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * In any case, if this method is to be reinvoked in the same decoding 507133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * operation then care should be taken to preserve any bytes remaining 508133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * in the input buffer so that they are available to the next invocation. 509133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 510133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The <tt>endOfInput</tt> parameter advises this method as to whether 511133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the invoker can provide further input beyond that contained in the given 512133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * input buffer. If there is a possibility of providing additional input 513133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * then the invoker should pass <tt>false</tt> for this parameter; if there 514133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * is no possibility of providing further input then the invoker should 515133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * pass <tt>true</tt>. It is not erroneous, and in fact it is quite 516133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * common, to pass <tt>false</tt> in one invocation and later discover that 517133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * no further input was actually available. It is critical, however, that 518133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the final invocation of this method in a sequence of invocations always 519133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * pass <tt>true</tt> so that any remaining undecoded input will be treated 520133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * as being malformed. 521133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 522133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method works by invoking the {@link #decodeLoop decodeLoop} 523133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * method, interpreting its results, handling error conditions, and 524133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * reinvoking it as necessary. </p> 525133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 526133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 527133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param in 528133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The input byte buffer 529133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 530133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param out 531133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The output character buffer 532133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 533133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param endOfInput 534133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <tt>true</tt> if, and only if, the invoker can provide no 535133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * additional input bytes beyond those in the given buffer 536133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 537133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return A coder-result object describing the reason for termination 538133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 539133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalStateException 540133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If a decoding operation is already in progress and the previous 541133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * step was an invocation neither of the {@link #reset reset} 542133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * method, nor of this method with a value of <tt>false</tt> for 543133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the <tt>endOfInput</tt> parameter, nor of this method with a 544133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * value of <tt>true</tt> for the <tt>endOfInput</tt> parameter 545133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * but a return value indicating an incomplete decoding operation 546133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 547133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws CoderMalfunctionError 548133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If an invocation of the decodeLoop method threw 549133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * an unexpected exception 550133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 551133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CoderResult decode(ByteBuffer in, CharBuffer out, 552133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski boolean endOfInput) 553133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski { 554133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski int newState = endOfInput ? ST_END : ST_CODING; 555133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if ((state != ST_RESET) && (state != ST_CODING) 556133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski && !(endOfInput && (state == ST_END))) 557133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throwIllegalStateException(state, newState); 558133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski state = newState; 559133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 560133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski for (;;) { 561133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 562133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CoderResult cr; 563133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski try { 564133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski cr = decodeLoop(in, out); 565133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } catch (BufferUnderflowException x) { 566133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new CoderMalfunctionError(x); 567133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } catch (BufferOverflowException x) { 568133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new CoderMalfunctionError(x); 569133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 570133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 571133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isOverflow()) 572133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return cr; 573133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 574133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isUnderflow()) { 575133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (endOfInput && in.hasRemaining()) { 576133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski cr = CoderResult.malformedForLength(in.remaining()); 577133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski // Fall through to malformed-input case 578133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } else { 579133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return cr; 580133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 581133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 582133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 583133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CodingErrorAction action = null; 584133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isMalformed()) 585133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski action = malformedInputAction; 586133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski else if (cr.isUnmappable()) 587133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski action = unmappableCharacterAction; 588133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski else 589133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski assert false : cr.toString(); 590133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 591133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (action == CodingErrorAction.REPORT) 592133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return cr; 593133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 594133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (action == CodingErrorAction.REPLACE) { 595133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (out.remaining() < replacement.length()) 596133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return CoderResult.OVERFLOW; 597133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski out.put(replacement); 598133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 599133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 600133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if ((action == CodingErrorAction.IGNORE) 601133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski || (action == CodingErrorAction.REPLACE)) { 602133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski // Skip erroneous input either way 603133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski in.position(in.position() + cr.length()); 604133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski continue; 605133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 606133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 607133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski assert false; 608133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 609133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 610133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 611133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 612133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 613133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Flushes this decoder. 614133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 615133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> Some decoders maintain internal state and may need to write some 616133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * final characters to the output buffer once the overall input sequence has 617133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * been read. 618133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 619133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> Any additional output is written to the output buffer beginning at 620133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * its current position. At most {@link Buffer#remaining out.remaining()} 621133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters will be written. The buffer's position will be advanced 622133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * appropriately, but its mark and limit will not be modified. 623133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 624133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> If this method completes successfully then it returns {@link 625133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CoderResult#UNDERFLOW}. If there is insufficient room in the output 626133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * buffer then it returns {@link CoderResult#OVERFLOW}. If this happens 627133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * then this method must be invoked again, with an output buffer that has 628133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * more room, in order to complete the current <a href="#steps">decoding 629133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * operation</a>. 630133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 631133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> If this decoder has already been flushed then invoking this method 632133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * has no effect. 633133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 634133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method invokes the {@link #implFlush implFlush} method to 635133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * perform the actual flushing operation. </p> 636133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 637133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param out 638133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The output character buffer 639133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 640133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return A coder-result object, either {@link CoderResult#UNDERFLOW} or 641133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * {@link CoderResult#OVERFLOW} 642133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 643133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalStateException 644133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the previous step of the current decoding operation was an 645133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * invocation neither of the {@link #flush flush} method nor of 646133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the three-argument {@link 647133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * #decode(ByteBuffer,CharBuffer,boolean) decode} method 648133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * with a value of <tt>true</tt> for the <tt>endOfInput</tt> 649133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * parameter 650133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 651133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CoderResult flush(CharBuffer out) { 652133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (state == ST_END) { 653133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CoderResult cr = implFlush(out); 654133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isUnderflow()) 655133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski state = ST_FLUSHED; 656133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return cr; 657133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 658133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 659133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (state != ST_FLUSHED) 660133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throwIllegalStateException(state, ST_FLUSHED); 661133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 662133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return CoderResult.UNDERFLOW; // Already flushed 663133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 664133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 665133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 666133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Flushes this decoder. 667133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 668133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method does nothing, and always 669133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * returns {@link CoderResult#UNDERFLOW}. This method should be overridden 670133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * by decoders that may need to write final characters to the output buffer 671133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * once the entire input sequence has been read. </p> 672133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 673133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param out 674133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The output character buffer 675133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 676133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return A coder-result object, either {@link CoderResult#UNDERFLOW} or 677133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * {@link CoderResult#OVERFLOW} 678133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 679133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected CoderResult implFlush(CharBuffer out) { 680133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return CoderResult.UNDERFLOW; 681133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 682133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 683133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 684133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Resets this decoder, clearing any internal state. 685133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 686133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method resets charset-independent state and also invokes the 687133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * {@link #implReset() implReset} method in order to perform any 688133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * charset-specific reset actions. </p> 689133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 690133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return This decoder 691133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 692133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 693133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CharsetDecoder reset() { 694133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski implReset(); 695133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski state = ST_RESET; 696133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return this; 697133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 698133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 699133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 700133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Resets this decoder, clearing any charset-specific internal state. 701133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 702133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method does nothing. This method 703133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * should be overridden by decoders that maintain internal state. </p> 704133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 705133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected void implReset() { } 706133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 707133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 708133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Decodes one or more bytes into one or more characters. 709133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 710133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method encapsulates the basic decoding loop, decoding as many 711133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * bytes as possible until it either runs out of input, runs out of room 712133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * in the output buffer, or encounters a decoding error. This method is 713133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * invoked by the {@link #decode decode} method, which handles result 714133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * interpretation and error recovery. 715133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 716133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The buffers are read from, and written to, starting at their current 717133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * positions. At most {@link Buffer#remaining in.remaining()} bytes 718133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * will be read, and at most {@link Buffer#remaining out.remaining()} 719133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * characters will be written. The buffers' positions will be advanced to 720133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * reflect the bytes read and the characters written, but their marks and 721133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * limits will not be modified. 722133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 723133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method returns a {@link CoderResult} object to describe its 724133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * reason for termination, in the same manner as the {@link #decode decode} 725133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * method. Most implementations of this method will handle decoding errors 726133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * by returning an appropriate result object for interpretation by the 727133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * {@link #decode decode} method. An optimized implementation may instead 728133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * examine the relevant error action and implement that action itself. 729133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 730133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> An implementation of this method may perform arbitrary lookahead by 731133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * returning {@link CoderResult#UNDERFLOW} until it receives sufficient 732133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * input. </p> 733133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 734133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param in 735133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The input byte buffer 736133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 737133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param out 738133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The output character buffer 739133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 740133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return A coder-result object describing the reason for termination 741133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 742133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski protected abstract CoderResult decodeLoop(ByteBuffer in, 743133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CharBuffer out); 744133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 745133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 746133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Convenience method that decodes the remaining content of a single input 747133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * byte buffer into a newly-allocated character buffer. 748133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 749133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> This method implements an entire <a href="#steps">decoding 750133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * operation</a>; that is, it resets this decoder, then it decodes the 751133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * bytes in the given byte buffer, and finally it flushes this 752133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * decoder. This method should therefore not be invoked if a decoding 753133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * operation is already in progress. </p> 754133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 755133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @param in 756133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * The input byte buffer 757133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 758133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return A newly-allocated character buffer containing the result of the 759133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * decoding operation. The buffer's position will be zero and its 760133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * limit will follow the last character written. 761133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 762133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalStateException 763133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If a decoding operation is already in progress 764133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 765133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws MalformedInputException 766133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the byte sequence starting at the input buffer's current 767133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * position is not legal for this charset and the current malformed-input action 768133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * is {@link CodingErrorAction#REPORT} 769133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 770133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws UnmappableCharacterException 771133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If the byte sequence starting at the input buffer's current 772133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * position cannot be mapped to an equivalent character sequence and 773133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the current unmappable-character action is {@link 774133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * CodingErrorAction#REPORT} 775133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 776133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public final CharBuffer decode(ByteBuffer in) 777133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throws CharacterCodingException 778133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski { 779133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski int n = (int)(in.remaining() * averageCharsPerByte()); 780133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CharBuffer out = CharBuffer.allocate(n); 781133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 782133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if ((n == 0) && (in.remaining() == 0)) 783133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return out; 784133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski reset(); 785133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski for (;;) { 786133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CoderResult cr = in.hasRemaining() ? 787133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski decode(in, out, true) : CoderResult.UNDERFLOW; 788133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isUnderflow()) 789133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski cr = flush(out); 790133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 791133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isUnderflow()) 792133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski break; 793133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski if (cr.isOverflow()) { 794133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski n = 2*n + 1; // Ensure progress; n might be 0! 795133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski CharBuffer o = CharBuffer.allocate(n); 796133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski out.flip(); 797133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski o.put(out); 798133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski out = o; 799133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski continue; 800133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 801133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski cr.throwException(); 802133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 803133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski out.flip(); 804133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return out; 805133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 806133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 807133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 808133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 809133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 810133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Tells whether or not this decoder implements an auto-detecting charset. 811133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 812133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method always returns 813133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <tt>false</tt>; it should be overridden by auto-detecting decoders to 814133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * return <tt>true</tt>. </p> 815133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 816133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return <tt>true</tt> if, and only if, this decoder implements an 817133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * auto-detecting charset 818133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 819133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public boolean isAutoDetecting() { 820133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski return false; 821133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 822133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 823133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 824133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Tells whether or not this decoder has yet detected a 825133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * charset <i>(optional operation)</i>. 826133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 827133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> If this decoder implements an auto-detecting charset then at a 828133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * single point during a decoding operation this method may start returning 829133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <tt>true</tt> to indicate that a specific charset has been detected in 830133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * the input byte sequence. Once this occurs, the {@link #detectedCharset 831133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * detectedCharset} method may be invoked to retrieve the detected charset. 832133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 833133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> That this method returns <tt>false</tt> does not imply that no bytes 834133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * have yet been decoded. Some auto-detecting decoders are capable of 835133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * decoding some, or even all, of an input byte sequence without fixing on 836133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * a particular charset. 837133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 838133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method always throws an {@link 839133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * UnsupportedOperationException}; it should be overridden by 840133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * auto-detecting decoders to return <tt>true</tt> once the input charset 841133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * has been determined. </p> 842133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 843133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return <tt>true</tt> if, and only if, this decoder has detected a 844133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * specific charset 845133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 846133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws UnsupportedOperationException 847133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If this decoder does not implement an auto-detecting charset 848133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 849133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public boolean isCharsetDetected() { 850133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new UnsupportedOperationException(); 851133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 852133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 853133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski /** 854133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * Retrieves the charset that was detected by this 855133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * decoder <i>(optional operation)</i>. 856133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 857133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> If this decoder implements an auto-detecting charset then this 858133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * method returns the actual charset once it has been detected. After that 859133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * point, this method returns the same value for the duration of the 860133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * current decoding operation. If not enough input bytes have yet been 861133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * read to determine the actual charset then this method throws an {@link 862133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * IllegalStateException}. 863133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 864133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * <p> The default implementation of this method always throws an {@link 865133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * UnsupportedOperationException}; it should be overridden by 866133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * auto-detecting decoders to return the appropriate value. </p> 867133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 868133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @return The charset detected by this auto-detecting decoder, 869133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * or <tt>null</tt> if the charset has not yet been determined 870133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 871133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws IllegalStateException 872133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If insufficient bytes have been read to determine a charset 873133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * 874133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * @throws UnsupportedOperationException 875133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski * If this decoder does not implement an auto-detecting charset 876133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski */ 877133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski public Charset detectedCharset() { 878133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new UnsupportedOperationException(); 879133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 880133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 881133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 882133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 883133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 884133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 885133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 886133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 887133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 888133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 889133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 890133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 891133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 892133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 893133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 894133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 895133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 896133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 897133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 898133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 899133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 900133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 901133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 902133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 903133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 904133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 905133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 906133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 907133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 908133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 909133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 910133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 911133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 912133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 913133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 914133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 915133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 916133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 917133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 918133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 919133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 920133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 921133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 922133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 923133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 924133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 925133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 926133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 927133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 928133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 929133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 930133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 931133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 932133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 933133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 934133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 935133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 936133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 937133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 938133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 939133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 940133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 941133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 942133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 943133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 944133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 945133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 946133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 947133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 948133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 949133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 950133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 951133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 952133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 953133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 954133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 955133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 956133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 957133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 958133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 959133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 960133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 961133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 962133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 963133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 964133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 965133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 966133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 967133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 968133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 969133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 970133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski private void throwIllegalStateException(int from, int to) { 971133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski throw new IllegalStateException("Current state = " + stateNames[from] 972133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski + ", new state = " + stateNames[to]); 973133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski } 974133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski 975133892a64c416abdb5d19c77ec3194aeb789b34fPiotr Jastrzebski} 976