The spec for
Charset-X-Coder.$code$($Itype$Buffer in, $Otype$Buffer out,
boolean endOfInput)

states:

     *
     * <li><p> {@link CoderResult#UNDERFLOW} indicates that as much of the
     * input buffer as possible has been $code$d. If there are no $itype$s
     * remaining and the invoker has no further input then the $coding$
     * operation is complete. Otherwise there is insufficient input for the
     * operation to proceed, so this method should be invoked again with
     * further input. </p></li>

But...an $coding$ operation includes, among other things, flush(),
so the $coding$ operation cannot be complete.

     *
     * <li><p> {@link CoderResult#OVERFLOW} indicates that the output buffer
     * is full. This method should be invoked again with a non-full output
     * buffer. </p></li>
     *
But... there might be one $otype$ remaining in the output buffer, which
would make it non-full, yet there is no room to $code$ any more $itype$s.
It is even possible to get OVERFLOW with a completely empty output buffer.

###@###.### 2005-2-18 22:43:48 GMT