src/share/classes/sun/io/ByteToCharConverter.java - toolchain/jdk/jdk9_jdk - Git at Google

 /*
  * Copyright (c) 1996, 2004, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */

 package sun.io;

 import java.io.*;


 /**
  * An abstract base class for subclasses which convert character data
  * in an external encoding into Unicode characters.
  *
  * @author Asmus Freytag
  * @author Lloyd Honomichl
  *
  * @deprecated Replaced by {@link java.nio.charset}.  THIS API WILL BE
  * REMOVED IN J2SE 1.6.
  */
 @Deprecated
 public abstract class ByteToCharConverter {

     /*
      * Substitution mode flag.
      */
     protected boolean subMode = true;

     /*
      * Characters to use for automatic substitution.
      */
     protected char[] subChars = { '\uFFFD' };

     /*
      * Offset of next character to be output
      */
     protected int charOff;

     /*
      * Offset of next byte to be converted
      */
     protected int byteOff;

     /*
      * Length of bad input that caused a MalformedInputException.
      */
     protected int badInputLength;

     /**
      * Create an instance of the default ByteToCharConverter subclass.
      */
     public static ByteToCharConverter getDefault() {
         Object cvt;
         cvt = Converters.newDefaultConverter(Converters.BYTE_TO_CHAR);
         return (ByteToCharConverter)cvt;
     }

     /**
      * Returns appropriate ByteToCharConverter subclass instance.
      * @param string represents encoding
      */
     public static ByteToCharConverter getConverter(String encoding)
         throws UnsupportedEncodingException
     {
         Object cvt;
         cvt = Converters.newConverter(Converters.BYTE_TO_CHAR, encoding);
         return (ByteToCharConverter)cvt;
     }

     /**
      * Returns the character set id for the conversion
      */
     public abstract String getCharacterEncoding();

     /**
      * Converts an array of bytes containing characters in an external
      * encoding into an array of Unicode characters.  This  method allows
      * a buffer by buffer conversion of a data stream.  The state of the
      * conversion is saved between calls to convert.  Among other things,
      * this means multibyte input sequences can be split between calls.
      * If a call to convert results in an exception, the conversion may be
      * continued by calling convert again with suitably modified parameters.
      * All conversions should be finished with a call to the flush method.
      *
      * @return the number of bytes written to output.
      * @param input byte array containing text to be converted.
      * @param inStart begin conversion at this offset in input array.
      * @param inEnd stop conversion at this offset in input array (exclusive).
      * @param output character array to receive conversion result.
      * @param outStart start writing to output array at this offset.
      * @param outEnd stop writing to output array at this offset (exclusive).
      * @exception MalformedInputException if the input buffer contains any
      * sequence of bytes that is illegal for the input character set.
      * @exception UnknownCharacterException for any character that
      * that cannot be converted to Unicode. Thrown only when converter
      * is not in substitution mode.
      * @exception ConversionBufferFullException if output array is filled prior
      * to converting all the input.
      */
     public abstract int convert(byte[] input, int inStart, int inEnd,
                                 char[] output, int outStart, int outEnd)
             throws MalformedInputException,
                    UnknownCharacterException,
                    ConversionBufferFullException;

     /**
      * Converts an array of bytes containing characters in an external
      * encoding into an array of Unicode characters.  Unlike convert,
      * this method does not do incremental conversion.  It assumes that
      * the given input array contains all the characters to be
      * converted. The state of the converter is reset at the beginning
      * of this method and is left in the reset state on successful
      * termination.  The converter is not reset if an exception is
      * thrown.  This allows the caller to determine where the bad input
      * was encountered by calling nextByteIndex.
      * <p>
      * This method uses substitution mode when performing the
      * conversion.  The method setSubstitutionChars may be used to
      * determine what characters are substituted.  Even though substitution
      * mode is used, the state of the converter's substitution mode is
      * not changed at the end of this method.
      *
      * @return an array of chars containing the converted characters.
      * @param input array containing Unicode characters to be converted.
      * @exception MalformedInputException if the input buffer contains any
      * sequence of chars that is illegal in the input character encoding.
      * After this exception is thrown,
      * the method nextByteIndex can be called to obtain the index of the
      * first invalid input byte and getBadInputLength can be called
      * to determine the length of the invalid input.
      *
      * @see   #nextByteIndex
      * @see   #setSubstitutionMode
      * @see   sun.io.CharToByteConverter#setSubstitutionBytes(byte[])
      * @see   #getBadInputLength
      */
     public char[] convertAll( byte input[] ) throws MalformedInputException {
         reset();
         boolean savedSubMode = subMode;
         subMode = true;

         char[] output = new char[ getMaxCharsPerByte() * input.length ];

         try {
             int outputLength = convert( input, 0, input.length,
                                         output, 0, output.length );
             outputLength += flush( output, outputLength, output.length );

             char [] returnedOutput = new char[ outputLength ];
             System.arraycopy( output, 0, returnedOutput, 0, outputLength );
             return returnedOutput;
         }
         catch( ConversionBufferFullException e ) {
             //Not supposed to happen.  If it does, getMaxCharsPerByte() lied.
             throw new
                 InternalError("this.getMaxCharsBerByte returned bad value");
         }
         catch( UnknownCharacterException e ) {
             // Not supposed to happen since we're in substitution mode.
             throw new InternalError();
         }
         finally {
             subMode = savedSubMode;
         }
     }

     /**
      * Writes any remaining output to the output buffer and resets the
      * converter to its initial state.
      *
      * @param output char array to receive flushed output.
      * @param outStart start writing to output array at this offset.
      * @param outEnd stop writing to output array at this offset (exclusive).
      * @exception MalformedInputException if the output to be flushed contained
      * a partial or invalid multibyte character sequence.  flush will
      * write what it can to the output buffer and reset the converter before
      * throwing this exception.  An additional call to flush is not required.
      * @exception ConversionBufferFullException if output array is filled
      * before all the output can be flushed. flush will write what it can
      * to the output buffer and remember its state.  An additional call to
      * flush with a new output buffer will conclude the operation.
      */
     public abstract int flush( char[] output, int outStart, int outEnd )
         throws MalformedInputException, ConversionBufferFullException;

     /**
      * Resets converter to its initial state.
      */
     public abstract void reset();

     /**
      * Returns the maximum number of characters needed to convert a byte. Useful
      * for calculating the maximum output buffer size needed for a particular
      * input buffer.
      */
     public int getMaxCharsPerByte() {
         // Until UTF-16, this will do for every encoding
         return 1;
     }

     /**
      * Returns the length, in bytes, of the input which caused a
      * MalformedInputException.  Always refers to the last
      * MalformedInputException thrown by the converter.  If none have
      * ever been thrown, returns 0.
      */
     public int getBadInputLength() {
         return badInputLength;
     }

     /**
      * Returns the index of the  character just past the last character
      * written by the previous call to convert.
      */
     public int nextCharIndex() {
         return charOff;
     }

     /**
      * Returns the index of the byte just past the last byte successfully
      * converted by the previous call to convert.
      */
     public int nextByteIndex() {
         return byteOff;
     }

     /**
      * Sets converter into substitution mode.  In substitution mode,
      * the converter will replace untranslatable characters in the source
      * encoding with the substitution character set by setSubstitionChars.
      * When not in substitution mode, the converter will throw an
      * UnknownCharacterException when it encounters untranslatable input.
      *
      * @param doSub if true, enable substitution mode.
      * @see #setSubstitutionChars
      */
     public void setSubstitutionMode(boolean doSub) {
         subMode = doSub;
     }

     /**
      * Sets the substitution characters to use when the converter is in
      * substitution mode.  The given chars must not be
      * longer than the value returned by getMaxCharsPerByte for this
      * converter.
      *
      * @param newSubBytes the substitution bytes
      * @exception IllegalArgumentException if given byte array is longer than
      *    the value returned by the method getMaxBytesPerChar.
      * @see #setSubstitutionMode
      * @see #getMaxBytesPerChar
      */
     /**
      * sets the substitution character to use
      * @param c the substitution character
      */
     public void setSubstitutionChars(char[] c)
         throws IllegalArgumentException
     {
         if( c.length > getMaxCharsPerByte() ) {
             throw new IllegalArgumentException();
         }

         subChars = new char[ c.length ];
         System.arraycopy( c, 0, subChars, 0, c.length );
     }

     /**
      * returns a string representation of the character conversion
      */
     public String toString() {
         return "ByteToCharConverter: " + getCharacterEncoding();
     }
 }
	/*
	* Copyright (c) 1996, 2004, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package sun.io;

	import java.io.*;


	/**
	* An abstract base class for subclasses which convert character data
	* in an external encoding into Unicode characters.
	*
	* @author Asmus Freytag
	* @author Lloyd Honomichl
	*
	* @deprecated Replaced by {@link java.nio.charset}. THIS API WILL BE
	* REMOVED IN J2SE 1.6.
	*/
	@Deprecated
	public abstract class ByteToCharConverter {

	/*
	* Substitution mode flag.
	*/
	protected boolean subMode = true;

	/*
	* Characters to use for automatic substitution.
	*/
	protected char[] subChars = { '\uFFFD' };

	/*
	* Offset of next character to be output
	*/
	protected int charOff;

	/*
	* Offset of next byte to be converted
	*/
	protected int byteOff;

	/*
	* Length of bad input that caused a MalformedInputException.
	*/
	protected int badInputLength;

	/**
	* Create an instance of the default ByteToCharConverter subclass.
	*/
	public static ByteToCharConverter getDefault() {
	Object cvt;
	cvt = Converters.newDefaultConverter(Converters.BYTE_TO_CHAR);
	return (ByteToCharConverter)cvt;
	}

	/**
	* Returns appropriate ByteToCharConverter subclass instance.
	* @param string represents encoding
	*/
	public static ByteToCharConverter getConverter(String encoding)
	throws UnsupportedEncodingException
	{
	Object cvt;
	cvt = Converters.newConverter(Converters.BYTE_TO_CHAR, encoding);
	return (ByteToCharConverter)cvt;
	}

	/**
	* Returns the character set id for the conversion
	*/
	public abstract String getCharacterEncoding();

	/**
	* Converts an array of bytes containing characters in an external
	* encoding into an array of Unicode characters. This method allows
	* a buffer by buffer conversion of a data stream. The state of the
	* conversion is saved between calls to convert. Among other things,
	* this means multibyte input sequences can be split between calls.
	* If a call to convert results in an exception, the conversion may be
	* continued by calling convert again with suitably modified parameters.
	* All conversions should be finished with a call to the flush method.
	*
	* @return the number of bytes written to output.
	* @param input byte array containing text to be converted.
	* @param inStart begin conversion at this offset in input array.
	* @param inEnd stop conversion at this offset in input array (exclusive).
	* @param output character array to receive conversion result.
	* @param outStart start writing to output array at this offset.
	* @param outEnd stop writing to output array at this offset (exclusive).
	* @exception MalformedInputException if the input buffer contains any
	* sequence of bytes that is illegal for the input character set.
	* @exception UnknownCharacterException for any character that
	* that cannot be converted to Unicode. Thrown only when converter
	* is not in substitution mode.
	* @exception ConversionBufferFullException if output array is filled prior
	* to converting all the input.
	*/
	public abstract int convert(byte[] input, int inStart, int inEnd,
	char[] output, int outStart, int outEnd)
	throws MalformedInputException,
	UnknownCharacterException,
	ConversionBufferFullException;

	/**
	* Converts an array of bytes containing characters in an external
	* encoding into an array of Unicode characters. Unlike convert,
	* this method does not do incremental conversion. It assumes that
	* the given input array contains all the characters to be
	* converted. The state of the converter is reset at the beginning
	* of this method and is left in the reset state on successful
	* termination. The converter is not reset if an exception is
	* thrown. This allows the caller to determine where the bad input
	* was encountered by calling nextByteIndex.
	* <p>
	* This method uses substitution mode when performing the
	* conversion. The method setSubstitutionChars may be used to
	* determine what characters are substituted. Even though substitution
	* mode is used, the state of the converter's substitution mode is
	* not changed at the end of this method.
	*
	* @return an array of chars containing the converted characters.
	* @param input array containing Unicode characters to be converted.
	* @exception MalformedInputException if the input buffer contains any
	* sequence of chars that is illegal in the input character encoding.
	* After this exception is thrown,
	* the method nextByteIndex can be called to obtain the index of the
	* first invalid input byte and getBadInputLength can be called
	* to determine the length of the invalid input.
	*
	* @see #nextByteIndex
	* @see #setSubstitutionMode
	* @see sun.io.CharToByteConverter#setSubstitutionBytes(byte[])
	* @see #getBadInputLength
	*/
	public char[] convertAll( byte input[] ) throws MalformedInputException {
	reset();
	boolean savedSubMode = subMode;
	subMode = true;

	char[] output = new char[ getMaxCharsPerByte() * input.length ];

	try {
	int outputLength = convert( input, 0, input.length,
	output, 0, output.length );
	outputLength += flush( output, outputLength, output.length );

	char [] returnedOutput = new char[ outputLength ];
	System.arraycopy( output, 0, returnedOutput, 0, outputLength );
	return returnedOutput;
	}
	catch( ConversionBufferFullException e ) {
	//Not supposed to happen. If it does, getMaxCharsPerByte() lied.
	throw new
	InternalError("this.getMaxCharsBerByte returned bad value");
	}
	catch( UnknownCharacterException e ) {
	// Not supposed to happen since we're in substitution mode.
	throw new InternalError();
	}
	finally {
	subMode = savedSubMode;
	}
	}

	/**
	* Writes any remaining output to the output buffer and resets the
	* converter to its initial state.
	*
	* @param output char array to receive flushed output.
	* @param outStart start writing to output array at this offset.
	* @param outEnd stop writing to output array at this offset (exclusive).
	* @exception MalformedInputException if the output to be flushed contained
	* a partial or invalid multibyte character sequence. flush will
	* write what it can to the output buffer and reset the converter before
	* throwing this exception. An additional call to flush is not required.
	* @exception ConversionBufferFullException if output array is filled
	* before all the output can be flushed. flush will write what it can
	* to the output buffer and remember its state. An additional call to
	* flush with a new output buffer will conclude the operation.
	*/
	public abstract int flush( char[] output, int outStart, int outEnd )
	throws MalformedInputException, ConversionBufferFullException;

	/**
	* Resets converter to its initial state.
	*/
	public abstract void reset();

	/**
	* Returns the maximum number of characters needed to convert a byte. Useful
	* for calculating the maximum output buffer size needed for a particular
	* input buffer.
	*/
	public int getMaxCharsPerByte() {
	// Until UTF-16, this will do for every encoding
	return 1;
	}

	/**
	* Returns the length, in bytes, of the input which caused a
	* MalformedInputException. Always refers to the last
	* MalformedInputException thrown by the converter. If none have
	* ever been thrown, returns 0.
	*/
	public int getBadInputLength() {
	return badInputLength;
	}

	/**
	* Returns the index of the character just past the last character
	* written by the previous call to convert.
	*/
	public int nextCharIndex() {
	return charOff;
	}

	/**
	* Returns the index of the byte just past the last byte successfully
	* converted by the previous call to convert.
	*/
	public int nextByteIndex() {
	return byteOff;
	}

	/**
	* Sets converter into substitution mode. In substitution mode,
	* the converter will replace untranslatable characters in the source
	* encoding with the substitution character set by setSubstitionChars.
	* When not in substitution mode, the converter will throw an
	* UnknownCharacterException when it encounters untranslatable input.
	*
	* @param doSub if true, enable substitution mode.
	* @see #setSubstitutionChars
	*/
	public void setSubstitutionMode(boolean doSub) {
	subMode = doSub;
	}

	/**
	* Sets the substitution characters to use when the converter is in
	* substitution mode. The given chars must not be
	* longer than the value returned by getMaxCharsPerByte for this
	* converter.
	*
	* @param newSubBytes the substitution bytes
	* @exception IllegalArgumentException if given byte array is longer than
	* the value returned by the method getMaxBytesPerChar.
	* @see #setSubstitutionMode
	* @see #getMaxBytesPerChar
	*/
	/**
	* sets the substitution character to use
	* @param c the substitution character
	*/
	public void setSubstitutionChars(char[] c)
	throws IllegalArgumentException
	{
	if( c.length > getMaxCharsPerByte() ) {
	throw new IllegalArgumentException();
	}

	subChars = new char[ c.length ];
	System.arraycopy( c, 0, subChars, 0, c.length );
	}

	/**
	* returns a string representation of the character conversion
	*/
	public String toString() {
	return "ByteToCharConverter: " + getCharacterEncoding();
	}
	}