Name: rmT116609 Date: 08/28/2003


FULL PRODUCT VERSION :
java version "1.4.2"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2-b28)
Java HotSpot(TM) Client VM (build 1.4.2-b28, mixed mode)


FULL OS VERSION :
Linux ruddigore.ebi.ac.uk 2.4.20-xfs #2 SMP Fri Feb 21 15:57:53 GMT 2003 i686 unknown

A DESCRIPTION OF THE PROBLEM :
Two of the possible results of

  CharsetDecoder.decode(ByteBuffer, CharBuffer, boolean)

are CoderResult.UNDERFLOW and CoderResult.OVERFLOW depending
on whether the input buffer was used up or the output
buffer got filled.

The documentation of the method does not specify what
happens (should happen) if both situations occur at the
same time.

For example: Let the input buffer contain one byte and the
output buffer shall have room for exactly one more
character and the single byte shall code for one character.
After decoding the byte, the CharsetDecoder faces
underflow and overflow at the same time. The decoders I
tested return CoderResult.UNDERFLOW. But this is
not guaranteed by the documentation.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Read the docs.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Preferred: The docs should clearly state which of the
two possible results takes preceedence.

Also possible: The docs should clearly state that the
preceedence is implementation dependent. (This would
make application of a CharsetDecoder really tedious.)
ACTUAL -
The result of the example test case below reads:

% java DecoderTest
UNDERFLOW no. of decoded chars=1


REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
import java.nio.charset.CharsetDecoder;
import java.nio.charset.Charset;
import java.nio.charset.CoderResult;
import java.nio.ByteBuffer;
import java.nio.CharBuffer;

/**
 * test/demonstrate behaviour of CharsetDecoder.
 */
public class DecoderTest {
  public static void main(String[] argv) {
    CharsetDecoder dec = Charset.forName("UTF-8").newDecoder();

    // put just one byte into the input buffer
    ByteBuffer bbuf = ByteBuffer.allocate(10);
    bbuf.clear();
    bbuf.put((byte)'a');
    bbuf.flip();

    // use an output buffer with only one character
    CharBuffer cbuf = CharBuffer.allocate(1);
    cbuf.clear();

    // This will decode the one byte into one character. Because we
    // pass 'false' indicating there are more bytes, the decoder
    // faces underflow. But at the same time there is no more room in
    // the output buffer, which is overflow. What will the decoder
    // return? The docs don't specify it explicitely.
    CoderResult code = dec.decode(bbuf, cbuf, false);
    System.out.println(""+code+" no. of decoded chars="+cbuf.position());
  }
}

---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
Either: Use the example program above to test the behaviour of
CharsetDecoders you want to use.

Or: Write your software such that it does the write thing
independent of whether the decoder prefers to return
overflow or underflow.
(Incident Review ID: 200912)
======================================================================