diff -r 64f7ee2f31dd -r 2f6d68f22eae jdk/src/share/classes/sun/io/ByteToCharConverter.java --- a/jdk/src/share/classes/sun/io/ByteToCharConverter.java Mon Aug 29 14:27:21 2011 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,294 +0,0 @@ -/* - * 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. - *

- * 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(); - } -}