charsetencoder.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 sixteen-bit Unicode characters into a sequence of
 * bytes in a specific charset.
 *
 * <a name="steps">
 *
 * <p> The input character sequence is provided in a character buffer or a series
 * of such buffers.  The output byte sequence is written to a byte buffer
 * or a series of such buffers.  An encoder should always be used by making
 * the following sequence of method invocations, hereinafter referred to as an
 * <i>encoding operation</i>:
 *
 * <ol>
 *
 *   <li><p> Reset the encoder via the {@link #reset reset} method, unless it
 *   has not been used before; </p></li>
 *
 *   <li><p> Invoke the {@link #encode encode} 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 #encode encode} 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 encoder can
 *   flush any internal state to the output buffer. </p></li>
 *
 * </ol>
 *
 * Each invocation of the {@link #encode encode} method will encode as many
 * characters as possible from the input buffer, writing the resulting bytes
 * to the output buffer.  The {@link #encode encode} method returns when more
 * input is required, when there is not enough room in the output buffer, or
 * when an encoding 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 an encoding error, as appropriate, and try again.
 *
 * <a name="ce">
 *
 * <p> There are two general types of encoding errors.  If the input character
 * sequence is not a legal sixteen-bit Unicode sequence then the input is considered <i>malformed</i>.  If
 * the input character sequence is legal but cannot be mapped to a valid
 * byte sequence in the given charset then an <i>unmappable character</i> has been encountered.
 *
 * <a name="cae">
 *
 * <p> How an encoding 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 byte array.  The replacement
 *

 * is initially set to the encoder's default replacement, which often
 * (but not always) has the initial value&nbsp;<tt>{</tt>&nbsp;<tt>(byte)'?'</tt>&nbsp;<tt>}</tt>;




 *
 * its value may be changed via the {@link #replaceWith(byte[])
 * 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 encoding
 * process, including the implementation of error actions.  An encoder for a
 * specific charset, which is a concrete subclass of this class, need only
 * implement the abstract {@link #encodeLoop encodeLoop} method, which
 * encapsulates the basic encoding 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 CharsetDecoder
 */

public abstract class CharsetEncoder {

    private final Charset charset;
    private final float averageBytesPerChar;
    private final float maxBytesPerChar;

    private byte[] 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 encoder.  The new encoder will have the given
     * bytes-per-char and replacement values. </p>
     *
     * @param  averageBytesPerChar
     *         A positive float value indicating the expected number of
     *         bytes that will be produced for each input character
     *
     * @param  maxBytesPerChar
     *         A positive float value indicating the maximum number of
     *         bytes that will be produced for each input character
     *
     * @param  replacement
     *         The initial replacement; must not be <tt>null</tt>, must have
     *         non-zero length, must not be longer than maxBytesPerChar,
     *         and must be {@link #isLegalReplacement </code>legal<code>}
     *
     * @throws  IllegalArgumentException
     *          If the preconditions on the parameters do not hold
     */
    protected
    CharsetEncoder(Charset cs,
		   float averageBytesPerChar,
		   float maxBytesPerChar,
		   byte[] replacement)
    {
	this.charset = cs;
	if (averageBytesPerChar <= 0.0f)
	    throw new IllegalArgumentException("Non-positive "
					       + "averageBytesPerChar");
	if (maxBytesPerChar <= 0.0f)
	    throw new IllegalArgumentException("Non-positive "
					       + "maxBytesPerChar");
	this.replacement = replacement;
	this.averageBytesPerChar = averageBytesPerChar;
	this.maxBytesPerChar = maxBytesPerChar;
	replaceWith(replacement);
    }

    /**
     * Initializes a new encoder.  The new encoder will have the given
     * bytes-per-char values and its replacement will be the
     * byte array <tt>{</tt>&nbsp;<tt>(byte)'?'</tt>&nbsp;<tt>}</tt>. </p>
     *
     * @param  averageBytesPerChar
     *         A positive float value indicating the expected number of
     *         bytes that will be produced for each input character
     *
     * @param  maxBytesPerChar
     *         A positive float value indicating the maximum number of
     *         bytes that will be produced for each input character
     *
     * @throws  IllegalArgumentException
     *          If the preconditions on the parameters do not hold
     */
    protected CharsetEncoder(Charset cs,
			     float averageBytesPerChar,
			     float maxBytesPerChar)
    {
	this(cs,
	     averageBytesPerChar, maxBytesPerChar,
	     new byte[] { (byte)'?' });
    }

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

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

    /**
     * Changes this encoder'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>, must have
     *         non-zero length, must not be longer than the value returned by
     *         the {@link #maxBytesPerChar maxBytesPerChar} method, and
     *         must be {@link #isLegalReplacement </code>legal<code>}

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

	if (!isLegalReplacement(newReplacement))
	    throw new IllegalArgumentException("Illegal replacement");

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

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



    private WeakReference cachedDecoder = null;

    /**
     * Tells whether or not the given byte array is a legal replacement value
     * for this encoder.
     *
     * <p> A replacement is legal if, and only if, it is a legal sequence of
     * bytes in this encoder's charset; that is, it must be possible to decode
     * the replacement into one or more sixteen-bit Unicode characters.
     *
     * <p> The default implementation of this method is not very efficient; it
     * should generally be overridden to improve performance.  </p>
     *
     * @param  repl  The byte array to be tested
     *
     * @return  <tt>true</tt> if, and only if, the given byte array
     *          is a legal replacement value for this encoder
     */
    public boolean isLegalReplacement(byte[] repl) {
	WeakReference wr = cachedDecoder;
	CharsetDecoder dec = null;
	if ((wr == null) || ((dec = (CharsetDecoder)wr.get()) == null)) {
	    dec = charset().newDecoder();
	    dec.onMalformedInput(CodingErrorAction.REPORT);
	    dec.onUnmappableCharacter(CodingErrorAction.REPORT);
	    cachedDecoder = new WeakReference(dec);
	} else {
	    dec.reset();
	}
	ByteBuffer bb = ByteBuffer.wrap(repl);
	CharBuffer cb = CharBuffer.allocate((int)(bb.remaining()