charsetdecoder.java

JAVA基本类源代码,大家可以学习学习!

/*
 * @(#)Charset-X-Coder.java	1.37 03/01/23
 *
 * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

// -- This file was mechanically generated: Do not edit! -- //

package java.nio.charset;

import java.nio.Buffer;
import java.nio.ByteBuffer;
import java.nio.CharBuffer;
import java.nio.BufferOverflowException;
import java.nio.BufferUnderflowException;
import java.lang.ref.WeakReference;
import java.nio.charset.CoderMalfunctionError;			// javadoc


/**
 * An engine that can transform a sequence of bytes in a specific charset into a sequence of
 * sixteen-bit Unicode characters.
 *
 * <a name="steps">
 *
 * <p> The input byte sequence is provided in a byte buffer or a series
 * of such buffers.  The output character sequence is written to a character buffer
 * or a series of such buffers.  A decoder should always be used by making
 * the following sequence of method invocations, hereinafter referred to as a
 * <i>decoding operation</i>:
 *
 * <ol>
 *
 *   <li><p> Reset the decoder via the {@link #reset reset} method, unless it
 *   has not been used before; </p></li>
 *
 *   <li><p> Invoke the {@link #decode decode} method zero or more times, as
 *   long as additional input may be available, passing <tt>false</tt> for the
 *   <tt>endOfInput</tt> argument and filling the input buffer and flushing the
 *   output buffer between invocations; </p></li>
 *
 *   <li><p> Invoke the {@link #decode decode} method one final time, passing
 *   <tt>true</tt> for the <tt>endOfInput</tt> argument; and then </p></li>
 *
 *   <li><p> Invoke the {@link #flush flush} method so that the decoder can
 *   flush any internal state to the output buffer. </p></li>
 *
 * </ol>
 *
 * Each invocation of the {@link #decode decode} method will decode as many
 * bytes as possible from the input buffer, writing the resulting characters
 * to the output buffer.  The {@link #decode decode} method returns when more
 * input is required, when there is not enough room in the output buffer, or
 * when a decoding error has occurred.  In each case a {@link CoderResult}
 * object is returned to describe the reason for termination.  An invoker can
 * examine this object and fill the input buffer, flush the output buffer, or
 * attempt to recover from a decoding error, as appropriate, and try again.
 *
 * <a name="ce">
 *
 * <p> There are two general types of decoding errors.  If the input byte
 * sequence is not legal for this charset then the input is considered <i>malformed</i>.  If
 * the input byte sequence is legal but cannot be mapped to a valid
 * Unicode character then an <i>unmappable character</i> has been encountered.
 *
 * <a name="cae">
 *
 * <p> How a decoding error is handled depends upon the action requested for
 * that type of error, which is described by an instance of the {@link
 * CodingErrorAction} class.  The possible error actions are to {@link
 * CodingErrorAction#IGNORE </code>ignore<code>} the erroneous input, {@link
 * CodingErrorAction#REPORT </code>report<code>} the error to the invoker via
 * the returned {@link CoderResult} object, or {@link CodingErrorAction#REPLACE
 * </code>replace<code>} the erroneous input with the current value of the
 * replacement string.  The replacement
 *





 * has the initial value <tt>"&#92;uFFFD"</tt>;

 *
 * its value may be changed via the {@link #replaceWith(java.lang.String)
 * replaceWith} method.
 *
 * <p> The default action for malformed-input and unmappable-character errors
 * is to {@link CodingErrorAction#REPORT </code>report<code>} them.  The
 * malformed-input error action may be changed via the {@link
 * #onMalformedInput(CodingErrorAction) onMalformedInput} method; the
 * unmappable-character action may be changed via the {@link
 * #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter} method.
 *
 * <p> This class is designed to handle many of the details of the decoding
 * process, including the implementation of error actions.  A decoder for a
 * specific charset, which is a concrete subclass of this class, need only
 * implement the abstract {@link #decodeLoop decodeLoop} method, which
 * encapsulates the basic decoding loop.  A subclass that maintains internal
 * state should, additionally, override the {@link #flush flush} and {@link
 * #reset reset} methods.
 *
 * <p> Instances of this class are not safe for use by multiple concurrent
 * threads.  </p>
 *
 *
 * @version 1.37, 03/01/23
 * @author Mark Reinhold
 * @author JSR-51 Expert Group
 * @since 1.4
 *
 * @see ByteBuffer
 * @see CharBuffer
 * @see Charset
 * @see CharsetEncoder
 */

