Hi,
Please find attached a patch which is the result of diff -u <original
CharsetDecoder.java> <my CharsetDecoder.java>.
Also please find attached a similar patch for Changelog.
Feedback on this would be welcome, and would mean less time would be
wasted when I get around to CharsetEncoder and others.
Regards,
Ricky.
--- classpath-backup/java/nio/charset/CharsetDecoder.java 2003-09-20
11:40:54.000000000 +0100
+++ classpath/java/nio/charset/CharsetDecoder.java 2003-09-21 23:24:47.000000000
+0100
@@ -41,30 +41,198 @@
import java.nio.CharBuffer;
/**
+ * <code>CharsetDecoder</code> provides facilities to decode a sequence of
+ * bytes (one or more [EMAIL PROTECTED] ByteBuffer}s) that are in a particular
+ * charset into a sequence of standard Java 16-bit Unicode characters (one or
+ * more [EMAIL PROTECTED] CharBuffer}s).
+ *
+ * <p>The input data are provided in a [EMAIL PROTECTED] ByteBuffer} or, by invoking
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}
+ * repeatedly and passing a different [EMAIL PROTECTED] ByteBuffer} as a parameter
each
+ * time, the data can be provided in a sequence of [EMAIL PROTECTED] ByteBuffer}s.
+ *
+ * <p>The output data are written to a [EMAIL PROTECTED] CharBuffer} or, by invoking
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}
+ * repeatedly and altering the [EMAIL PROTECTED] CharBuffer} passed as a parameter
each
+ * time, the data can be written to a sequence of [EMAIL PROTECTED] CharBuffer}s.
+ *
+ * <p>Methods are normally invoked on a <code>CharsetDecoder</code> in a certain
order:
+ *
+ * <p>1. [EMAIL PROTECTED] #reset()} - invoke if the <code>CharsetDecoder</code> has
+ * been used before.
+ *
+ * <p>2. [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean
endOfInput)}
+ * - invoke repeatedly as long as there are [EMAIL PROTECTED] ByteBuffer}s to be
decoded.
+ *
+ * <p><code>endOfInput</code> should be <code>false</code> until the
+ * current invocation of
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)} is
the
+ * last, i.e., pass <code>true</code> <em>only</em> when there are no more
+ * data to decode after the current invocation.
+ *
+ * <p>Each invocation of
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}
decodes
+ * as many bytes as possible, and returns a [EMAIL PROTECTED] CoderResult} object to
+ * describe the reason for returning. The invoker can examine this object to
+ * determine the reason and act accordingly, e.g., by filling the input
+ * [EMAIL PROTECTED] ByteBuffer}.
+ *
+ * <p>3. [EMAIL PROTECTED] #flush(CharBuffer out)} to ensure that the
+ * <code>CharsetDecoder</code> writes all data to the output
+ * [EMAIL PROTECTED] CharBuffer}.
+ *
+ * <p>If the input [EMAIL PROTECTED] ByteBuffer} does not contain a valid sequence of
+ * bytes for the specified [EMAIL PROTECTED] Charset} the input is malformed
+ * ([EMAIL PROTECTED] CoderResult#isMalformed()}).
+ *
+ * <p>If the input [EMAIL PROTECTED] ByteBuffer} is valid, but there is no equivalent
+ * Unicode character to map part of it to, the input has an unmappable
+ * character ([EMAIL PROTECTED] CoderResult#isUnmappable()}).
+ *
+ * <p>The methods [EMAIL PROTECTED] #onMalformedInput(CodingErrorAction newAction)}
and
+ * [EMAIL PROTECTED] #onUnmappableCharacter(CodingErrorAction newAction)} allow an
+ * action ([EMAIL PROTECTED] CodingErrorAction}) to be specified for the respective
+ * decoding errors.
+ *
+ * <p>The actions can be one of:
+ * <ul>
+ * <li>[EMAIL PROTECTED] CodingErrorAction#IGNORE} - specifies that the invalid input
+ * is to be ignored and that decoding should continue.</li>
+ *
+ * <li>[EMAIL PROTECTED] CodingErrorAction#REPLACE} - specifies that the invalid
+ * input is to be ignored and that the decoder's replacement value is to be
+ * inserted (This is "\<!-- comment to stop Unicode interpolation -->uFFFD"
+ * unless [EMAIL PROTECTED] #replaceWith(String newReplacement)} has been invoked) and
+ * that decoding should continue.</li>
+ *
+ * <li>[EMAIL PROTECTED] CodingErrorAction#REPORT} - specifies that the error should
+ * be reported to the invoker of
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)} via a
+ * [EMAIL PROTECTED] CoderResult} object, or by throwing a
+ * [EMAIL PROTECTED] CharacterCodingException}</li>
+ * </ul>
+ *
+ * <p>To implement a decoder for a specific charset, create a subclass of
+ * this class and implement the protected abstract method
+ * [EMAIL PROTECTED] #decodeLoop(ByteBuffer in, CharBuffer out)}.
+ *
+ * <p>To ensure that any internal state in a subclass is cleared correctly,
+ * also override [EMAIL PROTECTED] #flush(CharBuffer out)} and [EMAIL PROTECTED]
#reset()}, but make
+ * sure that you invoke <code>super.flush(out)</code> and
+ * <code>super.reset()</code> in their respective methods.
+ *
+ * Instances of this class are NOT threadsafe.
+ *
* @author Jesse Rosenstock
+ * @author Ricky Clarkson <[EMAIL PROTECTED]>
* @since 1.4
*/
public abstract class CharsetDecoder
{
+ /**
+ * Flag meaning that the <code>CharsetDecoder</code> has been reset.
+ *
+ * <p>See [EMAIL PROTECTED] #state}.
+ */
private static final int STATE_RESET = 0;
+
+ /**
+ * Flag meaning that the <code>CharsetDecoder</code> is currently decoding
+ * data.
+ *
+ * <p>See [EMAIL PROTECTED] #state}.
+ */
private static final int STATE_CODING = 1;
+
+ /**
+ * Flag meaning that the <code>CharsetDecoder</code> has finished decoding
+ * data.
+ *
+ * <p>See [EMAIL PROTECTED] #state}.
+ */
private static final int STATE_END = 2;
+
+ /**
+ * Flag meaning that the <code>CharsetDecoder</code> has been flushed.
+ *
+ * <p>See [EMAIL PROTECTED] #state}.
+ */
private static final int STATE_FLUSHED = 3;
+ /**
+ * The default value for [EMAIL PROTECTED] #replacement} before {link #replaceWith}
+ * is invoked.
+ */
private static final String DEFAULT_REPLACEMENT = "\uFFFD";
+ /**
+ * The [EMAIL PROTECTED] Charset} that instantiated this
<code>CharsetDecoder</code>.
+ */
private final Charset charset;
+
+ /**
+ * The expected average number of characters output per byte input.
+ *
+ * <p>For example, if 3 bytes correspond to 1 character, this value will be
+ * equal to 1.0f/3.
+ */
private final float averageCharsPerByte;
+
+ /**
+ * The maximum number of characters output per byte.
+ *
+ * <p>For example, if between 2 and 5 bytes correspond to 1 character, this
+ * value will be 0.5f
+ */
private final float maxCharsPerByte;
+
+ /**
+ * The [EMAIL PROTECTED] String} that will be inserted if a sequence of bytes is
+ * <em>unmappable</em> (see [EMAIL PROTECTED] CoderResult#isUnmappable()}).
+ * Set during construction and also by [EMAIL PROTECTED] #replaceWith()}.
+ */
+ //Is there any reason that this cannot be set to DEFAULT_REPLACEMENT
+ //here, and maybe DEFAULT_REPLACEMENT removed?
+ //Maybe removing DEFAULT_REPLACEMENT would cause Serialization problems.
private String replacement;
+ /**
+ * The current state of the decoder. One of:
+ * <ul>
+ * <li>[EMAIL PROTECTED] #STATE_RESET}</li>
+ * <li>[EMAIL PROTECTED] #STATE_CODING}</li>
+ * <li>[EMAIL PROTECTED] #STATE_END}</li>
+ * <li>[EMAIL PROTECTED] #STATE_FLUSHED}</li>
+ * </ul>
+ * At initialization time it is set to [EMAIL PROTECTED] #STATE_RESET}.
+ */
private int state = STATE_RESET;
+ /**
+ * The action to be taken when malformed input is received.
+ * At initialization time it is set to
+ * [EMAIL PROTECTED] CodingErrorAction#REPORT}, i.e., so that the user of the class
is
+ * informed about any malformed input.
+ */
private CodingErrorAction malformedInputAction
= CodingErrorAction.REPORT;
+
+ /**
+ * The action to be taken when a character that cannot be mapped to Unicode.
+ * At initialization time it is set to
+ * [EMAIL PROTECTED] CodingErrorAction#REPORT}, i.e., so that the user of the class
is
+ * informed about any unmapped characaters.
+ */
private CodingErrorAction unmappableCharacterAction
= CodingErrorAction.REPORT;
+ /**
+ * Real implementation of constructor (the other constructor just invokes
+ * this one).
+ *
+ * The main docs are in the other constructor though, because it will appear
+ * in most Javadocs.
+ */
private CharsetDecoder (Charset cs, float averageCharsPerByte,
float maxCharsPerByte, String replacement)
{
@@ -82,22 +250,108 @@
implReplaceWith (replacement);
}
+ /**
+ * Constructs a <code>CharsetDecoder</code> for the specified
+ * [EMAIL PROTECTED] Charset}.
+ *
+ * <p>This is normally only invoked via [EMAIL PROTECTED] Charset#newDecoder()}.
+ *
+ * <p>The method [EMAIL PROTECTED] #averageCharsPerByte()} will return the value
+ * passed as the parameter <code>averageCharsPerByte</code>.
+ *
+ * <p>The method [EMAIL PROTECTED] #maxCharsPerByte()} will return the value
+ * passed as the parameter <code>maxCharsPerByte</code>.
+ *
+ * <p>The replacement [EMAIL PROTECTED] String} will be set to
+ * "\<!-- comment just to prevent conversion to Unicode -->uFFFD".
+ * See [EMAIL PROTECTED] #replacement()}.
+ *
+ * @param cs the [EMAIL PROTECTED] Charset} that instantiated this
+ * <code>CharsetDecoder</code>.
+ *
+ * @param averageCharsPerByte a positive value describing the expected
+ * average number of characters of output per byte of input.
+ *
+ * @param maxCharsPerByte a positive value describing the maximum
+ * number of characters of output per byte of input.
+ *
+ * @throws IllegalArgumentException if <code>averageCharsPerByte</code>
+ * or <code>maxCharsPerByte</code> are less than or equal to 0.
+ */
protected CharsetDecoder (Charset cs, float averageCharsPerByte,
float maxCharsPerByte)
{
this (cs, averageCharsPerByte, maxCharsPerByte, DEFAULT_REPLACEMENT);
}
+ /**
+ * Returns the average number of characters output per byte of input.
+ *
+ * <p>For example, if 3 bytes correspond to 1 character, this value will be
+ * equal to 1.0f/3.
+ *
+ * @return the average number of characters output per byte of input.
+ */
public final float averageCharsPerByte ()
{
return averageCharsPerByte;
}
+ /**
+ * Returns the [EMAIL PROTECTED] Charset} that instantiated this
+ * <code>CharsetDecoder</code>.
+ *
+ * @return the [EMAIL PROTECTED] Charset} that instantiated this
+ * <code>CharsetDecoder</code>.
+ */
public final Charset charset ()
{
return charset;
}
+ /**
+ * Decodes the input [EMAIL PROTECTED] ByteBuffer}, allocates a [EMAIL PROTECTED]
CharBuffer}
+ * for output and places the decoded characters in the output
+ * [EMAIL PROTECTED] CharBuffer}.
+ *
+ * <p>This method probably should reset the <code>CharsetDecoder</code>, but
+ * instead throws an [EMAIL PROTECTED] IllegalStateException} if the
+ * <code>CharsetDecoder</code> has not already been reset. Sun's
+ * documentation conflicts with itself here, so it would be useful to run
+ * a test to find out what Sun's actual behavior is.
+ *
+ * <p>It then allocates a [EMAIL PROTECTED] CharBuffer} and populates it with
decoded
+ * data, and invokes [EMAIL PROTECTED] #flush(CharBuffer out)}.
+ *
+ * <p>This method should not be invoked between any invocations of
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)} and
+ * [EMAIL PROTECTED] #reset()}, and after use [EMAIL PROTECTED] #reset()} should be
invoked on it
+ * before invoking
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}.
+ *
+ * <p>The current algorithm for this uses the value that
+ * [EMAIL PROTECTED] #maxCharsPerByte()} returns to allocate storage, so it is not
+ * optimal in memory usage.
+ *
+ * @param in the input [EMAIL PROTECTED] ByteBuffer}.
+ * @return the new and populated [EMAIL PROTECTED] CharBuffer}, which is at
position 0
+ * and is limited to the size of the data.
+ *
+ * @throws IllegalStateException if the <code>CharsetDecoder</code> has not
+ * been [EMAIL PROTECTED] #reset()}.
+ *
+ * @throws MalformedInputException if the input is not valid for the
+ * [EMAIL PROTECTED] Charset} and the malformed input action is
+ * [EMAIL PROTECTED] CodingErrorAction#REPORT}.
+ *
+ * @throws UnmappableCharacterException if the input contains a character
+ * for which there is no known mapping to Unicode and the unmappable
+ * character action is set to [EMAIL PROTECTED] CodingErrorAction#REPORT}.
+ *
+ * @throws CharacterCodingException because
+ * [EMAIL PROTECTED] CoderResult#throwException()} is declared to throw this kind of
+ * exception.
+ */
public final CharBuffer decode (ByteBuffer in)
throws CharacterCodingException
{
@@ -133,6 +387,52 @@
return out;
}
+ /**
+ * Decodes the data passed in the input [EMAIL PROTECTED] ByteBuffer}
+ * and places the decoded characters in the output [EMAIL PROTECTED] CharBuffer}.
+ *
+ * <p>Make sure that <code>endOfInput</code> is true if and only if this
+ * invocation is the last invocation in this sequence of calls to
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}.
+ *
+ * <p>Both buffers are used starting at their current positions, i.e.,
+ * <code>rewind()</code> is NOT invoked on either.
+ *
+ * <p>This method will modify the current position, but will not affect the
+ * marks and limits.
+ *
+ * <p>Returns one of the following:
+ * <ul>
+ * <li>
+ * [EMAIL PROTECTED] CoderResult#UNDERFLOW} - this means that the input buffer
is
+ * exhausted, which indicates either that the <code>CharsetDecoder</code>
+ * is ready for more input, or that the decoding has finished, depending
+ * on whether the invoker has more data.
+ * </li>
+ * <li>
+ * [EMAIL PROTECTED] CoderResult#OVERFLOW} - this means that the output
+ * [EMAIL PROTECTED] CharBuffer} is exhausted and that the method should be
invoked
+ * again, but with a [EMAIL PROTECTED] CharBuffer} that is not full.
+ * </li>
+ * </ul>
+ *
+ * @param in a buffer holding the sequence of bytes to decode.
+ * @param out a buffer to hold the sequence of decoded characters.
+ *
+ * @param endOfInput a flag to describe whether the contents of
+ * <code>in</code> are the last data to be passed to this method.
+ *
+ * @return a [EMAIL PROTECTED] CoderResult} describing why the method returns.
+ *
+ * @throws IllegalStateException if the most recent method invocation
+ * (other than accessors and mutators) was not one of
+ * [EMAIL PROTECTED] #reset()} or
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}
where
+ * <code>endOfInput</code> is <code>true</code>.
+ *
+ * @throws CoderMalfunctionError if [EMAIL PROTECTED] #decodeLoop} throws a
non-checked
+ * exception.
+ */
public final CoderResult decode (ByteBuffer in, CharBuffer out,
boolean endOfInput)
{
@@ -188,13 +488,72 @@
}
}
+ /**
+ * Decodes the bytes in the input [EMAIL PROTECTED] ByteBuffer} and puts the
+ * resulting characters in the output [EMAIL PROTECTED] CharBuffer}.
+ *
+ * <p>The buffers are not rewound (<code>rewind()</code> is not invoked on
+ * either), and the marks and limits are not set. The positions will be
+ * modified.
+ *
+ * <p>Returns the same values as
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}.
+ *
+ * @param in a buffer holding the data to be decoded.
+ * @param out a buffer to hold the decoded data (characters).
+ * @return a [EMAIL PROTECTED] CoderResult} instance describing the reason for
+ * returning.
+ */
protected abstract CoderResult decodeLoop (ByteBuffer in, CharBuffer out);
+ /**
+ * If a subclass is capable of detecting the [EMAIL PROTECTED] Charset} based on
input
+ * data, it should override this.
+ *
+ * @return the detected [EMAIL PROTECTED] Charset}.
+ *
+ * @throws UnsupportedOperationException if detecting the [EMAIL PROTECTED] Charset}
+ * based on input data is not supported (this is the default).
+ *
+ * @throws IllegalStateException if not enough data have been processed yet
+ * to detect the [EMAIL PROTECTED] Charset}.
+ */
public Charset detectedCharset ()
{
throw new UnsupportedOperationException ();
}
-
+
+ /**
+ * Empties all buffers.
+ *
+ * <p>Some subclasses may need to be notified when decoding has finished,
+ * so that they can do some cleanup, such as releasing resources, or
+ * appending some characters to the end of the output. This method does
+ * some housekeeping of its own, then invokes implFlush, which a subclass may
+ * override to do this cleanup.
+ *
+ * <p>The method returns one of two values:
+ * <ul>
+ * <li>[EMAIL PROTECTED] CoderResult#UNDERFLOW} - this indicates success, i.e.,
that
+ * the input (extra characters to be appended) is exhausted.
+ * </li>
+ * <li>[EMAIL PROTECTED] CoderResult#OVERFLOW} - this indicates failure, i.e.,
that
+ * the output [EMAIL PROTECTED] CharBuffer} is exhausted before the input is
+ * exhausted. If this happens, invoke [EMAIL PROTECTED] #flush} again with a
+ * [EMAIL PROTECTED] CharBuffer} that isn't exhausted.
+ * </li>
+ * </ul>
+ *
+ * <p>Note that this method can be invoked directly after [EMAIL PROTECTED] #reset}
+ * without
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}
+ * being invoked, so a subclass should probably check to see whether decode
+ * has been invoked, to decide what output to write.
+ *
+ * @param out the [EMAIL PROTECTED] CharBuffer} to write to.
+ * @return a [EMAIL PROTECTED] CoderResult} instance describing the success or
failure
+ * state of the method.
+ */
public final CoderResult flush (CharBuffer out)
{
// It seems weird that you can flush after reset, but Sun's javadoc
@@ -214,11 +573,34 @@
return implFlush (out);
}
+ /**
+ * Does any cleanup that subclasses need to do.
+ *
+ * <p>This method is intended to be subclassed to do any cleanup.
+ *
+ * See [EMAIL PROTECTED] #flush(CharBuffer out)}.
+ *
+ * @param out the [EMAIL PROTECTED] CharBuffer} to write to.
+ * @return a [EMAIL PROTECTED] CoderResult} instance describing whether the method
+ * succeeded or failed.
+ */
protected CoderResult implFlush (CharBuffer out)
{
return CoderResult.UNDERFLOW;
}
+ /**
+ * Sets the action to be taken when invalid input is received.
+ *
+ * <p>For details of the available actions, see [EMAIL PROTECTED]
CodingErrorAction}.
+ *
+ * @param newAction the action to be taken when invalid input is received.
+ *
+ * @return the <code>CharsetDecoder</code> that this method was invoked on.
+ *
+ * @throws IllegalArgumentException if <code>newAction</code> is
+ * <code>null</code>.
+ */
public final CharsetDecoder onMalformedInput (CodingErrorAction newAction)
{
if (newAction == null)
@@ -229,46 +611,140 @@
return this;
}
+ /**
+ * Notifies a subclass when the invoker has changed the action to be taken
+ * when malformed input is received.
+ *
+ * <p>The default implementation does nothing; it is just intended to be
+ * overridden if required.
+ *
+ * <p>This method is invoked by [EMAIL PROTECTED] #onMalformedInput}.
+ *
+ * @param newAction the action to be taken when malformed input is received.
+ */
protected void implOnMalformedInput (CodingErrorAction newAction)
{
// default implementation does nothing
}
+ /**
+ * Notifies a subclass when the invoker has changed the action to be taken
+ * when a sequence of bytes cannot be mapped to a Unicode character.
+ *
+ * <p>The default implementation does nothing; it is just intended to be
+ * overridden if required.
+ *
+ * <p>This method is invoked by [EMAIL PROTECTED] #onUnmappableCharacter}.
+ *
+ * @param newAction the action to be taken when a sequence of bytes is
+ * received that cannot be mapped to a Unicode character.
+ */
protected void implOnUnmappableCharacter (CodingErrorAction newAction)
{
// default implementation does nothing
}
+ /**
+ * Notifies a subclass when the invoker has changed the replacement
+ * [EMAIL PROTECTED] String} (the sequence of characters to be output when a
+ * character is encountered that cannot be mapped to Unicode in the current
+ * [EMAIL PROTECTED] Charset}).
+ *
+ * <p>The default implementation does nothing; it is just intended to be
+ * overridden if required.
+ *
+ * <p>This method is invoked by [EMAIL PROTECTED] #replaceWith}.
+ *
+ * @param newReplacement the new replacement String.
+ */
protected void implReplaceWith (String newReplacement)
{
// default implementation does nothing
}
+ /**
+ * Notifies a subclass when the invoker has invoked [EMAIL PROTECTED] #reset()}.
+ *
+ * <p>The default implementation does nothing; it is just intended to be
+ * overridden if required.
+ *
+ * <p>This method is invoked by [EMAIL PROTECTED] #reset()}.
+ */
protected void implReset ()
{
// default implementation does nothing
}
+ /**
+ * Determines whether this <code>CharsetDecoder</code> can work out how to
+ * decode data based on the actual data, i.e., whether it can auto-detect
+ * the charset.
+ *
+ * <p>The default implementation always returns true; subclasses should
+ * override it if they implement auto-detection.
+ *
+ * @return <code>true</code> if this <code>CharsetDecoder</code> is
+ * auto-detecting, <code>false</code> otherwise.
+ */
public boolean isAutoDetecting ()
{
return false;
}
+ /**
+ * Determines whether or not an auto-detecting <code>CharsetDecoder</code>
+ * has yet detected the [EMAIL PROTECTED] Charset} of the data.
+ *
+ * @return <code>true</code> if the auto-detecting
+ * <code>CharsetDecoder</code> has detected the [EMAIL PROTECTED] Charset} of the
+ * data, <code>false</code> otherwise. Note that a <code>false</code> value
+ * does not indicate that bytes have not been decoded, just that the
+ * <code>CharsetDecoder</code> has not detected the [EMAIL PROTECTED] Charset} of
+ * the data.
+ *
+ * @throws UnsupportedOperationException if the <code>CharsetDecoder</code>
+ * does not support auto-detection (this is the default).
+ */
public boolean isCharsetDetected ()
{
throw new UnsupportedOperationException ();
}
+ /**
+ * Returns the action to be taken when invalid data is received.
+ *
+ * @return the action to be taken when invalid data is received.
+ */
public CodingErrorAction malformedInputAction ()
{
return malformedInputAction;
}
+ /**
+ * Returns the maximum number of characters output per byte of input.
+ *
+ * <p>For example, if a character of output needs between 2 and 5 bytes,
+ * then this value will be 0.5f.
+ *
+ * @return the maximum number of characters output per byte of input.
+ */
public final float maxCharsPerByte ()
{
return maxCharsPerByte;
}
+ /**
+ * Changes the action to be taken when a character is received that does not
+ * map into Unicode in this [EMAIL PROTECTED] Charset}.
+ *
+ * @param newAction the action to be taken when a character is received that
+ * does not map into Unicode in this [EMAIL PROTECTED] Charset}.
+ *
+ * @return the <code>CharsetDecoder</code> that this method was invoked on,
+ * for convenience.
+ *
+ * @throws IllegalArgumentException if <code>newAction</code> is null.
+ */
public final CharsetDecoder onUnmappableCharacter
(CodingErrorAction newAction)
{
@@ -280,11 +756,33 @@
return this;
}
+ /**
+ * Returns the sequence of characters used to replace a character that
+ * cannot be mapped to Unicode.
+ *
+ * <p>The [EMAIL PROTECTED] String} returned always has some content, i.e., it is
+ * never <code>null</code> and it is never empty.
+ *
+ * @return the sequence of characters used to replace a character that
+ * cannot be mapped to Unicode.
+ */
public final String replacement ()
{
return replacement;
}
+ /**
+ * Changes the sequence of characters used to replace a character that
+ * cannot be mapped to Unicode.
+ *
+ * @param newReplacement the new sequence of characters to be used to
+ * replace characters that cannot be mapped to Unicode.
+ *
+ * @return the <code>CharsetDecoder</code> that this method was invoked on.
+ *
+ * @throws IllegalArgumentException if <code>newReplacement</code> is
+ * <code>null</code> or empty (a length of 0).
+ */
public final CharsetDecoder replaceWith (String newReplacement)
{
if (newReplacement == null)
@@ -298,6 +796,15 @@
return this;
}
+ /**
+ * Resets this <code>CharsetDecoder</code>, ready for
+ * [EMAIL PROTECTED] #decode(ByteBuffer in, CharBuffer out, boolean endOfInput)}.
+ *
+ * <p>Invokes [EMAIL PROTECTED] #implReset} to ensure that any reset actions in the
+ * subclass are performed.
+ *
+ * @return the <code>CharsetDecoder</code> that this method was invoked on.
+ */
public final CharsetDecoder reset ()
{
state = STATE_RESET;
@@ -305,6 +812,13 @@
return this;
}
+ /**
+ * Returns the action to be taken when a character is received that cannot
+ * be represented in Unicode.
+ *
+ * @return the action to be taken when a character is received that cannot
+ * be represented in Unicode.
+ */
public CodingErrorAction unmappableCharacterAction ()
{
return unmappableCharacterAction;
--- classpath-backup/ChangeLog 2003-09-20 11:40:43.000000000 +0100
+++ classpath/ChangeLog 2003-09-21 23:37:08.000000000 +0100
@@ -1,3 +1,7 @@
+2003-09-23 Ricky Clarkson <[EMAIL PROTECTED]>
+
+ * java/nio/charset/CharsetDecoder.java: Added documentation.
+
2003-09-19 Michael Koch <[EMAIL PROTECTED]>
* java/net/DatagramSocket.java
_______________________________________________
Classpath mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/classpath
