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