The NIO charset API is being redesigned in order to address significant
performance problems and feature requests.  This bug is to track those changes
and summarize them when they're complete.

-- ###@###.### 2001/9/17


Summary of changes (see the JSR-51 / J2SE 1.4-beta3 spec for details):

 -  Defined the CoderResult class, a typesafe enumeration for reporting coder
    results.  The encode and decode methods, as well as the flush() methods,
    now return instances of this class rather than throw exceptions.  This
    change supports coders that are easier to use and reason about, and are
    significantly faster.

 -  Renamed substitution to replacement, which is more in line with the Unicode
    specification (and is also easier to spell).  The replacement is returned
    by the replacement method and changed by the replaceWith method.

 -  Generalized the handling of replacements so that separate actions can be
    specified for malformed-input vs. unmappable-character errors.  The action
    to be taken when an error is encountered is specified by an instance of the
    CodingErrorAction class, which is a simple typesafe enumeration.  The
    actions are specified via the onMalformedInput and onUnmappableCharacter
    methods; their current values may be retrieved via the malformedInputAction
    and unmappableCharacterAction methods.

 -  Defined charset methods in the coder classes so that the charset that
    created a coder may be retrieved from the coder itself.

 -  Added protected methods to better support subclasses: implReset, implFlush,
    implReplaceWith, implOnMalformedInput, and implOnUnmappableCharacter.
    These methods are invoked by the corresponding public methods after the
    public methods validate coder state and any arguments.  Their default
    implementations do nothing.  The implReset and implFlush methods were also
    required in order to implement coder state checking, i.e. the throwing of
    illegal-argument exceptions when a coder is used in a manner contrary to
    the specified coding-operation sequence.

 -  Cleaned up the API for auto-detecting charsets in CharsetDecoder by adding
    the isAutoDetecting and isCharsetDetected methods and making
    detectedCharset an optional operation.

 -  Defined the isLegalReplacement method in CharsetEncoder so that a
    replacement may be tested for validity without causing an exception to be
    thrown.

 -  Revised UnmappableCharacterException to report the number of input units
    that denote the unmappable character.

-- ###@###.### 2001/10/3