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