Source code
Description: source: package: org.apache.commons.codec.binary, class: BaseNCodec

    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.codec.binary;
    019
    020import java.math.BigInteger;
    021import java.util.ArrayList;
    022import java.util.Arrays;
    023import java.util.Objects;
    024import java.util.function.Supplier;
    025
    026import org.apache.commons.codec.BinaryDecoder;
    027import org.apache.commons.codec.BinaryEncoder;
    028import org.apache.commons.codec.CodecPolicy;
    029import org.apache.commons.codec.DecoderException;
    030import org.apache.commons.codec.EncoderException;
    031
    032/**
    033 * Abstract superclass for Base-N encoders and decoders.
    034 *
    035 * <p>
    036 * This class is thread-safe.
    037 * </p>
    038 * <p>
    039 * You can set the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a valid encoding. These can be bits that are
    040 * unused from the final character or entire characters. The default mode is lenient decoding.
    041 * </p>
    042 * <ul>
    043 * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.</li>
    044 * <li>Strict: The decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a valid encoding. Any unused bits from the final
    045 * character must be zero. Impossible counts of entire final characters are not allowed.</li>
    046 * </ul>
    047 * <p>
    048 * When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches the original, i.e. no changes occur on
    049 * the final character. This requires that the input bytes use the same padding and alphabet as the encoder.
    050 * </p>
    051 */
    052public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder {
    053
    054    /**
    055     * Builds {@link Base64} instances.
    056     *
    057     * @param <T> The codec type to build.
    058     * @param <B> The codec builder subtype.
    059     * @since 1.17.0
    060     */
    061    public abstract static class AbstractBuilder<T, B extends AbstractBuilder<T, B>> implements Supplier<T> {
    062
    063        /**
    064         * Clones the given array or returns a default array if the array is null.
    065         *
    066         * @param array        The array to test and clone if not null.
    067         * @param defaultArray The default array to return if the array is null.
    068         * @return A clone of the array or the default array if the array is null.
    069         */
    070        static byte[] clone(final byte[] array, final byte[] defaultArray) {
    071            return array != null ? array.clone() : defaultArray;
    072        }
    073
    074        private int unencodedBlockSize;
    075        private int encodedBlockSize;
    076        private CodecPolicy decodingPolicy = DECODING_POLICY_DEFAULT;
    077        private int lineLength;
    078        private byte[] lineSeparator = CHUNK_SEPARATOR;
    079        private final byte[] defaultEncodeTable;
    080        private byte[] encodeTable;
    081        private byte[] decodeTable;
    082
    083        /** Padding byte. */
    084        private byte padding = PAD_DEFAULT;
    085
    086        AbstractBuilder(final byte[] defaultEncodeTable) {
    087            this.defaultEncodeTable = defaultEncodeTable;
    088            this.encodeTable = defaultEncodeTable;
    089        }
    090
    091        /**
    092         * Returns this instance typed as the subclass type {@code B}.
    093         * <p>
    094         * This is the same as the expression:
    095         * </p>
    096         *
    097         * <pre>
    098         * (B) this
    099         * </pre>
    100         *
    101         * @return {@code this} instance typed as the subclass type {@code B}.
    102         */
    103        @SuppressWarnings("unchecked")
    104        B asThis() {
    105            return (B) this;
    106        }
    107
    108        byte[] getDecodeTable() {
    109            return decodeTable;
    110        }
    111
    112        CodecPolicy getDecodingPolicy() {
    113            return decodingPolicy;
    114        }
    115
    116        int getEncodedBlockSize() {
    117            return encodedBlockSize;
    118        }
    119
    120        byte[] getEncodeTable() {
    121            return encodeTable;
    122        }
    123
    124        int getLineLength() {
    125            return lineLength;
    126        }
    127
    128        byte[] getLineSeparator() {
    129            return lineSeparator;
    130        }
    131
    132        byte getPadding() {
    133            return padding;
    134        }
    135
    136        int getUnencodedBlockSize() {
    137            return unencodedBlockSize;
    138        }
    139
    140        /**
    141         * Sets the decode table.
    142         *
    143         * @param decodeTable The decode table.
    144         * @return {@code this} instance.
    145         * @since 1.20.0
    146         */
    147        public B setDecodeTable(final byte[] decodeTable) {
    148            this.decodeTable = clone(decodeTable, null);
    149            return asThis();
    150        }
    151
    152        /**
    153         * Sets the decode table.
    154         *
    155         * @param decodeTable The decode table, null resets to the default.
    156         * @return {@code this} instance.
    157         */
    158        B setDecodeTableRaw(final byte[] decodeTable) {
    159            this.decodeTable = decodeTable;
    160            return asThis();
    161        }
    162
    163        /**
    164         * Sets the decoding policy.
    165         *
    166         * @param decodingPolicy The decoding policy, null resets to the default.
    167         * @return {@code this} instance.
    168         */
    169        public B setDecodingPolicy(final CodecPolicy decodingPolicy) {
    170            this.decodingPolicy = decodingPolicy != null ? decodingPolicy : DECODING_POLICY_DEFAULT;
    171            return asThis();
    172        }
    173
    174        /**
    175         * Sets the encoded block size, subclasses normally set this on construction.
    176         *
    177         * @param encodedBlockSize The encoded block size, subclasses normally set this on construction.
    178         * @return {@code this} instance.
    179         */
    180        B setEncodedBlockSize(final int encodedBlockSize) {
    181            this.encodedBlockSize = gte0(encodedBlockSize);
    182            return asThis();
    183        }
    184
    185        /**
    186         * Sets the encode table.
    187         *
    188         * @param encodeTable The encode table, null resets to the default.
    189         * @return {@code this} instance.
    190         */
    191        public B setEncodeTable(final byte... encodeTable) {
    192            this.encodeTable = clone(encodeTable, defaultEncodeTable);
    193            return asThis();
    194        }
    195
    196        /**
    197         * Sets the encode table.
    198         *
    199         * @param encodeTable The encode table, null resets to the default.
    200         * @return {@code this} instance.
    201         */
    202        B setEncodeTableRaw(final byte... encodeTable) {
    203            this.encodeTable = encodeTable != null ? encodeTable : defaultEncodeTable;
    204            return asThis();
    205        }
    206
    207        /**
    208         * Sets the line length.
    209         *
    210         * @param lineLength The line length, less than 0 resets to the default.
    211         * @return {@code this} instance.
    212         */
    213        public B setLineLength(final int lineLength) {
    214            this.lineLength = Math.max(0, lineLength);
    215            return asThis();
    216        }
    217
    218        /**
    219         * Sets the line separator.
    220         *
    221         * @param lineSeparator The line separator, null resets to the default.
    222         * @return {@code this} instance.
    223         */
    224        public B setLineSeparator(final byte... lineSeparator) {
    225            this.lineSeparator = clone(lineSeparator , CHUNK_SEPARATOR);
    226            return asThis();
    227        }
    228
    229        /**
    230         * Sets the padding byte.
    231         *
    232         * @param padding The padding byte.
    233         * @return {@code this} instance.
    234         */
    235        public B setPadding(final byte padding) {
    236            this.padding = padding;
    237            return asThis();
    238        }
    239
    240        /**
    241         * Sets the unencoded block size, subclasses normally set this on construction.
    242         *
    243         * @param unencodedBlockSize The unencoded block size, subclasses normally set this on construction.
    244         * @return {@code this} instance.
    245         */
    246        B setUnencodedBlockSize(final int unencodedBlockSize) {
    247            this.unencodedBlockSize = gte0(unencodedBlockSize);
    248            return asThis();
    249        }
    250    }
    251
    252    /**
    253     * Holds thread context so classes can be thread-safe.
    254     *
    255     * This class is not itself thread-safe; each thread must allocate its own copy.
    256     */
    257    static class Context {
    258
    259        /**
    260         * Placeholder for the bytes we're dealing with for our based logic. Bitwise operations store and extract the encoding or decoding from this variable.
    261         */
    262        int ibitWorkArea;
    263
    264        /**
    265         * Placeholder for the bytes we're dealing with for our based logic. Bitwise operations store and extract the encoding or decoding from this variable.
    266         */
    267        long lbitWorkArea;
    268
    269        /**
    270         * Buffer for streaming.
    271         */
    272        byte[] buffer;
    273
    274        /**
    275         * Position where next character should be written in the buffer.
    276         */
    277        int pos;
    278
    279        /**
    280         * Position where next character should be read from the buffer.
    281         */
    282        int readPos;
    283
    284        /**
    285         * Boolean flag to indicate the EOF has been reached. Once EOF has been reached, this object becomes useless, and must be thrown away.
    286         */
    287        boolean eof;
    288
    289        /**
    290         * Variable tracks how many characters have been written to the current line. Only used when encoding. We use it to make sure each encoded line never
    291         * goes beyond lineLength (if lineLength &gt; 0).
    292         */
    293        int currentLinePos;
    294
    295        /**
    296         * Writes to the buffer only occur after every 3/5 reads when encoding, and every 4/8 reads when decoding. This variable helps track that.
    297         */
    298        int modulus;
    299
    300        /**
    301         * Returns a String useful for debugging (especially within a debugger.)
    302         *
    303         * @return A String useful for debugging.
    304         */
    305        @Override
    306        public String toString() {
    307            return String.format("%s[buffer=%s, currentLinePos=%s, eof=%s, ibitWorkArea=%s, lbitWorkArea=%s, " + "modulus=%s, pos=%s, readPos=%s]",
    308                    this.getClass().getSimpleName(), Arrays.toString(buffer), currentLinePos, eof, ibitWorkArea, lbitWorkArea, modulus, pos, readPos);
    309        }
    310    }
    311
    312    /**
    313     * End-of-file marker.
    314     *
    315     * @since 1.7
    316     */
    317    static final int EOF = -1;
    318
    319    /**
    320     * MIME chunk size per RFC 2045 section 6.8.
    321     *
    322     * <p>
    323     * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.
    324     * </p>
    325     *
    326     * @see <a href="https://www.ietf.org/rfc/rfc2045">RFC 2045 section 6.8</a>
    327     */
    328    public static final int MIME_CHUNK_SIZE = 76;
    329
    330    /**
    331     * PEM chunk size per RFC 1421 section 4.3.2.4.
    332     *
    333     * <p>
    334     * The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any equal signs.
    335     * </p>
    336     *
    337     * @see <a href="https://tools.ietf.org/html/rfc1421">RFC 1421 section 4.3.2.4</a>
    338     */
    339    public static final int PEM_CHUNK_SIZE = 64;
    340    private static final int DEFAULT_BUFFER_RESIZE_FACTOR = 2;
    341
    342    /**
    343     * Defines the default buffer size - currently {@value} - must be large enough for at least one encoded block+separator
    344     */
    345    private static final int DEFAULT_BUFFER_SIZE = 8192;
    346
    347    /**
    348     * The maximum size buffer to allocate.
    349     *
    350     * <p>
    351     * This is set to the same size used in the JDK {@link ArrayList}:
    352     * </p>
    353     * <blockquote> Some VMs reserve some header words in an array. Attempts to allocate larger arrays may result in OutOfMemoryError: Requested array size
    354     * exceeds VM limit. </blockquote>
    355     */
    356    private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8;
    357
    358    /** Mask used to extract 8 bits, used in decoding bytes */
    359    protected static final int MASK_8BITS = 0xff;
    360
    361    /**
    362     * Byte used to pad output.
    363     */
    364    protected static final byte PAD_DEFAULT = '='; // Allow static access to default
    365
    366    /**
    367     * The default decoding policy.
    368     *
    369     * @since 1.15
    370     */
    371    protected static final CodecPolicy DECODING_POLICY_DEFAULT = CodecPolicy.LENIENT;
    372
    373    /**
    374     * Chunk separator per RFC 2045 section 2.1.
    375     *
    376     * @see <a href="https://www.ietf.org/rfc/rfc2045">RFC 2045 section 2.1</a>
    377     */
    378    static final byte[] CHUNK_SEPARATOR = { '\r', '\n' };
    379
    380    /**
    381     * The empty byte array.
    382     */
    383    static final byte[] EMPTY_BYTE_ARRAY = {};
    384
    385    /**
    386     * Create a positive capacity at least as large the minimum required capacity. If the minimum capacity is negative then this throws an OutOfMemoryError as
    387     * no array can be allocated.
    388     *
    389     * @param minCapacity The minimum capacity.
    390     * @return The capacity.
    391     * @throws OutOfMemoryError if the {@code minCapacity} is negative.
    392     */
    393    private static int createPositiveCapacity(final int minCapacity) {
    394        if (minCapacity < 0) {
    395            // overflow
    396            throw new OutOfMemoryError("Unable to allocate array size: " + (minCapacity & 0xffffffffL));
    397        }
    398        // This is called when we require buffer expansion to a very big array.
    399        // Use the conservative maximum buffer size if possible, otherwise the biggest required.
    400        //
    401        // Note: In this situation JDK 1.8 java.util.ArrayList returns Integer.MAX_VALUE.
    402        // This excludes some VMs that can exceed MAX_BUFFER_SIZE but not allocate a full
    403        // Integer.MAX_VALUE length array.
    404        // The result is that we may have to allocate an array of this size more than once if
    405        // the capacity must be expanded again.
    406        return Math.max(minCapacity, MAX_BUFFER_SIZE);
    407    }
    408
    409    /**
    410     * Gets a copy of the chunk separator per RFC 2045 section 2.1.
    411     *
    412     * @return The chunk separator.
    413     * @see <a href="https://www.ietf.org/rfc/rfc2045">RFC 2045 section 2.1</a>
    414     * @since 1.15
    415     */
    416    public static byte[] getChunkSeparator() {
    417        return CHUNK_SEPARATOR.clone();
    418    }
    419
    420    private static int gte0(final int value) {
    421        if (value < 0) {
    422            throw new IllegalArgumentException("value must be greater than or equal to 0.");
    423        }
    424        return value;
    425    }
    426
    427    /**
    428     * Checks if a byte value is whitespace or not.
    429     *
    430     * @param byteToCheck The byte to check.
    431     * @return true if byte is whitespace, false otherwise.
    432     * @see Character#isWhitespace(int)
    433     * @deprecated Use {@link Character#isWhitespace(int)}.
    434     */
    435    @Deprecated
    436    protected static boolean isWhiteSpace(final byte byteToCheck) {
    437        return Character.isWhitespace(byteToCheck);
    438    }
    439
    440    /**
    441     * Increases our buffer by the {@link #DEFAULT_BUFFER_RESIZE_FACTOR}.
    442     *
    443     * @param context     The context to be used.
    444     * @param minCapacity The minimum required capacity.
    445     * @return The resized byte[] buffer.
    446     * @throws OutOfMemoryError if the {@code minCapacity} is negative.
    447     */
    448    private static byte[] resizeBuffer(final Context context, final int minCapacity) {
    449        // Overflow-conscious code treats the min and new capacity as unsigned.
    450        final int oldCapacity = context.buffer.length;
    451        int newCapacity = oldCapacity * DEFAULT_BUFFER_RESIZE_FACTOR;
    452        if (Integer.compareUnsigned(newCapacity, minCapacity) < 0) {
    453            newCapacity = minCapacity;
    454        }
    455        if (Integer.compareUnsigned(newCapacity, MAX_BUFFER_SIZE) > 0) {
    456            newCapacity = createPositiveCapacity(minCapacity);
    457        }
    458        final byte[] b = Arrays.copyOf(context.buffer, newCapacity);
    459        context.buffer = b;
    460        return b;
    461    }
    462
    463    /**
    464     * Returns a byte-array representation of a {@code BigInteger} without sign bit.
    465     * <p>
    466     * The value {@link BigInteger#ZERO} maps to an empty array.
    467     * </p>
    468     *
    469     * @param bigInt {@code BigInteger} to be converted.
    470     * @return A byte array representation of the BigInteger parameter.
    471     */
    472    static byte[] toUnsignedBytes(final BigInteger value) {
    473        byte[] unsigned = value.equals(BigInteger.ZERO) ? EMPTY_BYTE_ARRAY : value.toByteArray();
    474        if (unsigned.length > 0 && unsigned[0] == 0) {
    475            final byte[] tmp = new byte[unsigned.length - 1];
    476            System.arraycopy(unsigned, 1, tmp, 0, tmp.length);
    477            unsigned = tmp;
    478        }
    479        return unsigned;
    480    }
    481
    482    /**
    483     * Deprecated: Will be removed in 2.0.
    484     * <p>
    485     * Instance variable just in case it needs to vary later
    486     * </p>
    487     *
    488     * @deprecated Use {@link #pad}. Will be removed in 2.0.
    489     */
    490    @Deprecated
    491    protected final byte PAD = PAD_DEFAULT;
    492
    493    /** Pad byte. Instance variable just in case it needs to vary later. */
    494    protected final byte pad;
    495
    496    /** Number of bytes in each full block of unencoded data, for example 4 for Base64 and 5 for Base32 */
    497    private final int unencodedBlockSize;
    498
    499    /** Number of bytes in each full block of encoded data, for example 3 for Base64 and 8 for Base32 */
    500    private final int encodedBlockSize;
    501
    502    /**
    503     * Chunksize for encoding. Not used when decoding. A value of zero or less implies no chunking of the encoded data. Rounded down to the nearest multiple of
    504     * encodedBlockSize.
    505     */
    506    protected final int lineLength;
    507
    508    /**
    509     * Size of chunk separator. Not used unless {@link #lineLength} &gt; 0.
    510     */
    511    private final int chunkSeparatorLength;
    512
    513    /**
    514     * Defines the decoding behavior when the input bytes contain leftover trailing bits that cannot be created by a valid encoding. These can be bits that are
    515     * unused from the final character or entire characters. The default mode is lenient decoding. Set this to {@code true} to enable strict decoding.
    516     * <ul>
    517     * <li>Lenient: Any trailing bits are composed into 8-bit bytes where possible. The remainder are discarded.</li>
    518     * <li>Strict: The decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a valid encoding. Any unused bits from the final
    519     * character must be zero. Impossible counts of entire final characters are not allowed.</li>
    520     * </ul>
    521     * <p>
    522     * When strict decoding is enabled it is expected that the decoded bytes will be re-encoded to a byte array that matches the original, i.e. no changes occur
    523     * on the final character. This requires that the input bytes use the same padding and alphabet as the encoder.
    524     * </p>
    525     */
    526    private final CodecPolicy decodingPolicy;
    527
    528    /**
    529     * Decode table to use.
    530     */
    531    final byte[] decodeTable;
    532
    533    /**
    534     * Encode table.
    535     */
    536    final byte[] encodeTable;
    537
    538    /**
    539     * Constructs a new instance for a subclass.
    540     *
    541     * @param builder How to build this portion of the instance.
    542     * @since 1.20.0
    543     */
    544    protected BaseNCodec(final AbstractBuilder<?, ?> builder) {
    545        this.unencodedBlockSize = gte0(builder.unencodedBlockSize);
    546        this.encodedBlockSize = gte0(builder.encodedBlockSize);
    547        final boolean useChunking = builder.lineLength > 0 && builder.lineSeparator.length > 0;
    548        this.lineLength = useChunking ? builder.lineLength / builder.encodedBlockSize * builder.encodedBlockSize : 0;
    549        this.chunkSeparatorLength = builder.lineSeparator.length;
    550        this.pad = builder.padding;
    551        this.decodingPolicy = Objects.requireNonNull(builder.decodingPolicy, "codecPolicy");
    552        this.encodeTable = Objects.requireNonNull(builder.getEncodeTable(), "builder.getEncodeTable()");
    553        this.decodeTable = builder.getDecodeTable();
    554    }
    555
    556    /**
    557     * Constructs a new instance.
    558     * <p>
    559     * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. If {@code chunkSeparatorLength} is zero, then chunking is
    560     * disabled.
    561     * </p>
    562     *
    563     * @param unencodedBlockSize   The size of an unencoded block (for example Base64 = 3).
    564     * @param encodedBlockSize     The size of an encoded block (for example Base64 = 4).
    565     * @param lineLength           if &gt; 0, use chunking with a length {@code lineLength}.
    566     * @param chunkSeparatorLength The chunk separator length, if relevant.
    567     * @deprecated Use {@link BaseNCodec#BaseNCodec(AbstractBuilder)}.
    568     */
    569    @Deprecated
    570    protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength) {
    571        this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, PAD_DEFAULT);
    572    }
    573
    574    /**
    575     * Constructs a new instance.
    576     * <p>
    577     * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. If {@code chunkSeparatorLength} is zero, then chunking is
    578     * disabled.
    579     * </p>
    580     *
    581     * @param unencodedBlockSize   The size of an unencoded block (for example Base64 = 3).
    582     * @param encodedBlockSize     The size of an encoded block (for example Base64 = 4).
    583     * @param lineLength           if &gt; 0, use chunking with a length {@code lineLength}.
    584     * @param chunkSeparatorLength The chunk separator length, if relevant.
    585     * @param pad                  byte used as padding byte.
    586     * @deprecated Use {@link BaseNCodec#BaseNCodec(AbstractBuilder)}.
    587     */
    588    @Deprecated
    589    protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength, final byte pad) {
    590        this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, pad, DECODING_POLICY_DEFAULT);
    591    }
    592
    593    /**
    594     * Constructs a new instance.
    595     * <p>
    596     * Note {@code lineLength} is rounded down to the nearest multiple of the encoded block size. If {@code chunkSeparatorLength} is zero, then chunking is
    597     * disabled.
    598     * </p>
    599     *
    600     * @param unencodedBlockSize   The size of an unencoded block (for example Base64 = 3).
    601     * @param encodedBlockSize     The size of an encoded block (for example Base64 = 4).
    602     * @param lineLength           if &gt; 0, use chunking with a length {@code lineLength}.
    603     * @param chunkSeparatorLength The chunk separator length, if relevant.
    604     * @param pad                  byte used as padding byte.
    605     * @param decodingPolicy       Decoding policy.
    606     * @since 1.15
    607     * @deprecated Use {@link BaseNCodec#BaseNCodec(AbstractBuilder)}.
    608     */
    609    @Deprecated
    610    protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength, final byte pad,
    611            final CodecPolicy decodingPolicy) {
    612        this.unencodedBlockSize = unencodedBlockSize;
    613        this.encodedBlockSize = encodedBlockSize;
    614        final boolean useChunking = lineLength > 0 && chunkSeparatorLength > 0;
    615        this.lineLength = useChunking ? lineLength / encodedBlockSize * encodedBlockSize : 0;
    616        this.chunkSeparatorLength = chunkSeparatorLength;
    617        this.pad = pad;
    618        this.decodingPolicy = Objects.requireNonNull(decodingPolicy, "codecPolicy");
    619        this.encodeTable = null;
    620        this.decodeTable = null;
    621    }
    622
    623    /**
    624     * Returns the amount of buffered data available for reading.
    625     *
    626     * @param context The context to be used.
    627     * @return The amount of buffered data available for reading.
    628     */
    629    int available(final Context context) { // package protected for access from I/O streams
    630        return hasData(context) ? context.pos - context.readPos : 0;
    631    }
    632
    633    /**
    634     * Tests a given byte array to see if it contains any characters within the alphabet or PAD.
    635     *
    636     * Intended for use in checking line-ending arrays.
    637     *
    638     * @param arrayOctet byte array to test.
    639     * @return {@code true} if any byte is a valid character in the alphabet or PAD; {@code false} otherwise.
    640     */
    641    protected boolean containsAlphabetOrPad(final byte[] arrayOctet) {
    642        if (arrayOctet != null) {
    643            for (final byte element : arrayOctet) {
    644                if (pad == element || isInAlphabet(element)) {
    645                    return true;
    646                }
    647            }
    648        }
    649        return false;
    650    }
    651
    652    /**
    653     * Decodes a byte[] containing characters in the Base-N alphabet.
    654     *
    655     * @param array A byte array containing Base-N character data.
    656     * @return A byte array containing binary data.
    657     */
    658    @Override
    659    public byte[] decode(final byte[] array) {
    660        if (BinaryCodec.isEmpty(array)) {
    661            return array;
    662        }
    663        final Context context = new Context();
    664        decode(array, 0, array.length, context);
    665        decode(array, 0, EOF, context); // Notify decoder of EOF.
    666        final byte[] result = new byte[context.pos];
    667        readResults(result, 0, result.length, context);
    668        return result;
    669    }
    670
    671    // package protected for access from I/O streams
    672    abstract void decode(byte[] array, int i, int length, Context context);
    673
    674    /**
    675     * Decodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of the Decoder interface, and will throw a
    676     * DecoderException if the supplied object is not of type byte[] or String.
    677     *
    678     * @param obj Object to decode.
    679     * @return An object (of type byte[]) containing the binary data which corresponds to the byte[] or String supplied.
    680     * @throws DecoderException if the parameter supplied is not of type byte[].
    681     */
    682    @Override
    683    public Object decode(final Object obj) throws DecoderException {
    684        if (obj instanceof byte[]) {
    685            return decode((byte[]) obj);
    686        }
    687        if (obj instanceof String) {
    688            return decode((String) obj);
    689        }
    690        throw new DecoderException("Parameter supplied to Base-N decode is not a byte[] or a String");
    691    }
    692
    693    /**
    694     * Decodes a String containing characters in the Base-N alphabet.
    695     *
    696     * @param array A String containing Base-N character data.
    697     * @return A byte array containing binary data.
    698     */
    699    public byte[] decode(final String array) {
    700        return decode(StringUtils.getBytesUtf8(array));
    701    }
    702
    703    /**
    704     * Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
    705     *
    706     * @param array A byte array containing binary data.
    707     * @return A byte array containing only the base N alphabetic character data.
    708     */
    709    @Override
    710    public byte[] encode(final byte[] array) {
    711        if (BinaryCodec.isEmpty(array)) {
    712            return array;
    713        }
    714        return encode(array, 0, array.length);
    715    }
    716
    717    /**
    718     * Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet.
    719     *
    720     * @param array  A byte array containing binary data.
    721     * @param offset initial offset of the subarray.
    722     * @param length length of the subarray.
    723     * @return A byte array containing only the base N alphabetic character data.
    724     * @since 1.11
    725     */
    726    public byte[] encode(final byte[] array, final int offset, final int length) {
    727        if (BinaryCodec.isEmpty(array)) {
    728            return array;
    729        }
    730        final Context context = new Context();
    731        encode(array, offset, length, context);
    732        encode(array, offset, EOF, context); // Notify encoder of EOF.
    733        final byte[] buf = new byte[context.pos - context.readPos];
    734        readResults(buf, 0, buf.length, context);
    735        return buf;
    736    }
    737
    738    // package protected for access from I/O streams
    739    abstract void encode(byte[] array, int i, int length, Context context);
    740
    741    /**
    742     * Encodes an Object using the Base-N algorithm. This method is provided in order to satisfy the requirements of the Encoder interface, and will throw an
    743     * EncoderException if the supplied object is not of type byte[].
    744     *
    745     * @param obj Object to encode.
    746     * @return An object (of type byte[]) containing the Base-N encoded data which corresponds to the byte[] supplied.
    747     * @throws EncoderException if the parameter supplied is not of type byte[].
    748     */
    749    @Override
    750    public Object encode(final Object obj) throws EncoderException {
    751        if (!(obj instanceof byte[])) {
    752            throw new EncoderException("Parameter supplied to Base-N encode is not a byte[]");
    753        }
    754        return encode((byte[]) obj);
    755    }
    756
    757    /**
    758     * Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. Uses UTF8 encoding.
    759     * <p>
    760     * This is a duplicate of {@link #encodeToString(byte[])}; it was merged during refactoring.
    761     * </p>
    762     *
    763     * @param array A byte array containing binary data.
    764     * @return String containing only character data in the appropriate alphabet.
    765     * @since 1.5
    766     */
    767    public String encodeAsString(final byte[] array) {
    768        return StringUtils.newStringUtf8(encode(array));
    769    }
    770
    771    /**
    772     * Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. Uses UTF8 encoding.
    773     *
    774     * @param array A byte array containing binary data.
    775     * @return A String containing only Base-N character data.
    776     */
    777    public String encodeToString(final byte[] array) {
    778        return StringUtils.newStringUtf8(encode(array));
    779    }
    780
    781    /**
    782     * Ensures that the buffer has room for {@code size} bytes
    783     *
    784     * @param size    minimum spare space required.
    785     * @param context The context to be used.
    786     * @return The buffer.
    787     */
    788    protected byte[] ensureBufferSize(final int size, final Context context) {
    789        if (context.buffer == null) {
    790            context.buffer = new byte[Math.max(size, getDefaultBufferSize())];
    791            context.pos = 0;
    792            context.readPos = 0;
    793            // Overflow-conscious:
    794            // x + y > z == x + y - z > 0
    795        } else if (context.pos + size - context.buffer.length > 0) {
    796            return resizeBuffer(context, context.pos + size);
    797        }
    798        return context.buffer;
    799    }
    800
    801    /**
    802     * Gets the decoding behavior policy.
    803     *
    804     * <p>
    805     * The default is lenient. If the decoding policy is strict, then decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a
    806     * valid encoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder.
    807     * </p>
    808     *
    809     * @return true if using strict decoding.
    810     * @since 1.15
    811     */
    812    public CodecPolicy getCodecPolicy() {
    813        return decodingPolicy;
    814    }
    815
    816    /**
    817     * Gets the default buffer size. Can be overridden.
    818     *
    819     * @return The default buffer size.
    820     */
    821    protected int getDefaultBufferSize() {
    822        return DEFAULT_BUFFER_SIZE;
    823    }
    824
    825    /**
    826     * Gets the amount of space needed to encode the supplied array.
    827     *
    828     * @param array byte[] array which will later be encoded.
    829     * @return amount of space needed to encode the supplied array. Returns a long since a max-len array will require &gt; Integer.MAX_VALUE.
    830     */
    831    public long getEncodedLength(final byte[] array) {
    832        // Calculate non-chunked size - rounded up to allow for padding
    833        // cast to long is needed to avoid possibility of overflow
    834        long len = (array.length + unencodedBlockSize - 1) / unencodedBlockSize * (long) encodedBlockSize;
    835        if (lineLength > 0) { // We're using chunking
    836            // Round up to nearest multiple
    837            len += (len + lineLength - 1) / lineLength * chunkSeparatorLength;
    838        }
    839        return len;
    840    }
    841
    842    /**
    843     * Tests whether this object has buffered data for reading.
    844     *
    845     * @param context The context to be used.
    846     * @return true if there is data still available for reading.
    847     */
    848    boolean hasData(final Context context) { // package protected for access from I/O streams
    849        return context.pos > context.readPos;
    850    }
    851
    852    /**
    853     * Tests whether or not the {@code octet} is in the current alphabet. Does not allow whitespace or pad.
    854     *
    855     * @param value The value to test.
    856     * @return {@code true} if the value is defined in the current alphabet, {@code false} otherwise.
    857     */
    858    protected abstract boolean isInAlphabet(byte value);
    859
    860    /**
    861     * Tests a given byte array to see if it contains only valid characters within the alphabet. The method optionally treats whitespace and pad as valid.
    862     *
    863     * @param arrayOctet byte array to test.
    864     * @param allowWhitespacePad if {@code true}, then whitespace and PAD are also allowed.
    865     * @return {@code true} if all bytes are valid characters in the alphabet or if the byte array is empty; {@code false}, otherwise.
    866     */
    867    public boolean isInAlphabet(final byte[] arrayOctet, final boolean allowWhitespacePad) {
    868        for (final byte octet : arrayOctet) {
    869            if (!isInAlphabet(octet) && (!allowWhitespacePad || octet != pad && !Character.isWhitespace(octet))) {
    870                return false;
    871            }
    872        }
    873        return true;
    874    }
    875
    876    /**
    877     * Tests a given String to see if it contains only valid characters within the alphabet. The method treats whitespace and PAD as valid.
    878     *
    879     * @param basen String to test.
    880     * @return {@code true} if all characters in the String are valid characters in the alphabet or if the String is empty; {@code false}, otherwise.
    881     * @see #isInAlphabet(byte[], boolean)
    882     */
    883    public boolean isInAlphabet(final String basen) {
    884        return isInAlphabet(StringUtils.getBytesUtf8(basen), true);
    885    }
    886
    887    /**
    888     * Tests true if decoding behavior is strict. Decoding will raise an {@link IllegalArgumentException} if trailing bits are not part of a valid encoding.
    889     *
    890     * <p>
    891     * The default is false for lenient decoding. Decoding will compose trailing bits into 8-bit bytes and discard the remainder.
    892     * </p>
    893     *
    894     * @return true if using strict decoding.
    895     * @since 1.15
    896     */
    897    public boolean isStrictDecoding() {
    898        return decodingPolicy == CodecPolicy.STRICT;
    899    }
    900
    901    /**
    902     * Reads buffered data into the provided byte[] array, starting at position bPos, up to a maximum of bAvail bytes. Returns how many bytes were actually
    903     * extracted.
    904     * <p>
    905     * Package private for access from I/O streams.
    906     * </p>
    907     *
    908     * @param b         byte[] array to extract the buffered data into.
    909     * @param position  position in byte[] array to start extraction at.
    910     * @param available amount of bytes we're allowed to extract. We may extract fewer (if fewer are available).
    911     * @param context   The context to be used.
    912     * @return The number of bytes successfully extracted into the provided byte[] array.
    913     */
    914    int readResults(final byte[] b, final int position, final int available, final Context context) {
    915        if (hasData(context)) {
    916            final int len = Math.min(available(context), available);
    917            System.arraycopy(context.buffer, context.readPos, b, position, len);
    918            context.readPos += len;
    919            if (!hasData(context)) {
    920                // All data read.
    921                // Reset position markers but do not set buffer to null to allow its reuse.
    922                // hasData(context) will still return false, and this method will return 0 until
    923                // more data is available, or -1 if EOF.
    924                context.pos = context.readPos = 0;
    925            }
    926            return len;
    927        }
    928        return context.eof ? EOF : 0;
    929    }
    930}