All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.fireflysource.common.codec.base64.BaseNCodec Maven / Gradle / Ivy

There is a newer version: 5.0.2
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.fireflysource.common.codec.base64;

import java.nio.charset.StandardCharsets;
import java.util.Arrays;

/**
 * Abstract superclass for Base-N encoders and decoders.
 *
 * 

* This class is thread-safe. *

* * @version $Id: BaseNCodec.java 1634404 2014-10-26 23:06:10Z ggregory $ */ public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder { /** * Holds thread context so classes can be thread-safe. *

* This class is not itself thread-safe; each thread must allocate its own copy. * * @since 1.7 */ static class Context { /** * Place holder for the bytes we're dealing with for our based logic. * Bitwise operations store and extract the encoding or decoding from this variable. */ int ibitWorkArea; /** * Place holder for the bytes we're dealing with for our based logic. * Bitwise operations store and extract the encoding or decoding from this variable. */ long lbitWorkArea; /** * Buffer for streaming. */ byte[] buffer; /** * Position where next character should be written in the buffer. */ int pos; /** * Position where next character should be read from the buffer. */ int readPos; /** * Boolean flag to indicate the EOF has been reached. Once EOF has been reached, this object becomes useless, * and must be thrown away. */ boolean eof; /** * 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 goes beyond lineLength (if lineLength > 0). */ int currentLinePos; /** * 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. */ int modulus; Context() { } /** * Returns a String useful for debugging (especially within a debugger.) * * @return a String useful for debugging. */ @SuppressWarnings("boxing") // OK to ignore boxing here @Override public String toString() { return String.format("%s[buffer=%s, currentLinePos=%s, eof=%s, ibitWorkArea=%s, lbitWorkArea=%s, " + "modulus=%s, pos=%s, readPos=%s]", this.getClass().getSimpleName(), Arrays.toString(buffer), currentLinePos, eof, ibitWorkArea, lbitWorkArea, modulus, pos, readPos); } } /** * EOF * * @since 1.7 */ static final int EOF = -1; /** * MIME chunk size per RFC 2045 section 6.8. * *

* The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any * equal signs. *

* * @see RFC 2045 section 6.8 */ public static final int MIME_CHUNK_SIZE = 76; /** * PEM chunk size per RFC 1421 section 4.3.2.4. * *

* The {@value} character limit does not count the trailing CRLF, but counts all other characters, including any * equal signs. *

* * @see RFC 1421 section 4.3.2.4 */ public static final int PEM_CHUNK_SIZE = 64; private static final int DEFAULT_BUFFER_RESIZE_FACTOR = 2; /** * Defines the default buffer size - currently {@value} * - must be large enough for at least one encoded block+separator */ private static final int DEFAULT_BUFFER_SIZE = 8192; /** * Mask used to extract 8 bits, used in decoding bytes */ protected static final int MASK_8BITS = 0xff; /** * Byte used to pad output. */ protected static final byte PAD_DEFAULT = '='; // Allow static access to default /** * @deprecated Use {@link #pad}. Will be removed in 2.0. */ @Deprecated protected final byte PAD = PAD_DEFAULT; // instance variable just in case it needs to vary later protected final byte pad; // instance variable just in case it needs to vary later /** * Number of bytes in each full block of unencoded data, e.g. 4 for Base64 and 5 for Base32 */ private final int unencodedBlockSize; /** * Number of bytes in each full block of encoded data, e.g. 3 for Base64 and 8 for Base32 */ private final int encodedBlockSize; /** * Chunksize for encoding. Not used when decoding. * A value of zero or less implies no chunking of the encoded data. * Rounded down to nearest multiple of encodedBlockSize. */ protected final int lineLength; /** * Size of chunk separator. Not used unless {@link #lineLength} > 0. */ private final int chunkSeparatorLength; /** * Note lineLength is rounded down to the nearest multiple of {@link #encodedBlockSize} * If chunkSeparatorLength is zero, then chunking is disabled. * * @param unencodedBlockSize the size of an unencoded block (e.g. Base64 = 3) * @param encodedBlockSize the size of an encoded block (e.g. Base64 = 4) * @param lineLength if > 0, use chunking with a length lineLength * @param chunkSeparatorLength the chunk separator length, if relevant */ protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength) { this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, PAD_DEFAULT); } /** * Note lineLength is rounded down to the nearest multiple of {@link #encodedBlockSize} * If chunkSeparatorLength is zero, then chunking is disabled. * * @param unencodedBlockSize the size of an unencoded block (e.g. Base64 = 3) * @param encodedBlockSize the size of an encoded block (e.g. Base64 = 4) * @param lineLength if > 0, use chunking with a length lineLength * @param chunkSeparatorLength the chunk separator length, if relevant * @param pad byte used as padding byte. */ protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize, final int lineLength, final int chunkSeparatorLength, final byte pad) { this.unencodedBlockSize = unencodedBlockSize; this.encodedBlockSize = encodedBlockSize; final boolean useChunking = lineLength > 0 && chunkSeparatorLength > 0; this.lineLength = useChunking ? (lineLength / encodedBlockSize) * encodedBlockSize : 0; this.chunkSeparatorLength = chunkSeparatorLength; this.pad = pad; } /** * Returns true if this object has buffered data for reading. * * @param context the context to be used * @return true if there is data still available for reading. */ boolean hasData(final Context context) { // package protected for access from I/O streams return context.buffer != null; } /** * Returns the amount of buffered data available for reading. * * @param context the context to be used * @return The amount of buffered data available for reading. */ int available(final Context context) { // package protected for access from I/O streams return context.buffer != null ? context.pos - context.readPos : 0; } /** * Get the default buffer size. Can be overridden. * * @return {@link #DEFAULT_BUFFER_SIZE} */ protected int getDefaultBufferSize() { return DEFAULT_BUFFER_SIZE; } /** * Increases our buffer by the {@link #DEFAULT_BUFFER_RESIZE_FACTOR}. * * @param context the context to be used */ private byte[] resizeBuffer(final Context context) { if (context.buffer == null) { context.buffer = new byte[getDefaultBufferSize()]; context.pos = 0; context.readPos = 0; } else { final byte[] b = new byte[context.buffer.length * DEFAULT_BUFFER_RESIZE_FACTOR]; System.arraycopy(context.buffer, 0, b, 0, context.buffer.length); context.buffer = b; } return context.buffer; } /** * Ensure that the buffer has room for size bytes * * @param size minimum spare space required * @param context the context to be used * @return the buffer */ protected byte[] ensureBufferSize(final int size, final Context context) { if ((context.buffer == null) || (context.buffer.length < context.pos + size)) { return resizeBuffer(context); } return context.buffer; } /** * Extracts buffered data into the provided byte[] array, starting at position bPos, up to a maximum of bAvail * bytes. Returns how many bytes were actually extracted. *

* Package protected for access from I/O streams. * * @param b byte[] array to extract the buffered data into. * @param bPos position in byte[] array to start extraction at. * @param bAvail amount of bytes we're allowed to extract. We may extract fewer (if fewer are available). * @param context the context to be used * @return The number of bytes successfully extracted into the provided byte[] array. */ int readResults(final byte[] b, final int bPos, final int bAvail, final Context context) { if (context.buffer != null) { final int len = Math.min(available(context), bAvail); System.arraycopy(context.buffer, context.readPos, b, bPos, len); context.readPos += len; if (context.readPos >= context.pos) { context.buffer = null; // so hasData() will return false, and this method can return -1 } return len; } return context.eof ? EOF : 0; } /** * Checks if a byte value is whitespace or not. * Whitespace is taken to mean: space, tab, CR, LF * * @param byteToCheck the byte to check * @return true if byte is whitespace, false otherwise */ protected static boolean isWhiteSpace(final byte byteToCheck) { switch (byteToCheck) { case ' ': case '\n': case '\r': case '\t': return true; default: return false; } } /** * 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 EncoderException if the supplied object is not of type byte[]. * * @param obj Object to encode * @return An object (of type byte[]) containing the Base-N encoded data which corresponds to the byte[] supplied. * @throws EncoderException if the parameter supplied is not of type byte[] */ @Override public Object encode(final Object obj) throws EncoderException { if (!(obj instanceof byte[])) { throw new EncoderException("Parameter supplied to Base-N encode is not a byte[]"); } return encode((byte[]) obj); } /** * Encodes a byte[] containing binary data, into a String containing characters in the Base-N alphabet. * Uses UTF8 encoding. * * @param pArray a byte array containing binary data * @return A String containing only Base-N character data */ public String encodeToString(final byte[] pArray) { return new String(encode(pArray), StandardCharsets.UTF_8); } /** * Encodes a byte[] containing binary data, into a String containing characters in the appropriate alphabet. * Uses UTF8 encoding. * * @param pArray a byte array containing binary data * @return String containing only character data in the appropriate alphabet. */ public String encodeAsString(final byte[] pArray) { return new String(encode(pArray), StandardCharsets.UTF_8); } /** * 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 DecoderException if the supplied object is not of type byte[] or String. * * @param obj Object to decode * @return An object (of type byte[]) containing the binary data which corresponds to the byte[] or String * supplied. * @throws DecoderException if the parameter supplied is not of type byte[] */ @Override public Object decode(final Object obj) throws DecoderException { if (obj instanceof byte[]) { return decode((byte[]) obj); } else if (obj instanceof String) { return decode((String) obj); } else { throw new DecoderException("Parameter supplied to Base-N decode is not a byte[] or a String"); } } /** * Decodes a String containing characters in the Base-N alphabet. * * @param pArray A String containing Base-N character data * @return a byte array containing binary data */ public byte[] decode(final String pArray) { return decode(pArray.getBytes(StandardCharsets.UTF_8)); } /** * Decodes a byte[] containing characters in the Base-N alphabet. * * @param pArray A byte array containing Base-N character data * @return a byte array containing binary data */ @Override public byte[] decode(final byte[] pArray) { if (pArray == null || pArray.length == 0) { return pArray; } final Context context = new Context(); decode(pArray, 0, pArray.length, context); decode(pArray, 0, EOF, context); // Notify decoder of EOF. final byte[] result = new byte[context.pos]; readResults(result, 0, result.length, context); return result; } /** * Encodes a byte[] containing binary data, into a byte[] containing characters in the alphabet. * * @param pArray a byte array containing binary data * @return A byte array containing only the basen alphabetic character data */ @Override public byte[] encode(final byte[] pArray) { if (pArray == null || pArray.length == 0) { return pArray; } final Context context = new Context(); encode(pArray, 0, pArray.length, context); encode(pArray, 0, EOF, context); // Notify encoder of EOF. final byte[] buf = new byte[context.pos - context.readPos]; readResults(buf, 0, buf.length, context); return buf; } // package protected for access from I/O streams abstract void encode(byte[] pArray, int i, int length, Context context); // package protected for access from I/O streams abstract void decode(byte[] pArray, int i, int length, Context context); /** * Returns whether or not the octet is in the current alphabet. * Does not allow whitespace or pad. * * @param value The value to test * @return true if the value is defined in the current alphabet, false otherwise. */ protected abstract boolean isInAlphabet(byte value); /** * 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. * * @param arrayOctet byte array to test * @param allowWSPad if true, then whitespace and PAD are also allowed * @return true if all bytes are valid characters in the alphabet or if the byte array is empty; * false, otherwise */ public boolean isInAlphabet(final byte[] arrayOctet, final boolean allowWSPad) { for (int i = 0; i < arrayOctet.length; i++) { if (!isInAlphabet(arrayOctet[i]) && (!allowWSPad || (arrayOctet[i] != pad) && !isWhiteSpace(arrayOctet[i]))) { return false; } } return true; } /** * Tests a given String to see if it contains only valid characters within the alphabet. * The method treats whitespace and PAD as valid. * * @param basen String to test * @return true if all characters in the String are valid characters in the alphabet or if * the String is empty; false, otherwise * @see #isInAlphabet(byte[], boolean) */ public boolean isInAlphabet(final String basen) { return isInAlphabet(basen.getBytes(StandardCharsets.UTF_8), true); } /** * Tests a given byte array to see if it contains any characters within the alphabet or PAD. *

* Intended for use in checking line-ending arrays * * @param arrayOctet byte array to test * @return true if any byte is a valid character in the alphabet or PAD; false otherwise */ protected boolean containsAlphabetOrPad(final byte[] arrayOctet) { if (arrayOctet == null) { return false; } for (final byte element : arrayOctet) { if (pad == element || isInAlphabet(element)) { return true; } } return false; } /** * Calculates the amount of space needed to encode the supplied array. * * @param pArray byte[] array which will later be encoded * @return amount of space needed to encoded the supplied array. * Returns a long since a max-len array will require > Integer.MAX_VALUE */ public long getEncodedLength(final byte[] pArray) { // Calculate non-chunked size - rounded up to allow for padding // cast to long is needed to avoid possibility of overflow long len = ((pArray.length + unencodedBlockSize - 1) / unencodedBlockSize) * (long) encodedBlockSize; if (lineLength > 0) { // We're using chunking // Round up to nearest multiple len += ((len + lineLength - 1) / lineLength) * chunkSeparatorLength; } return len; } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy