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