1 /*
   2  * Copyright (c) 2000, 2013, 2017, 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 (average$ItypesPerOtype$ > max$ItypesPerOtype$)
 199             throw new IllegalArgumentException("average$ItypesPerOtype$"
 200                                                + " exceeds "
 201                                                + "max$ItypesPerOtype$");

 202         this.replacement = replacement;
 203         this.average$ItypesPerOtype$ = average$ItypesPerOtype$;
 204         this.max$ItypesPerOtype$ = max$ItypesPerOtype$;
 205         replaceWith(replacement);
 206     }
 207 
 208     /**
 209      * Initializes a new $coder$.  The new $coder$ will have the given
 210      * $otypes-per-itype$ values and its replacement will be the
 211      * $replTypeName$ $defaultReplName$.
 212      *
 213      * @param  cs
 214      *         The charset that created this $coder$
 215      *
 216      * @param  average$ItypesPerOtype$
 217      *         A positive float value indicating the expected number of
 218      *         $otype$s that will be produced for each input $itype$
 219      *
 220      * @param  max$ItypesPerOtype$
 221      *         A positive float value indicating the maximum number of
 222      *         $otype$s that will be produced for each input $itype$
 223      *
 224      * @throws  IllegalArgumentException
 225      *          If the preconditions on the parameters do not hold
 226      */
 227     protected Charset$Coder$(Charset cs,
 228                              float average$ItypesPerOtype$,
 229                              float max$ItypesPerOtype$)
 230     {
 231         this(cs,
 232              average$ItypesPerOtype$, max$ItypesPerOtype$,
 233              $defaultRepl$);
 234     }
 235 
 236     /**
 237      * Returns the charset that created this $coder$.
 238      *
 239      * @return  This $coder$'s charset
 240      */
 241     public final Charset charset() {
 242         return charset;
 243     }
 244 
 245     /**
 246      * Returns this $coder$'s replacement value.
 247      *
 248      * @return  This $coder$'s current replacement,
 249      *          which is never {@code null} and is never empty
 250      */
 251     public final $replType$ replacement() {
 252 #if[decoder]
 253         return replacement;
 254 #end[decoder]
 255 #if[encoder]
 256         return Arrays.copyOf(replacement, replacement.$replLength$);
 257 #end[encoder]
 258     }
 259 
 260     /**
 261      * Changes this $coder$'s replacement value.
 262      *
 263      * <p> This method invokes the {@link #implReplaceWith implReplaceWith}
 264      * method, passing the new replacement, after checking that the new
 265      * replacement is acceptable.  </p>
 266      *
 267      * @param  newReplacement  The new replacement; must not be
 268      *         {@code null}, must have non-zero length,
 269 #if[decoder]
 270      *         and must not be longer than the value returned by the
 271      *         {@link #max$ItypesPerOtype$() max$ItypesPerOtype$} method
 272 #end[decoder]
 273 #if[encoder]
 274      *         must not be longer than the value returned by the
 275      *         {@link #max$ItypesPerOtype$() max$ItypesPerOtype$} method, and
 276      *         must be {@link #isLegalReplacement legal}
 277 #end[encoder]
 278      *
 279      * @return  This $coder$
 280      *
 281      * @throws  IllegalArgumentException
 282      *          If the preconditions on the parameter do not hold
 283      */
 284     public final Charset$Coder$ replaceWith($replType$ newReplacement) {
 285         if (newReplacement == null)
 286             throw new IllegalArgumentException("Null replacement");
 287         int len = newReplacement.$replLength$;
 288         if (len == 0)
 289             throw new IllegalArgumentException("Empty replacement");
 290         if (len > max$ItypesPerOtype$)
 291             throw new IllegalArgumentException("Replacement too long");
 292 #if[decoder]
 293         this.replacement = newReplacement;
 294 #end[decoder]
 295 #if[encoder]
 296         if (!isLegalReplacement(newReplacement))
 297             throw new IllegalArgumentException("Illegal replacement");
 298         this.replacement = Arrays.copyOf(newReplacement, newReplacement.$replLength$);
 299 #end[encoder]
 300         implReplaceWith(this.replacement);
 301         return this;
 302     }
 303 
 304     /**
 305      * Reports a change to this $coder$'s replacement value.
 306      *
 307      * <p> The default implementation of this method does nothing.  This method
 308      * should be overridden by $coder$s that require notification of changes to
 309      * the replacement.  </p>
 310      *
 311      * @param  newReplacement    The replacement value
 312      */
 313     protected void implReplaceWith($replType$ newReplacement) {
 314     }
 315 
 316 #if[encoder]
 317 
 318     private WeakReference<CharsetDecoder> cachedDecoder = null;
 319 
 320     /**
 321      * Tells whether or not the given byte array is a legal replacement value
 322      * for this encoder.
 323      *
 324      * <p> A replacement is legal if, and only if, it is a legal sequence of
 325      * bytes in this encoder's charset; that is, it must be possible to decode
 326      * the replacement into one or more sixteen-bit Unicode characters.
 327      *
 328      * <p> The default implementation of this method is not very efficient; it
 329      * should generally be overridden to improve performance.  </p>
 330      *
 331      * @param  repl  The byte array to be tested
 332      *
 333      * @return  {@code true} if, and only if, the given byte array
 334      *          is a legal replacement value for this encoder
 335      */
 336     public boolean isLegalReplacement(byte[] repl) {
 337         WeakReference<CharsetDecoder> wr = cachedDecoder;
 338         CharsetDecoder dec = null;
 339         if ((wr == null) || ((dec = wr.get()) == null)) {
 340             dec = charset().newDecoder();
 341             dec.onMalformedInput(CodingErrorAction.REPORT);
 342             dec.onUnmappableCharacter(CodingErrorAction.REPORT);
 343             cachedDecoder = new WeakReference<CharsetDecoder>(dec);
 344         } else {
 345             dec.reset();
 346         }
 347         ByteBuffer bb = ByteBuffer.wrap(repl);
 348         CharBuffer cb = CharBuffer.allocate((int)(bb.remaining()
 349                                                   * dec.maxCharsPerByte()));
 350         CoderResult cr = dec.decode(bb, cb, true);
 351         return !cr.isError();
 352     }
 353 
 354 #end[encoder]
 355 
 356     /**
 357      * Returns this $coder$'s current action for malformed-input errors.
 358      *
 359      * @return The current malformed-input action, which is never {@code null}
 360      */
 361     public CodingErrorAction malformedInputAction() {
 362         return malformedInputAction;
 363     }
 364 
 365     /**
 366      * Changes this $coder$'s action for malformed-input errors.
 367      *
 368      * <p> This method invokes the {@link #implOnMalformedInput
 369      * implOnMalformedInput} method, passing the new action.  </p>
 370      *
 371      * @param  newAction  The new action; must not be {@code null}
 372      *
 373      * @return  This $coder$
 374      *
 375      * @throws IllegalArgumentException
 376      *         If the precondition on the parameter does not hold
 377      */
 378     public final Charset$Coder$ onMalformedInput(CodingErrorAction newAction) {
 379         if (newAction == null)
 380             throw new IllegalArgumentException("Null action");
 381         malformedInputAction = newAction;
 382         implOnMalformedInput(newAction);
 383         return this;
 384     }
 385 
 386     /**
 387      * Reports a change to this $coder$'s malformed-input action.
 388      *
 389      * <p> The default implementation of this method does nothing.  This method
 390      * should be overridden by $coder$s that require notification of changes to
 391      * the malformed-input action.  </p>
 392      *
 393      * @param  newAction  The new action
 394      */
 395     protected void implOnMalformedInput(CodingErrorAction newAction) { }
 396 
 397     /**
 398      * Returns this $coder$'s current action for unmappable-character errors.
 399      *
 400      * @return The current unmappable-character action, which is never
 401      *         {@code null}
 402      */
 403     public CodingErrorAction unmappableCharacterAction() {
 404         return unmappableCharacterAction;
 405     }
 406 
 407     /**
 408      * Changes this $coder$'s action for unmappable-character errors.
 409      *
 410      * <p> This method invokes the {@link #implOnUnmappableCharacter
 411      * implOnUnmappableCharacter} method, passing the new action.  </p>
 412      *
 413      * @param  newAction  The new action; must not be {@code null}
 414      *
 415      * @return  This $coder$
 416      *
 417      * @throws IllegalArgumentException
 418      *         If the precondition on the parameter does not hold
 419      */
 420     public final Charset$Coder$ onUnmappableCharacter(CodingErrorAction
 421                                                       newAction)
 422     {
 423         if (newAction == null)
 424             throw new IllegalArgumentException("Null action");
 425         unmappableCharacterAction = newAction;
 426         implOnUnmappableCharacter(newAction);
 427         return this;
 428     }
 429 
 430     /**
 431      * Reports a change to this $coder$'s unmappable-character action.
 432      *
 433      * <p> The default implementation of this method does nothing.  This method
 434      * should be overridden by $coder$s that require notification of changes to
 435      * the unmappable-character action.  </p>
 436      *
 437      * @param  newAction  The new action
 438      */
 439     protected void implOnUnmappableCharacter(CodingErrorAction newAction) { }
 440 
 441     /**
 442      * Returns the average number of $otype$s that will be produced for each
 443      * $itype$ of input.  This heuristic value may be used to estimate the size
 444      * of the output buffer required for a given input sequence.
 445      *
 446      * @return  The average number of $otype$s produced
 447      *          per $itype$ of input
 448      */
 449     public final float average$ItypesPerOtype$() {
 450         return average$ItypesPerOtype$;
 451     }
 452 
 453     /**
 454      * Returns the maximum number of $otype$s that will be produced for each
 455      * $itype$ of input.  This value may be used to compute the worst-case size
 456      * of the output buffer required for a given input sequence.
 457      *
 458      * @return  The maximum number of $otype$s that will be produced per
 459      *          $itype$ of input
 460      */
 461     public final float max$ItypesPerOtype$() {
 462         return max$ItypesPerOtype$;
 463     }
 464 
 465     /**
 466      * $Code$s as many $itype$s as possible from the given input buffer,
 467      * writing the results to the given output buffer.
 468      *
 469      * <p> The buffers are read from, and written to, starting at their current
 470      * positions.  At most {@link Buffer#remaining in.remaining()} $itype$s
 471      * will be read and at most {@link Buffer#remaining out.remaining()}
 472      * $otype$s will be written.  The buffers' positions will be advanced to
 473      * reflect the $itype$s read and the $otype$s written, but their marks and
 474      * limits will not be modified.
 475      *
 476      * <p> In addition to reading $itype$s from the input buffer and writing
 477      * $otype$s to the output buffer, this method returns a {@link CoderResult}
 478      * object to describe its reason for termination:
 479      *
 480      * <ul>
 481      *
 482      *   <li><p> {@link CoderResult#UNDERFLOW} indicates that as much of the
 483      *   input buffer as possible has been $code$d.  If there is no further
 484      *   input then the invoker can proceed to the next step of the
 485      *   <a href="#steps">$coding$ operation</a>.  Otherwise this method
 486      *   should be invoked again with further input.  </p></li>
 487      *
 488      *   <li><p> {@link CoderResult#OVERFLOW} indicates that there is
 489      *   insufficient space in the output buffer to $code$ any more $itype$s.
 490      *   This method should be invoked again with an output buffer that has
 491      *   more {@linkplain Buffer#remaining remaining} $otype$s. This is
 492      *   typically done by draining any $code$d $otype$s from the output
 493      *   buffer.  </p></li>
 494      *
 495      *   <li><p> A {@linkplain CoderResult#malformedForLength
 496      *   malformed-input} result indicates that a malformed-input
 497      *   error has been detected.  The malformed $itype$s begin at the input
 498      *   buffer's (possibly incremented) position; the number of malformed
 499      *   $itype$s may be determined by invoking the result object's {@link
 500      *   CoderResult#length() length} method.  This case applies only if the
 501      *   {@linkplain #onMalformedInput malformed action} of this $coder$
 502      *   is {@link CodingErrorAction#REPORT}; otherwise the malformed input
 503      *   will be ignored or replaced, as requested.  </p></li>
 504      *
 505      *   <li><p> An {@linkplain CoderResult#unmappableForLength
 506      *   unmappable-character} result indicates that an
 507      *   unmappable-character error has been detected.  The $itype$s that
 508      *   $code$ the unmappable character begin at the input buffer's (possibly
 509      *   incremented) position; the number of such $itype$s may be determined
 510      *   by invoking the result object's {@link CoderResult#length() length}
 511      *   method.  This case applies only if the {@linkplain #onUnmappableCharacter
 512      *   unmappable action} of this $coder$ is {@link
 513      *   CodingErrorAction#REPORT}; otherwise the unmappable character will be
 514      *   ignored or replaced, as requested.  </p></li>
 515      *
 516      * </ul>
 517      *
 518      * In any case, if this method is to be reinvoked in the same $coding$
 519      * operation then care should be taken to preserve any $itype$s remaining
 520      * in the input buffer so that they are available to the next invocation.
 521      *
 522      * <p> The {@code endOfInput} parameter advises this method as to whether
 523      * the invoker can provide further input beyond that contained in the given
 524      * input buffer.  If there is a possibility of providing additional input
 525      * then the invoker should pass {@code false} for this parameter; if there
 526      * is no possibility of providing further input then the invoker should
 527      * pass {@code true}.  It is not erroneous, and in fact it is quite
 528      * common, to pass {@code false} in one invocation and later discover that
 529      * no further input was actually available.  It is critical, however, that
 530      * the final invocation of this method in a sequence of invocations always
 531      * pass {@code true} so that any remaining un$code$d input will be treated
 532      * as being malformed.
 533      *
 534      * <p> This method works by invoking the {@link #$code$Loop $code$Loop}
 535      * method, interpreting its results, handling error conditions, and
 536      * reinvoking it as necessary.  </p>
 537      *
 538      *
 539      * @param  in
 540      *         The input $itype$ buffer
 541      *
 542      * @param  out
 543      *         The output $otype$ buffer
 544      *
 545      * @param  endOfInput
 546      *         {@code true} if, and only if, the invoker can provide no
 547      *         additional input $itype$s beyond those in the given buffer
 548      *
 549      * @return  A coder-result object describing the reason for termination
 550      *
 551      * @throws  IllegalStateException
 552      *          If $a$ $coding$ operation is already in progress and the previous
 553      *          step was an invocation neither of the {@link #reset reset}
 554      *          method, nor of this method with a value of {@code false} for
 555      *          the {@code endOfInput} parameter, nor of this method with a
 556      *          value of {@code true} for the {@code endOfInput} parameter
 557      *          but a return value indicating an incomplete $coding$ operation
 558      *
 559      * @throws  CoderMalfunctionError
 560      *          If an invocation of the $code$Loop method threw
 561      *          an unexpected exception
 562      */
 563     public final CoderResult $code$($Itype$Buffer in, $Otype$Buffer out,
 564                                     boolean endOfInput)
 565     {
 566         int newState = endOfInput ? ST_END : ST_CODING;
 567         if ((state != ST_RESET) && (state != ST_CODING)
 568             && !(endOfInput && (state == ST_END)))
 569             throwIllegalStateException(state, newState);
 570         state = newState;
 571 
 572         for (;;) {
 573 
 574             CoderResult cr;
 575             try {
 576                 cr = $code$Loop(in, out);
 577             } catch (BufferUnderflowException x) {
 578                 throw new CoderMalfunctionError(x);
 579             } catch (BufferOverflowException x) {
 580                 throw new CoderMalfunctionError(x);
 581             }
 582 
 583             if (cr.isOverflow())
 584                 return cr;
 585 
 586             if (cr.isUnderflow()) {
 587                 if (endOfInput && in.hasRemaining()) {
 588                     cr = CoderResult.malformedForLength(in.remaining());
 589                     // Fall through to malformed-input case
 590                 } else {
 591                     return cr;
 592                 }
 593             }
 594 
 595             CodingErrorAction action = null;
 596             if (cr.isMalformed())
 597                 action = malformedInputAction;
 598             else if (cr.isUnmappable())
 599                 action = unmappableCharacterAction;
 600             else
 601                 assert false : cr.toString();
 602 
 603             if (action == CodingErrorAction.REPORT)
 604                 return cr;
 605 
 606             if (action == CodingErrorAction.REPLACE) {
 607                 if (out.remaining() < replacement.$replLength$)
 608                     return CoderResult.OVERFLOW;
 609                 out.put(replacement);
 610             }
 611 
 612             if ((action == CodingErrorAction.IGNORE)
 613                 || (action == CodingErrorAction.REPLACE)) {
 614                 // Skip erroneous input either way
 615                 in.position(in.position() + cr.length());
 616                 continue;
 617             }
 618 
 619             assert false;
 620         }
 621 
 622     }
 623 
 624     /**
 625      * Flushes this $coder$.
 626      *
 627      * <p> Some $coder$s maintain internal state and may need to write some
 628      * final $otype$s to the output buffer once the overall input sequence has
 629      * been read.
 630      *
 631      * <p> Any additional output is written to the output buffer beginning at
 632      * its current position.  At most {@link Buffer#remaining out.remaining()}
 633      * $otype$s will be written.  The buffer's position will be advanced
 634      * appropriately, but its mark and limit will not be modified.
 635      *
 636      * <p> If this method completes successfully then it returns {@link
 637      * CoderResult#UNDERFLOW}.  If there is insufficient room in the output
 638      * buffer then it returns {@link CoderResult#OVERFLOW}.  If this happens
 639      * then this method must be invoked again, with an output buffer that has
 640      * more room, in order to complete the current <a href="#steps">$coding$
 641      * operation</a>.
 642      *
 643      * <p> If this $coder$ has already been flushed then invoking this method
 644      * has no effect.
 645      *
 646      * <p> This method invokes the {@link #implFlush implFlush} method to
 647      * perform the actual flushing operation.  </p>
 648      *
 649      * @param  out
 650      *         The output $otype$ buffer
 651      *
 652      * @return  A coder-result object, either {@link CoderResult#UNDERFLOW} or
 653      *          {@link CoderResult#OVERFLOW}
 654      *
 655      * @throws  IllegalStateException
 656      *          If the previous step of the current $coding$ operation was an
 657      *          invocation neither of the {@link #flush flush} method nor of
 658      *          the three-argument {@link
 659      *          #$code$($Itype$Buffer,$Otype$Buffer,boolean) $code$} method
 660      *          with a value of {@code true} for the {@code endOfInput}
 661      *          parameter
 662      */
 663     public final CoderResult flush($Otype$Buffer out) {
 664         if (state == ST_END) {
 665             CoderResult cr = implFlush(out);
 666             if (cr.isUnderflow())
 667                 state = ST_FLUSHED;
 668             return cr;
 669         }
 670 
 671         if (state != ST_FLUSHED)
 672             throwIllegalStateException(state, ST_FLUSHED);
 673 
 674         return CoderResult.UNDERFLOW; // Already flushed
 675     }
 676 
 677     /**
 678      * Flushes this $coder$.
 679      *
 680      * <p> The default implementation of this method does nothing, and always
 681      * returns {@link CoderResult#UNDERFLOW}.  This method should be overridden
 682      * by $coder$s that may need to write final $otype$s to the output buffer
 683      * once the entire input sequence has been read. </p>
 684      *
 685      * @param  out
 686      *         The output $otype$ buffer
 687      *
 688      * @return  A coder-result object, either {@link CoderResult#UNDERFLOW} or
 689      *          {@link CoderResult#OVERFLOW}
 690      */
 691     protected CoderResult implFlush($Otype$Buffer out) {
 692         return CoderResult.UNDERFLOW;
 693     }
 694 
 695     /**
 696      * Resets this $coder$, clearing any internal state.
 697      *
 698      * <p> This method resets charset-independent state and also invokes the
 699      * {@link #implReset() implReset} method in order to perform any
 700      * charset-specific reset actions.  </p>
 701      *
 702      * @return  This $coder$
 703      *
 704      */
 705     public final Charset$Coder$ reset() {
 706         implReset();
 707         state = ST_RESET;
 708         return this;
 709     }
 710 
 711     /**
 712      * Resets this $coder$, clearing any charset-specific internal state.
 713      *
 714      * <p> The default implementation of this method does nothing.  This method
 715      * should be overridden by $coder$s that maintain internal state.  </p>
 716      */
 717     protected void implReset() { }
 718 
 719     /**
 720      * $Code$s one or more $itype$s into one or more $otype$s.
 721      *
 722      * <p> This method encapsulates the basic $coding$ loop, $coding$ as many
 723      * $itype$s as possible until it either runs out of input, runs out of room
 724      * in the output buffer, or encounters $a$ $coding$ error.  This method is
 725      * invoked by the {@link #$code$ $code$} method, which handles result
 726      * interpretation and error recovery.
 727      *
 728      * <p> The buffers are read from, and written to, starting at their current
 729      * positions.  At most {@link Buffer#remaining in.remaining()} $itype$s
 730      * will be read, and at most {@link Buffer#remaining out.remaining()}
 731      * $otype$s will be written.  The buffers' positions will be advanced to
 732      * reflect the $itype$s read and the $otype$s written, but their marks and
 733      * limits will not be modified.
 734      *
 735      * <p> This method returns a {@link CoderResult} object to describe its
 736      * reason for termination, in the same manner as the {@link #$code$ $code$}
 737      * method.  Most implementations of this method will handle $coding$ errors
 738      * by returning an appropriate result object for interpretation by the
 739      * {@link #$code$ $code$} method.  An optimized implementation may instead
 740      * examine the relevant error action and implement that action itself.
 741      *
 742      * <p> An implementation of this method may perform arbitrary lookahead by
 743      * returning {@link CoderResult#UNDERFLOW} until it receives sufficient
 744      * input.  </p>
 745      *
 746      * @param  in
 747      *         The input $itype$ buffer
 748      *
 749      * @param  out
 750      *         The output $otype$ buffer
 751      *
 752      * @return  A coder-result object describing the reason for termination
 753      */
 754     protected abstract CoderResult $code$Loop($Itype$Buffer in,
 755                                               $Otype$Buffer out);
 756 
 757     /**
 758      * Convenience method that $code$s the remaining content of a single input
 759      * $itype$ buffer into a newly-allocated $otype$ buffer.
 760      *
 761      * <p> This method implements an entire <a href="#steps">$coding$
 762      * operation</a>; that is, it resets this $coder$, then it $code$s the
 763      * $itype$s in the given $itype$ buffer, and finally it flushes this
 764      * $coder$.  This method should therefore not be invoked if $a$ $coding$
 765      * operation is already in progress.  </p>
 766      *
 767      * @param  in
 768      *         The input $itype$ buffer
 769      *
 770      * @return A newly-allocated $otype$ buffer containing the result of the
 771      *         $coding$ operation.  The buffer's position will be zero and its
 772      *         limit will follow the last $otype$ written.
 773      *
 774      * @throws  IllegalStateException
 775      *          If $a$ $coding$ operation is already in progress
 776      *
 777      * @throws  MalformedInputException
 778      *          If the $itype$ sequence starting at the input buffer's current
 779      *          position is $notLegal$ and the current malformed-input action
 780      *          is {@link CodingErrorAction#REPORT}
 781      *
 782      * @throws  UnmappableCharacterException
 783      *          If the $itype$ sequence starting at the input buffer's current
 784      *          position cannot be mapped to an equivalent $otype$ sequence and
 785      *          the current unmappable-character action is {@link
 786      *          CodingErrorAction#REPORT}
 787      */
 788     public final $Otype$Buffer $code$($Itype$Buffer in)
 789         throws CharacterCodingException
 790     {
 791         int n = (int)(in.remaining() * average$ItypesPerOtype$());
 792         $Otype$Buffer out = $Otype$Buffer.allocate(n);
 793 
 794         if ((n == 0) && (in.remaining() == 0))
 795             return out;
 796         reset();
 797         for (;;) {
 798             CoderResult cr = in.hasRemaining() ?
 799                 $code$(in, out, true) : CoderResult.UNDERFLOW;
 800             if (cr.isUnderflow())
 801                 cr = flush(out);
 802 
 803             if (cr.isUnderflow())
 804                 break;
 805             if (cr.isOverflow()) {
 806                 n = 2*n + 1;    // Ensure progress; n might be 0!
 807                 $Otype$Buffer o = $Otype$Buffer.allocate(n);
 808                 out.flip();
 809                 o.put(out);
 810                 out = o;
 811                 continue;
 812             }
 813             cr.throwException();
 814         }
 815         out.flip();
 816         return out;
 817     }
 818 
 819 #if[decoder]
 820 
 821     /**
 822      * Tells whether or not this decoder implements an auto-detecting charset.
 823      *
 824      * <p> The default implementation of this method always returns
 825      * {@code false}; it should be overridden by auto-detecting decoders to
 826      * return {@code true}.  </p>
 827      *
 828      * @return  {@code true} if, and only if, this decoder implements an
 829      *          auto-detecting charset
 830      */
 831     public boolean isAutoDetecting() {
 832         return false;
 833     }
 834 
 835     /**
 836      * Tells whether or not this decoder has yet detected a
 837      * charset&nbsp;&nbsp;<i>(optional operation)</i>.
 838      *
 839      * <p> If this decoder implements an auto-detecting charset then at a
 840      * single point during a decoding operation this method may start returning
 841      * {@code true} to indicate that a specific charset has been detected in
 842      * the input byte sequence.  Once this occurs, the {@link #detectedCharset
 843      * detectedCharset} method may be invoked to retrieve the detected charset.
 844      *
 845      * <p> That this method returns {@code false} does not imply that no bytes
 846      * have yet been decoded.  Some auto-detecting decoders are capable of
 847      * decoding some, or even all, of an input byte sequence without fixing on
 848      * a particular charset.
 849      *
 850      * <p> The default implementation of this method always throws an {@link
 851      * UnsupportedOperationException}; it should be overridden by
 852      * auto-detecting decoders to return {@code true} once the input charset
 853      * has been determined.  </p>
 854      *
 855      * @return  {@code true} if, and only if, this decoder has detected a
 856      *          specific charset
 857      *
 858      * @throws  UnsupportedOperationException
 859      *          If this decoder does not implement an auto-detecting charset
 860      */
 861     public boolean isCharsetDetected() {
 862         throw new UnsupportedOperationException();
 863     }
 864 
 865     /**
 866      * Retrieves the charset that was detected by this
 867      * decoder&nbsp;&nbsp;<i>(optional operation)</i>.
 868      *
 869      * <p> If this decoder implements an auto-detecting charset then this
 870      * method returns the actual charset once it has been detected.  After that
 871      * point, this method returns the same value for the duration of the
 872      * current decoding operation.  If not enough input bytes have yet been
 873      * read to determine the actual charset then this method throws an {@link
 874      * IllegalStateException}.
 875      *
 876      * <p> The default implementation of this method always throws an {@link
 877      * UnsupportedOperationException}; it should be overridden by
 878      * auto-detecting decoders to return the appropriate value.  </p>
 879      *
 880      * @return  The charset detected by this auto-detecting decoder,
 881      *          or {@code null} if the charset has not yet been determined
 882      *
 883      * @throws  IllegalStateException
 884      *          If insufficient bytes have been read to determine a charset
 885      *
 886      * @throws  UnsupportedOperationException
 887      *          If this decoder does not implement an auto-detecting charset
 888      */
 889     public Charset detectedCharset() {
 890         throw new UnsupportedOperationException();
 891     }
 892 
 893 #end[decoder]
 894 
 895 #if[encoder]
 896 
 897     private boolean canEncode(CharBuffer cb) {
 898         if (state == ST_FLUSHED)
 899             reset();
 900         else if (state != ST_RESET)
 901             throwIllegalStateException(state, ST_CODING);
 902         CodingErrorAction ma = malformedInputAction();
 903         CodingErrorAction ua = unmappableCharacterAction();
 904         try {
 905             onMalformedInput(CodingErrorAction.REPORT);
 906             onUnmappableCharacter(CodingErrorAction.REPORT);
 907             encode(cb);
 908         } catch (CharacterCodingException x) {
 909             return false;
 910         } finally {
 911             onMalformedInput(ma);
 912             onUnmappableCharacter(ua);
 913             reset();
 914         }
 915         return true;
 916     }
 917 
 918     /**
 919      * Tells whether or not this encoder can encode the given character.
 920      *
 921      * <p> This method returns {@code false} if the given character is a
 922      * surrogate character; such characters can be interpreted only when they
 923      * are members of a pair consisting of a high surrogate followed by a low
 924      * surrogate.  The {@link #canEncode(java.lang.CharSequence)
 925      * canEncode(CharSequence)} method may be used to test whether or not a
 926      * character sequence can be encoded.
 927      *
 928      * <p> This method may modify this encoder's state; it should therefore not
 929      * be invoked if an <a href="#steps">encoding operation</a> is already in
 930      * progress.
 931      *
 932      * <p> The default implementation of this method is not very efficient; it
 933      * should generally be overridden to improve performance.  </p>
 934      *
 935      * @param   c
 936      *          The given character
 937      *
 938      * @return  {@code true} if, and only if, this encoder can encode
 939      *          the given character
 940      *
 941      * @throws  IllegalStateException
 942      *          If $a$ $coding$ operation is already in progress
 943      */
 944     public boolean canEncode(char c) {
 945         CharBuffer cb = CharBuffer.allocate(1);
 946         cb.put(c);
 947         cb.flip();
 948         return canEncode(cb);
 949     }
 950 
 951     /**
 952      * Tells whether or not this encoder can encode the given character
 953      * sequence.
 954      *
 955      * <p> If this method returns {@code false} for a particular character
 956      * sequence then more information about why the sequence cannot be encoded
 957      * may be obtained by performing a full <a href="#steps">encoding
 958      * operation</a>.
 959      *
 960      * <p> This method may modify this encoder's state; it should therefore not
 961      * be invoked if an encoding operation is already in progress.
 962      *
 963      * <p> The default implementation of this method is not very efficient; it
 964      * should generally be overridden to improve performance.  </p>
 965      *
 966      * @param   cs
 967      *          The given character sequence
 968      *
 969      * @return  {@code true} if, and only if, this encoder can encode
 970      *          the given character without throwing any exceptions and without
 971      *          performing any replacements
 972      *
 973      * @throws  IllegalStateException
 974      *          If $a$ $coding$ operation is already in progress
 975      */
 976     public boolean canEncode(CharSequence cs) {
 977         CharBuffer cb;
 978         if (cs instanceof CharBuffer)
 979             cb = ((CharBuffer)cs).duplicate();
 980         else
 981             cb = CharBuffer.wrap(cs.toString());
 982         return canEncode(cb);
 983     }
 984 
 985 #end[encoder]
 986 
 987 
 988     private void throwIllegalStateException(int from, int to) {
 989         throw new IllegalStateException("Current state = " + stateNames[from]
 990                                         + ", new state = " + stateNames[to]);
 991     }
 992 
 993 }
--- EOF ---