public abstract class CharsetDecoder {

    private final Charset charset;
    private final float averageCharsPerByte;
    private final float maxCharsPerByte;

    private String replacement;
    private CodingErrorAction malformedInputAction
	= CodingErrorAction.REPORT;
    private CodingErrorAction unmappableCharacterAction
	= CodingErrorAction.REPORT;

    // Internal states
    //
    private static final int ST_RESET   = 0;
    private static final int ST_CODING  = 1;
    private static final int ST_END     = 2;
    private static final int ST_FLUSHED = 3;

    private int state = ST_RESET;

    private static String stateNames[]
	= { "RESET", "CODING", "CODING_END", "FLUSHED" };


    /**
     * Initializes a new decoder.  The new decoder will have the given
     * chars-per-byte and replacement values. </p>
     *
     * @param  averageCharsPerByte
     *         A positive float value indicating the expected number of
     *         characters that will be produced for each input byte
     *
     * @param  maxCharsPerByte
     *         A positive float value indicating the maximum number of
     *         characters that will be produced for each input byte
     *
     * @param  replacement
     *         The initial replacement; must not be <tt>null</tt>, must have
     *         non-zero length, must not be longer than maxCharsPerByte,
     *         and must be {@link #isLegalReplacement </code>legal<code>}
     *
     * @throws  IllegalArgumentException
     *          If the preconditions on the parameters do not hold
     */
    private
    CharsetDecoder(Charset cs,
		   float averageCharsPerByte,
		   float maxCharsPerByte,
		   String replacement)
    {
	this.charset = cs;
	if (averageCharsPerByte <= 0.0f)
	    throw new IllegalArgumentException("Non-positive "
					       + "averageCharsPerByte");
	if (maxCharsPerByte <= 0.0f)
	    throw new IllegalArgumentException("Non-positive "
					       + "maxCharsPerByte");
	this.replacement = replacement;
	this.averageCharsPerByte = averageCharsPerByte;
	this.maxCharsPerByte = maxCharsPerByte;
	replaceWith(replacement);
    }

    /**
     * Initializes a new decoder.  The new decoder will have the given
     * chars-per-byte values and its replacement will be the
     * string <tt>"&#92;uFFFD"</tt>. </p>
     *
     * @param  averageCharsPerByte
     *         A positive float value indicating the expected number of
     *         characters that will be produced for each input byte
     *
     * @param  maxCharsPerByte
     *         A positive float value indicating the maximum number of
     *         characters that will be produced for each input byte
     *
     * @throws  IllegalArgumentException
     *          If the preconditions on the parameters do not hold
     */
    protected CharsetDecoder(Charset cs,
			     float averageCharsPerByte,
			     float maxCharsPerByte)
    {
	this(cs,
	     averageCharsPerByte, maxCharsPerByte,
	     "\uFFFD");
    }

    /**
     * Returns the charset that created this decoder.  </p>
     *
     * @return  This decoder's charset
     */
    public final Charset charset() {
	return charset;
    }

    /**
     * Returns this decoder's replacement value. </p>
     *
     * @return  This decoder's current replacement,
     *          which is never <tt>null</tt> and is never empty
     */
    public final String replacement() {
	return replacement;
    }

    /**
     * Changes this decoder's replacement value.
     *
     * <p> This method invokes the {@link #implReplaceWith implReplaceWith}
     * method, passing the new replacement, after checking that the new
     * replacement is acceptable.  </p>
     *
     * @param  newReplacement
     *

     *         The new replacement; must not be <tt>null</tt>
     *         and must have non-zero length







     *
     * @return  This decoder
     *
     * @throws  IllegalArgumentException
     *          If the preconditions on the parameter do not hold
     */
    public final CharsetDecoder replaceWith(String newReplacement) {
	if (newReplacement == null)
	    throw new IllegalArgumentException("Null replacement");
	int len = newReplacement.length();
	if (len == 0)
	    throw new IllegalArgumentException("Empty replacement");
	if (len > maxCharsPerByte)
	    throw new IllegalArgumentException("Replacement too long");




	this.replacement = newReplacement;
	implReplaceWith(newReplacement);
	return this;
    }

    /**
     * Reports a change to this decoder's replacement value.
     *
     * <p> The default implementation of this method does nothing.  This method
     * should be overridden by decoders that require notification of changes to
     * the replacement.  </p>
     *
     * @param  newReplacement
     */
    protected void implReplaceWith(String newReplacement) {
    }