1 /*
   2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 #warn This file is preprocessed before being compiled
  27 
  28 package java.nio.charset;
  29 
  30 import java.nio.Buffer;
  31 import java.nio.ByteBuffer;
  32 import java.nio.CharBuffer;
  33 import java.nio.BufferOverflowException;
  34 import java.nio.BufferUnderflowException;
  35 import java.lang.ref.WeakReference;
  36 import java.nio.charset.CoderMalfunctionError;                  // javadoc
  37 import java.util.Arrays;
  38 
  39 
  40 /**
  41  * An engine that can transform a sequence of $itypesPhrase$ into a sequence of
  42  * $otypesPhrase$.
  43  *
  44  * <a id="steps"></a>
  45  *
  46  * <p> The input $itype$ sequence is provided in a $itype$ buffer or a series
  47  * of such buffers.  The output $otype$ sequence is written to a $otype$ buffer
  48  * or a series of such buffers.  $A$ $coder$ should always be used by making
  49  * the following sequence of method invocations, hereinafter referred to as $a$
  50  * <i>$coding$ operation</i>:
  51  *
  52  * <ol>
  53  *
  54  *   <li><p> Reset the $coder$ via the {@link #reset reset} method, unless it
  55  *   has not been used before; </p></li>
  56  *
  57  *   <li><p> Invoke the {@link #$code$ $code$} method zero or more times, as
  58  *   long as additional input may be available, passing {@code false} for the
  59  *   {@code endOfInput} argument and filling the input buffer and flushing the
  60  *   output buffer between invocations; </p></li>
  61  *
  62  *   <li><p> Invoke the {@link #$code$ $code$} method one final time, passing
  63  *   {@code true} for the {@code endOfInput} argument; and then </p></li>
  64  *
  65  *   <li><p> Invoke the {@link #flush flush} method so that the $coder$ can
  66  *   flush any internal state to the output buffer. </p></li>
  67  *
  68  * </ol>
  69  *
  70  * Each invocation of the {@link #$code$ $code$} method will $code$ as many
  71  * $itype$s as possible from the input buffer, writing the resulting $otype$s
  72  * to the output buffer.  The {@link #$code$ $code$} method returns when more
  73  * input is required, when there is not enough room in the output buffer, or
  74  * when $a$ $coding$ error has occurred.  In each case a {@link CoderResult}
  75  * object is returned to describe the reason for termination.  An invoker can
  76  * examine this object and fill the input buffer, flush the output buffer, or
  77  * attempt to recover from $a$ $coding$ error, as appropriate, and try again.
  78  *
  79  * <a id="ce"></a>
  80  *
  81  * <p> There are two general types of $coding$ errors.  If the input $itype$
  82  * sequence is $notLegal$ then the input is considered <i>malformed</i>.  If
  83  * the input $itype$ sequence is legal but cannot be mapped to a valid
  84  * $outSequence$ then an <i>unmappable character</i> has been encountered.
  85  *
  86  * <a id="cae"></a>
  87  *
  88  * <p> How $a$ $coding$ error is handled depends upon the action requested for
  89  * that type of error, which is described by an instance of the {@link
  90  * CodingErrorAction} class.  The possible error actions are to {@linkplain
  91  * CodingErrorAction#IGNORE ignore} the erroneous input, {@linkplain
  92  * CodingErrorAction#REPORT report} the error to the invoker via
  93  * the returned {@link CoderResult} object, or {@linkplain CodingErrorAction#REPLACE
  94  * replace} the erroneous input with the current value of the
  95  * replacement $replTypeName$.  The replacement
  96  *
  97 #if[encoder]
  98  * is initially set to the $coder$'s default replacement, which often
  99  * (but not always) has the initial value&nbsp;$defaultReplName$;
 100 #end[encoder]
 101 #if[decoder]
 102  * has the initial value $defaultReplName$;
 103 #end[decoder]
 104  *
 105  * its value may be changed via the {@link #replaceWith($replFQType$)
 106  * replaceWith} method.
 107  *
 108  * <p> The default action for malformed-input and unmappable-character errors
 109  * is to {@linkplain CodingErrorAction#REPORT report} them.  The
 110  * malformed-input error action may be changed via the {@link
 111  * #onMalformedInput(CodingErrorAction) onMalformedInput} method; the
 112  * unmappable-character action may be changed via the {@link
 113  * #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter} method.
 114  *
 115  * <p> This class is designed to handle many of the details of the $coding$
 116  * process, including the implementation of error actions.  $A$ $coder$ for a
 117  * specific charset, which is a concrete subclass of this class, need only
 118  * implement the abstract {@link #$code$Loop $code$Loop} method, which
 119  * encapsulates the basic $coding$ loop.  A subclass that maintains internal
 120  * state should, additionally, override the {@link #implFlush implFlush} and
 121  * {@link #implReset implReset} methods.
 122  *
 123  * <p> Instances of this class are not safe for use by multiple concurrent
 124  * threads.  </p>
 125  *
 126  *
 127  * @author Mark Reinhold
 128  * @author JSR-51 Expert Group
 129  * @since 1.4
 130  *
 131  * @see ByteBuffer
 132  * @see CharBuffer
 133  * @see Charset
 134  * @see Charset$OtherCoder$
 135  */
 136 
 137 public abstract class Charset$Coder$ {
 138 
 139     private final Charset charset;
 140     private final float average$ItypesPerOtype$;
 141     private final float max$ItypesPerOtype$;
 142 
 143     private $replType$ replacement;
 144     private CodingErrorAction malformedInputAction
 145         = CodingErrorAction.REPORT;
 146     private CodingErrorAction unmappableCharacterAction
 147         = CodingErrorAction.REPORT;
 148 
 149     // Internal states
 150     //
 151     private static final int ST_RESET   = 0;
 152     private static final int ST_CODING  = 1;
 153     private static final int ST_END     = 2;
 154     private static final int ST_FLUSHED = 3;
 155 
 156     private int state = ST_RESET;
 157 
 158     private static String stateNames[]
 159         = { "RESET", "CODING", "CODING_END", "FLUSHED" };
 160 
 161 
 162     /**
 163      * Initializes a new $coder$.  The new $coder$ will have the given
 164      * $otypes-per-itype$ and replacement values.
 165      *
 166      * @param  cs
 167      *         The charset that created this $coder$
 168      *
 169      * @param  average$ItypesPerOtype$
 170      *         A positive float value indicating the expected number of
 171      *         $otype$s that will be produced for each input $itype$
 172      *
 173      * @param  max$ItypesPerOtype$
 174      *         A positive float value indicating the maximum number of
 175      *         $otype$s that will be produced for each input $itype$
 176      *
 177      * @param  replacement
 178      *         The initial replacement; must not be {@code null}, must have
 179      *         non-zero length, must not be longer than max$ItypesPerOtype$,
 180      *         and must be {@linkplain #isLegalReplacement legal}
 181      *
 182      * @throws  IllegalArgumentException
 183      *          If the preconditions on the parameters do not hold
 184      */
 185     {#if[encoder]?protected:private}
 186     Charset$Coder$(Charset cs,
 187                    float average$ItypesPerOtype$,
 188                    float max$ItypesPerOtype$,
 189                    $replType$ replacement)
 190     {
 191         this.charset = cs;
 192         if (average$ItypesPerOtype$ <= 0.0f)
 193             throw new IllegalArgumentException("Non-positive "
 194                                                + "average$ItypesPerOtype$");
 195         if (max$ItypesPerOtype$ <= 0.0f)
 196             throw new IllegalArgumentException("Non-positive "
 197                                                + "max$ItypesPerOtype$");
 198         if (!Charset.atBugLevel("1.4")) {
 199             if (average$ItypesPerOtype$ > max$ItypesPerOtype$)
 200                 throw new IllegalArgumentException("average$ItypesPerOtype$"
 201                                                    + " exceeds "
 202                                                    + "max$ItypesPerOtype$");
 203         }
 204         this.replacement = replacement;
 205         this.average$ItypesPerOtype$ = average$ItypesPerOtype$;
 206         this.max$ItypesPerOtype$ = max$ItypesPerOtype$;
 207         replaceWith(replacement);
 208     }
 209 
 210     /**
 211      * Initializes a new $coder$.  The new $coder$ will have the given
 212      * $otypes-per-itype$ values and its replacement will be the
 213      * $replTypeName$ $defaultReplName$.
 214      *
 215      * @param  cs
 216      *         The charset that created this $coder$
 217      *
 218      * @param  average$ItypesPerOtype$
 219      *         A positive float value indicating the expected number of
 220      *         $otype$s that will be produced for each input $itype$
 221      *
 222      * @param  max$ItypesPerOtype$
 223      *         A positive float value indicating the maximum number of
 224      *         $otype$s that will be produced for each input $itype$
 225      *
 226      * @throws  IllegalArgumentException
 227      *          If the preconditions on the parameters do not hold
 228      */
 229     protected Charset$Coder$(Charset cs,
 230                              float average$ItypesPerOtype$,
 231                              float max$ItypesPerOtype$)
 232     {
 233         this(cs,
 234              average$ItypesPerOtype$, max$ItypesPerOtype$,
 235              $defaultRepl$);
 236     }
 237 
 238     /**
 239      * Returns the charset that created this $coder$.
 240      *
 241      * @return  This $coder$'s charset
 242      */
 243     public final Charset charset() {
 244         return charset;
 245     }
 246 
 247     /**
 248      * Returns this $coder$'s replacement value.
 249      *
 250      * @return  This $coder$'s current replacement,
 251      *          which is never {@code null} and is never empty
 252      */
 253     public final $replType$ replacement() {
 254 #if[decoder]
 255         return replacement;
 256 #end[decoder]
 257 #if[encoder]
 258         return Arrays.copyOf(replacement, replacement.$replLength$);
 259 #end[encoder]
 260     }
 261 
 262     /**
 263      * Changes this $coder$'s replacement value.
 264      *
 265      * <p> This method invokes the {@link #implReplaceWith implReplaceWith}
 266      * method, passing the new replacement, after checking that the new
 267      * replacement is acceptable.  </p>
 268      *
 269      * @param  newReplacement  The new replacement; must not be
 270      *         {@code null}, must have non-zero length,
 271 #if[decoder]
 272      *         and must not be longer than the value returned by the
 273      *         {@link #max$ItypesPerOtype$() max$ItypesPerOtype$} method
 274 #end[decoder]
 275 #if[encoder]
 276      *         must not be longer than the value returned by the
 277      *         {@link #max$ItypesPerOtype$() max$ItypesPerOtype$} method, and
 278      *         must be {@link #isLegalReplacement legal}
 279 #end[encoder]
 280      *
 281      * @return  This $coder$
 282      *
 283      * @throws  IllegalArgumentException
 284      *          If the preconditions on the parameter do not hold
 285      */
 286     public final Charset$Coder$ replaceWith($replType$ newReplacement) {
 287         if (newReplacement == null)
 288             throw new IllegalArgumentException("Null replacement");
 289         int len = newReplacement.$replLength$;
 290         if (len == 0)
 291             throw new IllegalArgumentException("Empty replacement");
 292         if (len > max$ItypesPerOtype$)
 293             throw new IllegalArgumentException("Replacement too long");
 294 #if[decoder]
 295         this.replacement = newReplacement;
 296 #end[decoder]
 297 #if[encoder]
 298         if (!isLegalReplacement(newReplacement))
 299             throw new IllegalArgumentException("Illegal replacement");
 300         this.replacement = Arrays.copyOf(newReplacement, newReplacement.$replLength$);
 301 #end[encoder]
 302         implReplaceWith(this.replacement);
 303         return this;
 304     }
 305 
 306     /**
 307      * Reports a change to this $coder$'s replacement value.
 308      *
 309      * <p> The default implementation of this method does nothing.  This method
 310      * should be overridden by $coder$s that require notification of changes to
 311      * the replacement.  </p>
 312      *
 313      * @param  newReplacement    The replacement value
 314      */
 315     protected void implReplaceWith($replType$ newReplacement) {
 316     }
 317 
 318 #if[encoder]
 319 
 320     private WeakReference<CharsetDecoder> cachedDecoder = null;
 321 
 322     /**
 323      * Tells whether or not the given byte array is a legal replacement value
 324      * for this encoder.
 325      *
 326      * <p> A replacement is legal if, and only if, it is a legal sequence of
 327      * bytes in this encoder's charset; that is, it must be possible to decode
 328      * the replacement into one or more sixteen-bit Unicode characters.
 329      *
 330      * <p> The default implementation of this method is not very efficient; it
 331      * should generally be overridden to improve performance.  </p>
 332      *
 333      * @param  repl  The byte array to be tested
 334      *
 335      * @return  {@code true} if, and only if, the given byte array
 336      *          is a legal replacement value for this encoder
 337      */
 338     public boolean isLegalReplacement(byte[] repl) {
 339         WeakReference<CharsetDecoder> wr = cachedDecoder;
 340         CharsetDecoder dec = null;
 341         if ((wr == null) || ((dec = wr.get()) == null)) {
 342             dec = charset().newDecoder();
 343             dec.onMalformedInput(CodingErrorAction.REPORT);
 344             dec.onUnmappableCharacter(CodingErrorAction.REPORT);
 345             cachedDecoder = new WeakReference<CharsetDecoder>(dec);
 346         } else {
 347             dec.reset();
 348         }
 349         ByteBuffer bb = ByteBuffer.wrap(repl);
 350         CharBuffer cb = CharBuffer.allocate((int)(bb.remaining()
 351                                                   * dec.maxCharsPerByte()));
 352         CoderResult cr = dec.decode(bb, cb, true);
 353         return !cr.isError();
 354     }
 355 
 356 #end[encoder]
 357 
 358     /**
 359      * Returns this $coder$'s current action for malformed-input errors.
 360      *
 361      * @return The current malformed-input action, which is never {@code null}
 362      */
 363     public CodingErrorAction malformedInputAction() {
 364         return malformedInputAction;
 365     }
 366 
 367     /**
 368      * Changes this $coder$'s action for malformed-input errors.
 369      *
 370      * <p> This method invokes the {@link #implOnMalformedInput
 371      * implOnMalformedInput} method, passing the new action.  </p>
 372      *
 373      * @param  newAction  The new action; must not be {@code null}
 374      *
 375      * @return  This $coder$
 376      *
 377      * @throws IllegalArgumentException
 378      *         If the precondition on the parameter does not hold
 379      */
 380     public final Charset$Coder$ onMalformedInput(CodingErrorAction newAction) {
 381         if (newAction == null)
 382             throw new IllegalArgumentException("Null action");
 383         malformedInputAction = newAction;
 384         implOnMalformedInput(newAction);
 385         return this;
 386     }
 387 
 388     /**
 389      * Reports a change to this $coder$'s malformed-input action.
 390      *
 391      * <p> The default implementation of this method does nothing.  This method
 392      * should be overridden by $coder$s that require notification of changes to
 393      * the malformed-input action.  </p>
 394      *
 395      * @param  newAction  The new action
 396      */
 397     protected void implOnMalformedInput(CodingErrorAction newAction) { }
 398 
 399     /**
 400      * Returns this $coder$'s current action for unmappable-character errors.
 401      *
 402      * @return The current unmappable-character action, which is never
 403      *         {@code null}
 404      */
 405     public CodingErrorAction unmappableCharacterAction() {
 406         return unmappableCharacterAction;
 407     }
 408 
 409     /**
 410      * Changes this $coder$'s action for unmappable-character errors.
 411      *
 412      * <p> This method invokes the {@link #implOnUnmappableCharacter
 413      * implOnUnmappableCharacter} method, passing the new action.  </p>
 414      *
 415      * @param  newAction  The new action; must not be {@code null}
 416      *
 417      * @return  This $coder$
 418      *
 419      * @throws IllegalArgumentException
 420      *         If the precondition on the parameter does not hold
 421      */
 422     public final Charset$Coder$ onUnmappableCharacter(CodingErrorAction
 423                                                       newAction)
 424     {
 425         if (newAction == null)
 426             throw new IllegalArgumentException("Null action");
 427         unmappableCharacterAction = newAction;
 428         implOnUnmappableCharacter(newAction);
 429         return this;
 430     }
 431 
 432     /**
 433      * Reports a change to this $coder$'s unmappable-character action.
 434      *
 435      * <p> The default implementation of this method does nothing.  This method
 436      * should be overridden by $coder$s that require notification of changes to
 437      * the unmappable-character action.  </p>
 438      *
 439      * @param  newAction  The new action
 440      */
 441     protected void implOnUnmappableCharacter(CodingErrorAction newAction) { }
 442 
 443     /**
 444      * Returns the average number of $otype$s that will be produced for each
 445      * $itype$ of input.  This heuristic value may be used to estimate the size
 446      * of the output buffer required for a given input sequence.
 447      *
 448      * @return  The average number of $otype$s produced
 449      *          per $itype$ of input
 450      */
 451     public final float average$ItypesPerOtype$() {
 452         return average$ItypesPerOtype$;
 453     }
 454 
 455     /**
 456      * Returns the maximum number of $otype$s that will be produced for each
 457      * $itype$ of input.  This value may be used to compute the worst-case size
 458      * of the output buffer required for a given input sequence.
 459      *
 460      * @return  The maximum number of $otype$s that will be produced per
 461      *          $itype$ of input
 462      */
 463     public final float max$ItypesPerOtype$() {
 464         return max$ItypesPerOtype$;
 465     }
 466 
 467     /**
 468      * $Code$s as many $itype$s as possible from the given input buffer,
 469      * writing the results to the given output buffer.
 470      *
 471      * <p> The buffers are read from, and written to, starting at their current
 472      * positions.  At most {@link Buffer#remaining in.remaining()} $itype$s
 473      * will be read and at most {@link Buffer#remaining out.remaining()}
 474      * $otype$s will be written.  The buffers' positions will be advanced to
 475      * reflect the $itype$s read and the $otype$s written, but their marks and
 476      * limits will not be modified.
 477      *
 478      * <p> In addition to reading $itype$s from the input buffer and writing
 479      * $otype$s to the output buffer, this method returns a {@link CoderResult}
 480      * object to describe its reason for termination:
 481      *
 482      * <ul>
 483      *
 484      *   <li><p> {@link CoderResult#UNDERFLOW} indicates that as much of the
 485      *   input buffer as possible has been $code$d.  If there is no further
 486      *   input then the invoker can proceed to the next step of the
 487      *   <a href="#steps">$coding$ operation</a>.  Otherwise this method
 488      *   should be invoked again with further input.  </p></li>
 489      *
 490      *   <li><p> {@link CoderResult#OVERFLOW} indicates that there is
 491      *   insufficient space in the output buffer to $code$ any more $itype$s.
 492      *   This method should be invoked again with an output buffer that has
 493      *   more {@linkplain Buffer#remaining remaining} $otype$s. This is
 494      *   typically done by draining any $code$d $otype$s from the output
 495      *   buffer.  </p></li>
 496      *
 497      *   <li><p> A {@linkplain CoderResult#malformedForLength
 498      *   malformed-input} result indicates that a malformed-input
 499      *   error has been detected.  The malformed $itype$s begin at the input
 500      *   buffer's (possibly incremented) position; the number of malformed
 501      *   $itype$s may be determined by invoking the result object's {@link
 502      *   CoderResult#length() length} method.  This case applies only if the
 503      *   {@linkplain #onMalformedInput malformed action} of this $coder$
 504      *   is {@link CodingErrorAction#REPORT}; otherwise the malformed input
 505      *   will be ignored or replaced, as requested.  </p></li>
 506      *
 507      *   <li><p> An {@linkplain CoderResult#unmappableForLength
 508      *   unmappable-character} result indicates that an
 509      *   unmappable-character error has been detected.  The $itype$s that
 510      *   $code$ the unmappable character begin at the input buffer's (possibly
 511      *   incremented) position; the number of such $itype$s may be determined
 512      *   by invoking the result object's {@link CoderResult#length() length}
 513      *   method.  This case applies only if the {@linkplain #onUnmappableCharacter
 514      *   unmappable action} of this $coder$ is {@link
 515      *   CodingErrorAction#REPORT}; otherwise the unmappable character will be
 516      *   ignored or replaced, as requested.  </p></li>
 517      *
 518      * </ul>
 519      *
 520      * In any case, if this method is to be reinvoked in the same $coding$
 521      * operation then care should be taken to preserve any $itype$s remaining
 522      * in the input buffer so that they are available to the next invocation.
 523      *
 524      * <p> The {@code endOfInput} parameter advises this method as to whether
 525      * the invoker can provide further input beyond that contained in the given
 526      * input buffer.  If there is a possibility of providing additional input
 527      * then the invoker should pass {@code false} for this parameter; if there
 528      * is no possibility of providing further input then the invoker should
 529      * pass {@code true}.  It is not erroneous, and in fact it is quite
 530      * common, to pass {@code false} in one invocation and later discover that
 531      * no further input was actually available.  It is critical, however, that
 532      * the final invocation of this method in a sequence of invocations always
 533      * pass {@code true} so that any remaining un$code$d input will be treated
 534      * as being malformed.
 535      *
 536      * <p> This method works by invoking the {@link #$code$Loop $code$Loop}
 537      * method, interpreting its results, handling error conditions, and
 538      * reinvoking it as necessary.  </p>
 539      *
 540      *
 541      * @param  in
 542      *         The input $itype$ buffer
 543      *
 544      * @param  out
 545      *         The output $otype$ buffer
 546      *
 547      * @param  endOfInput
 548      *         {@code true} if, and only if, the invoker can provide no
 549      *         additional input $itype$s beyond those in the given buffer
 550      *
 551      * @return  A coder-result object describing the reason for termination
 552      *
 553      * @throws  IllegalStateException
 554      *          If $a$ $coding$ operation is already in progress and the previous
 555      *          step was an invocation neither of the {@link #reset reset}
 556      *          method, nor of this method with a value of {@code false} for
 557      *          the {@code endOfInput} parameter, nor of this method with a
 558      *          value of {@code true} for the {@code endOfInput} parameter
 559      *          but a return value indicating an incomplete $coding$ operation
 560      *
 561      * @throws  CoderMalfunctionError
 562      *          If an invocation of the $code$Loop method threw
 563      *          an unexpected exception
 564      */
 565     public final CoderResult $code$($Itype$Buffer in, $Otype$Buffer out,
 566                                     boolean endOfInput)
 567     {
 568         int newState = endOfInput ? ST_END : ST_CODING;
 569         if ((state != ST_RESET) && (state != ST_CODING)
 570             && !(endOfInput && (state == ST_END)))
 571             throwIllegalStateException(state, newState);
 572         state = newState;
 573 
 574         for (;;) {
 575 
 576             CoderResult cr;
 577             try {
 578                 cr = $code$Loop(in, out);
 579             } catch (BufferUnderflowException x) {
 580                 throw new CoderMalfunctionError(x);
 581             } catch (BufferOverflowException x) {
 582                 throw new CoderMalfunctionError(x);
 583             }
 584 
 585             if (cr.isOverflow())
 586                 return cr;
 587 
 588             if (cr.isUnderflow()) {
 589                 if (endOfInput && in.hasRemaining()) {
 590                     cr = CoderResult.malformedForLength(in.remaining());
 591                     // Fall through to malformed-input case
 592                 } else {
 593                     return cr;
 594                 }
 595             }
 596 
 597             CodingErrorAction action = null;
 598             if (cr.isMalformed())
 599                 action = malformedInputAction;
 600             else if (cr.isUnmappable())
 601                 action = unmappableCharacterAction;
 602             else
 603                 assert false : cr.toString();
 604 
 605             if (action == CodingErrorAction.REPORT)
 606                 return cr;
 607 
 608             if (action == CodingErrorAction.REPLACE) {
 609                 if (out.remaining() < replacement.$replLength$)
 610                     return CoderResult.OVERFLOW;
 611                 out.put(replacement);
 612             }
 613 
 614             if ((action == CodingErrorAction.IGNORE)
 615                 || (action == CodingErrorAction.REPLACE)) {
 616                 // Skip erroneous input either way
 617                 in.position(in.position() + cr.length());
 618                 continue;
 619             }
 620 
 621             assert false;
 622         }
 623 
 624     }
 625 
 626     /**
 627      * Flushes this $coder$.
 628      *
 629      * <p> Some $coder$s maintain internal state and may need to write some
 630      * final $otype$s to the output buffer once the overall input sequence has
 631      * been read.
 632      *
 633      * <p> Any additional output is written to the output buffer beginning at
 634      * its current position.  At most {@link Buffer#remaining out.remaining()}
 635      * $otype$s will be written.  The buffer's position will be advanced
 636      * appropriately, but its mark and limit will not be modified.
 637      *
 638      * <p> If this method completes successfully then it returns {@link
 639      * CoderResult#UNDERFLOW}.  If there is insufficient room in the output
 640      * buffer then it returns {@link CoderResult#OVERFLOW}.  If this happens
 641      * then this method must be invoked again, with an output buffer that has
 642      * more room, in order to complete the current <a href="#steps">$coding$
 643      * operation</a>.
 644      *
 645      * <p> If this $coder$ has already been flushed then invoking this method
 646      * has no effect.
 647      *
 648      * <p> This method invokes the {@link #implFlush implFlush} method to
 649      * perform the actual flushing operation.  </p>
 650      *
 651      * @param  out
 652      *         The output $otype$ buffer
 653      *
 654      * @return  A coder-result object, either {@link CoderResult#UNDERFLOW} or
 655      *          {@link CoderResult#OVERFLOW}
 656      *
 657      * @throws  IllegalStateException
 658      *          If the previous step of the current $coding$ operation was an
 659      *          invocation neither of the {@link #flush flush} method nor of
 660      *          the three-argument {@link
 661      *          #$code$($Itype$Buffer,$Otype$Buffer,boolean) $code$} method
 662      *          with a value of {@code true} for the {@code endOfInput}
 663      *          parameter
 664      */
 665     public final CoderResult flush($Otype$Buffer out) {
 666         if (state == ST_END) {
 667             CoderResult cr = implFlush(out);
 668             if (cr.isUnderflow())
 669                 state = ST_FLUSHED;
 670             return cr;
 671         }
 672 
 673         if (state != ST_FLUSHED)
 674             throwIllegalStateException(state, ST_FLUSHED);
 675 
 676         return CoderResult.UNDERFLOW; // Already flushed
 677     }
 678 
 679     /**
 680      * Flushes this $coder$.
 681      *
 682      * <p> The default implementation of this method does nothing, and always
 683      * returns {@link CoderResult#UNDERFLOW}.  This method should be overridden
 684      * by $coder$s that may need to write final $otype$s to the output buffer
 685      * once the entire input sequence has been read. </p>
 686      *
 687      * @param  out
 688      *         The output $otype$ buffer
 689      *
 690      * @return  A coder-result object, either {@link CoderResult#UNDERFLOW} or
 691      *          {@link CoderResult#OVERFLOW}
 692      */
 693     protected CoderResult implFlush($Otype$Buffer out) {
 694         return CoderResult.UNDERFLOW;
 695     }
 696 
 697     /**
 698      * Resets this $coder$, clearing any internal state.
 699      *
 700      * <p> This method resets charset-independent state and also invokes the
 701      * {@link #implReset() implReset} method in order to perform any
 702      * charset-specific reset actions.  </p>
 703      *
 704      * @return  This $coder$
 705      *
 706      */
 707     public final Charset$Coder$ reset() {
 708         implReset();
 709         state = ST_RESET;
 710         return this;
 711     }
 712 
 713     /**
 714      * Resets this $coder$, clearing any charset-specific internal state.
 715      *
 716      * <p> The default implementation of this method does nothing.  This method
 717      * should be overridden by $coder$s that maintain internal state.  </p>
 718      */
 719     protected void implReset() { }
 720 
 721     /**
 722      * $Code$s one or more $itype$s into one or more $otype$s.
 723      *
 724      * <p> This method encapsulates the basic $coding$ loop, $coding$ as many
 725      * $itype$s as possible until it either runs out of input, runs out of room
 726      * in the output buffer, or encounters $a$ $coding$ error.  This method is
 727      * invoked by the {@link #$code$ $code$} method, which handles result
 728      * interpretation and error recovery.
 729      *
 730      * <p> The buffers are read from, and written to, starting at their current
 731      * positions.  At most {@link Buffer#remaining in.remaining()} $itype$s
 732      * will be read, and at most {@link Buffer#remaining out.remaining()}
 733      * $otype$s will be written.  The buffers' positions will be advanced to
 734      * reflect the $itype$s read and the $otype$s written, but their marks and
 735      * limits will not be modified.
 736      *
 737      * <p> This method returns a {@link CoderResult} object to describe its
 738      * reason for termination, in the same manner as the {@link #$code$ $code$}
 739      * method.  Most implementations of this method will handle $coding$ errors
 740      * by returning an appropriate result object for interpretation by the
 741      * {@link #$code$ $code$} method.  An optimized implementation may instead
 742      * examine the relevant error action and implement that action itself.
 743      *
 744      * <p> An implementation of this method may perform arbitrary lookahead by
 745      * returning {@link CoderResult#UNDERFLOW} until it receives sufficient
 746      * input.  </p>
 747      *
 748      * @param  in
 749      *         The input $itype$ buffer
 750      *
 751      * @param  out
 752      *         The output $otype$ buffer
 753      *
 754      * @return  A coder-result object describing the reason for termination
 755      */
 756     protected abstract CoderResult $code$Loop($Itype$Buffer in,
 757                                               $Otype$Buffer out);
 758 
 759     /**
 760      * Convenience method that $code$s the remaining content of a single input
 761      * $itype$ buffer into a newly-allocated $otype$ buffer.
 762      *
 763      * <p> This method implements an entire <a href="#steps">$coding$
 764      * operation</a>; that is, it resets this $coder$, then it $code$s the
 765      * $itype$s in the given $itype$ buffer, and finally it flushes this
 766      * $coder$.  This method should therefore not be invoked if $a$ $coding$
 767      * operation is already in progress.  </p>
 768      *
 769      * @param  in
 770      *         The input $itype$ buffer
 771      *
 772      * @return A newly-allocated $otype$ buffer containing the result of the
 773      *         $coding$ operation.  The buffer's position will be zero and its
 774      *         limit will follow the last $otype$ written.
 775      *
 776      * @throws  IllegalStateException
 777      *          If $a$ $coding$ operation is already in progress
 778      *
 779      * @throws  MalformedInputException
 780      *          If the $itype$ sequence starting at the input buffer's current
 781      *          position is $notLegal$ and the current malformed-input action
 782      *          is {@link CodingErrorAction#REPORT}
 783      *
 784      * @throws  UnmappableCharacterException
 785      *          If the $itype$ sequence starting at the input buffer's current
 786      *          position cannot be mapped to an equivalent $otype$ sequence and
 787      *          the current unmappable-character action is {@link
 788      *          CodingErrorAction#REPORT}
 789      */
 790     public final $Otype$Buffer $code$($Itype$Buffer in)
 791         throws CharacterCodingException
 792     {
 793         int n = (int)(in.remaining() * average$ItypesPerOtype$());
 794         $Otype$Buffer out = $Otype$Buffer.allocate(n);
 795 
 796         if ((n == 0) && (in.remaining() == 0))
 797             return out;
 798         reset();
 799         for (;;) {
 800             CoderResult cr = in.hasRemaining() ?
 801                 $code$(in, out, true) : CoderResult.UNDERFLOW;
 802             if (cr.isUnderflow())
 803                 cr = flush(out);
 804 
 805             if (cr.isUnderflow())
 806                 break;
 807             if (cr.isOverflow()) {
 808                 n = 2*n + 1;    // Ensure progress; n might be 0!
 809                 $Otype$Buffer o = $Otype$Buffer.allocate(n);
 810                 out.flip();
 811                 o.put(out);
 812                 out = o;
 813                 continue;
 814             }
 815             cr.throwException();
 816         }
 817         out.flip();
 818         return out;
 819     }
 820 
 821 #if[decoder]
 822 
 823     /**
 824      * Tells whether or not this decoder implements an auto-detecting charset.
 825      *
 826      * <p> The default implementation of this method always returns
 827      * {@code false}; it should be overridden by auto-detecting decoders to
 828      * return {@code true}.  </p>
 829      *
 830      * @return  {@code true} if, and only if, this decoder implements an
 831      *          auto-detecting charset
 832      */
 833     public boolean isAutoDetecting() {
 834         return false;
 835     }
 836 
 837     /**
 838      * Tells whether or not this decoder has yet detected a
 839      * charset&nbsp;&nbsp;<i>(optional operation)</i>.
 840      *
 841      * <p> If this decoder implements an auto-detecting charset then at a
 842      * single point during a decoding operation this method may start returning
 843      * {@code true} to indicate that a specific charset has been detected in
 844      * the input byte sequence.  Once this occurs, the {@link #detectedCharset
 845      * detectedCharset} method may be invoked to retrieve the detected charset.
 846      *
 847      * <p> That this method returns {@code false} does not imply that no bytes
 848      * have yet been decoded.  Some auto-detecting decoders are capable of
 849      * decoding some, or even all, of an input byte sequence without fixing on
 850      * a particular charset.
 851      *
 852      * <p> The default implementation of this method always throws an {@link
 853      * UnsupportedOperationException}; it should be overridden by
 854      * auto-detecting decoders to return {@code true} once the input charset
 855      * has been determined.  </p>
 856      *
 857      * @return  {@code true} if, and only if, this decoder has detected a
 858      *          specific charset
 859      *
 860      * @throws  UnsupportedOperationException
 861      *          If this decoder does not implement an auto-detecting charset
 862      */
 863     public boolean isCharsetDetected() {
 864         throw new UnsupportedOperationException();
 865     }
 866 
 867     /**
 868      * Retrieves the charset that was detected by this
 869      * decoder&nbsp;&nbsp;<i>(optional operation)</i>.
 870      *
 871      * <p> If this decoder implements an auto-detecting charset then this
 872      * method returns the actual charset once it has been detected.  After that
 873      * point, this method returns the same value for the duration of the
 874      * current decoding operation.  If not enough input bytes have yet been
 875      * read to determine the actual charset then this method throws an {@link
 876      * IllegalStateException}.
 877      *
 878      * <p> The default implementation of this method always throws an {@link
 879      * UnsupportedOperationException}; it should be overridden by
 880      * auto-detecting decoders to return the appropriate value.  </p>
 881      *
 882      * @return  The charset detected by this auto-detecting decoder,
 883      *          or {@code null} if the charset has not yet been determined
 884      *
 885      * @throws  IllegalStateException
 886      *          If insufficient bytes have been read to determine a charset
 887      *
 888      * @throws  UnsupportedOperationException
 889      *          If this decoder does not implement an auto-detecting charset
 890      */
 891     public Charset detectedCharset() {
 892         throw new UnsupportedOperationException();
 893     }
 894 
 895 #end[decoder]
 896 
 897 #if[encoder]
 898 
 899     private boolean canEncode(CharBuffer cb) {
 900         if (state == ST_FLUSHED)
 901             reset();
 902         else if (state != ST_RESET)
 903             throwIllegalStateException(state, ST_CODING);
 904         CodingErrorAction ma = malformedInputAction();
 905         CodingErrorAction ua = unmappableCharacterAction();
 906         try {
 907             onMalformedInput(CodingErrorAction.REPORT);
 908             onUnmappableCharacter(CodingErrorAction.REPORT);
 909             encode(cb);
 910         } catch (CharacterCodingException x) {
 911             return false;
 912         } finally {
 913             onMalformedInput(ma);
 914             onUnmappableCharacter(ua);
 915             reset();
 916         }
 917         return true;
 918     }
 919 
 920     /**
 921      * Tells whether or not this encoder can encode the given character.
 922      *
 923      * <p> This method returns {@code false} if the given character is a
 924      * surrogate character; such characters can be interpreted only when they
 925      * are members of a pair consisting of a high surrogate followed by a low
 926      * surrogate.  The {@link #canEncode(java.lang.CharSequence)
 927      * canEncode(CharSequence)} method may be used to test whether or not a
 928      * character sequence can be encoded.
 929      *
 930      * <p> This method may modify this encoder's state; it should therefore not
 931      * be invoked if an <a href="#steps">encoding operation</a> is already in
 932      * progress.
 933      *
 934      * <p> The default implementation of this method is not very efficient; it
 935      * should generally be overridden to improve performance.  </p>
 936      *
 937      * @param   c
 938      *          The given character
 939      *
 940      * @return  {@code true} if, and only if, this encoder can encode
 941      *          the given character
 942      *
 943      * @throws  IllegalStateException
 944      *          If $a$ $coding$ operation is already in progress
 945      */
 946     public boolean canEncode(char c) {
 947         CharBuffer cb = CharBuffer.allocate(1);
 948         cb.put(c);
 949         cb.flip();
 950         return canEncode(cb);
 951     }
 952 
 953     /**
 954      * Tells whether or not this encoder can encode the given character
 955      * sequence.
 956      *
 957      * <p> If this method returns {@code false} for a particular character
 958      * sequence then more information about why the sequence cannot be encoded
 959      * may be obtained by performing a full <a href="#steps">encoding
 960      * operation</a>.
 961      *
 962      * <p> This method may modify this encoder's state; it should therefore not
 963      * be invoked if an encoding operation is already in progress.
 964      *
 965      * <p> The default implementation of this method is not very efficient; it
 966      * should generally be overridden to improve performance.  </p>
 967      *
 968      * @param   cs
 969      *          The given character sequence
 970      *
 971      * @return  {@code true} if, and only if, this encoder can encode
 972      *          the given character without throwing any exceptions and without
 973      *          performing any replacements
 974      *
 975      * @throws  IllegalStateException
 976      *          If $a$ $coding$ operation is already in progress
 977      */
 978     public boolean canEncode(CharSequence cs) {
 979         CharBuffer cb;
 980         if (cs instanceof CharBuffer)
 981             cb = ((CharBuffer)cs).duplicate();
 982         else
 983             cb = CharBuffer.wrap(cs.toString());
 984         return canEncode(cb);
 985     }
 986 
 987 #end[encoder]
 988 
 989 
 990     private void throwIllegalStateException(int from, int to) {
 991         throw new IllegalStateException("Current state = " + stateNames[from]
 992                                         + ", new state = " + stateNames[to]);
 993     }
 994 
 995 }
--- EOF ---