Package io.undertow.util

Class FlexBase64

  • public class FlexBase64
extends Object
    An efficient and flexible Base64 implementation. This class can deal with both MIME Base64 and Base64url.
    Author:
    Jason T. Greene

    • Constructor Detail

      • FlexBase64

        public FlexBase64()

    • Method Detail

      • createEncoder

        public static FlexBase64.Encoder createEncoder​(boolean wrap)
        Creates a state driven base64 encoder.

        The Encoder instance is not thread-safe, and must not be shared between threads without establishing a happens-before relationship.

        Parameters:
        wrap - whether or not to wrap at 76 characters with CRLF
        Returns:
        an createEncoder instance

      • createURLEncoder

        public static FlexBase64.Encoder createURLEncoder​(boolean wrap)
        Creates a state driven base64url encoder.

        The Encoder instance is not thread-safe, and must not be shared between threads without establishing a happens-before relationship.

        Parameters:
        wrap - whether or not to wrap at 76 characters with CRLF
        Returns:
        an createEncoder instance

      • createDecoder

        public static FlexBase64.Decoder createDecoder()
        Creates a state driven base64 decoder.

        The Decoder instance is not thread-safe, and must not be shared between threads without establishing a happens-before relationship.

        Returns:
        a new createDecoder instance

      • createURLDecoder

        public static FlexBase64.Decoder createURLDecoder()
        Creates a state driven base64url decoder.

        The Decoder instance is not thread-safe, and must not be shared between threads without establishing a happens-before relationship.

        Returns:
        a new createDecoder instance

      • encodeString

        public static String encodeString​(byte[] source,
                                  boolean wrap)
        Encodes a fixed and complete byte array into a Base64 String.

        This method is only useful for applications which require a String and have all data to be encoded up-front. Note that byte arrays or buffers are almost always a better storage choice. They consume half the memory and can be reused (modified). In other words, it is almost always better to use encodeBytes(byte[], int, int, boolean), createEncoder(boolean), or createEncoderOutputStream(java.io.OutputStream, int, boolean) instead. instead.

        Parameters:
        source - the byte array to encode from
        wrap - whether or not to wrap the output at 76 chars with CRLFs
        Returns:
        a new String representing the Base64 output

      • encodeStringURL

        public static String encodeStringURL​(byte[] source,
                                     boolean wrap)
        Encodes a fixed and complete byte array into a Base64url String.

        This method is only useful for applications which require a String and have all data to be encoded up-front. Note that byte arrays or buffers are almost always a better storage choice. They consume half the memory and can be reused (modified). In other words, it is almost always better to use encodeBytes(byte[], int, int, boolean), createEncoder(boolean), or createEncoderOutputStream(java.io.OutputStream, int, boolean) instead. instead.

        Parameters:
        source - the byte array to encode from
        wrap - whether or not to wrap the output at 76 chars with CRLFs
        Returns:
        a new String representing the Base64url output

      • encodeString

        public static String encodeString​(byte[] source,
                                  int pos,
                                  int limit,
                                  boolean wrap)
        Encodes a fixed and complete byte array into a Base64 String.

        This method is only useful for applications which require a String and have all data to be encoded up-front. Note that byte arrays or buffers are almost always a better storage choice. They consume half the memory and can be reused (modified). In other words, it is almost always better to use encodeBytes(byte[], int, int, boolean), createEncoder(boolean), or createEncoderOutputStream(java.io.OutputStream, int, boolean) instead.

        
    // Encodes "ell"
    FlexBase64.encodeString("hello".getBytes("US-ASCII"), 1, 4);
        Parameters:
        source - the byte array to encode from
        pos - the position to start encoding from
        limit - the position to halt encoding at (exclusive)
        wrap - whether or not to wrap the output at 76 chars with CRLFs
        Returns:
        a new String representing the Base64 output

      • encodeStringURL

        public static String encodeStringURL​(byte[] source,
                                     int pos,
                                     int limit,
                                     boolean wrap)
        Encodes a fixed and complete byte array into a Base64url String.

        This method is only useful for applications which require a String and have all data to be encoded up-front. Note that byte arrays or buffers are almost always a better storage choice. They consume half the memory and can be reused (modified). In other words, it is almost always better to use encodeBytes(byte[], int, int, boolean), createEncoder(boolean), or createEncoderOutputStream(java.io.OutputStream, int, boolean) instead.

        
    // Encodes "ell"
    FlexBase64.encodeStringURL("hello".getBytes("US-ASCII"), 1, 4);
        Parameters:
        source - the byte array to encode from
        pos - the position to start encoding from
        limit - the position to halt encoding at (exclusive)
        wrap - whether or not to wrap the output at 76 chars with CRLFs
        Returns:
        a new String representing the Base64url output

      • encodeString

        public static String encodeString​(ByteBuffer source,
                                  boolean wrap)
        Encodes a fixed and complete byte buffer into a Base64 String.

        This method is only useful for applications which require a String and have all data to be encoded up-front. Note that byte arrays or buffers are almost always a better storage choice. They consume half the memory and can be reused (modified). In other words, it is almost always better to use encodeBytes(byte[], int, int, boolean), createEncoder(boolean), or createEncoderOutputStream(java.io.OutputStream, int, boolean) instead.

        
    // Encodes "hello"
    FlexBase64.encodeString(ByteBuffer.wrap("hello".getBytes("US-ASCII")), false);
        Parameters:
        source - the byte buffer to encode from
        wrap - whether or not to wrap the output at 76 chars with CRLFs
        Returns:
        a new String representing the Base64 output

      • encodeStringURL

        public static String encodeStringURL​(ByteBuffer source,
                                     boolean wrap)
        Encodes a fixed and complete byte buffer into a Base64url String.

        This method is only useful for applications which require a String and have all data to be encoded up-front. Note that byte arrays or buffers are almost always a better storage choice. They consume half the memory and can be reused (modified). In other words, it is almost always better to use encodeBytes(byte[], int, int, boolean), createEncoder(boolean), or createEncoderOutputStream(java.io.OutputStream, int, boolean) instead.

        
    // Encodes "hello"
    FlexBase64.encodeStringURL(ByteBuffer.wrap("hello".getBytes("US-ASCII")), false);
        Parameters:
        source - the byte buffer to encode from
        wrap - whether or not to wrap the output at 76 chars with CRLFs
        Returns:
        a new String representing the Base64url output

      • encodeBytes

        public static byte[] encodeBytes​(byte[] source,
                                 int pos,
                                 int limit,
                                 boolean wrap)
        Encodes a fixed and complete byte buffer into a Base64 byte array. 
        
    // Encodes "ell"
    FlexBase64.encodeString("hello".getBytes("US-ASCII"), 1, 4, false);
        Parameters:
        source - the byte array to encode from
        pos - the position to start encoding at
        limit - the position to halt encoding at (exclusive)
        wrap - whether or not to wrap at 76 characters with CRLFs
        Returns:
        a new byte array containing the encoded ASCII values

      • encodeBytesURL

        public static byte[] encodeBytesURL​(byte[] source,
                                    int pos,
                                    int limit,
                                    boolean wrap)
        Encodes a fixed and complete byte buffer into a Base64url byte array. 
        
    // Encodes "ell"
    FlexBase64.encodeStringURL("hello".getBytes("US-ASCII"), 1, 4, false);
        Parameters:
        source - the byte array to encode from
        pos - the position to start encoding at
        limit - the position to halt encoding at (exclusive)
        wrap - whether or not to wrap at 76 characters with CRLFs
        Returns:
        a new byte array containing the encoded ASCII values

      • decode

        public static ByteBuffer decode​(String source)
                         throws IOException
        Decodes a Base64 encoded string into a new byte buffer. The returned byte buffer is a heap buffer, and it is therefor possible to retrieve the backing array using ByteBuffer.array(), ByteBuffer.arrayOffset() and Buffer.limit(). The latter is very important since the decoded array may be larger than the decoded data. This is due to length estimation which avoids an unnecessary array copy.
        Parameters:
        source - the Base64 string to decode
        Returns:
        a byte buffer containing the decoded output
        Throws:
        IOException - if the encoding is invalid or corrupted

      • decodeURL

        public static ByteBuffer decodeURL​(String source)
                            throws IOException
        Decodes a Base64url encoded string into a new byte buffer. The returned byte buffer is a heap buffer, and it is therefor possible to retrieve the backing array using ByteBuffer.array(), ByteBuffer.arrayOffset() and Buffer.limit(). The latter is very important since the decoded array may be larger than the decoded data. This is due to length estimation which avoids an unnecessary array copy.
        Parameters:
        source - the Base64 string to decode
        Returns:
        a byte buffer containing the decoded output
        Throws:
        IOException - if the encoding is invalid or corrupted

      • decode

        public static ByteBuffer decode​(ByteBuffer source)
                         throws IOException
        Decodes a Base64 encoded byte buffer into a new byte buffer. The returned byte buffer is a heap buffer, and it is therefor possible to retrieve the backing array using ByteBuffer.array(), ByteBuffer.arrayOffset() and Buffer.limit(). The latter is very important since the decoded array may be larger than the decoded data. This is due to length estimation which avoids an unnecessary array copy.
        Parameters:
        source - the Base64 content to decode
        Returns:
        a byte buffer containing the decoded output
        Throws:
        IOException - if the encoding is invalid or corrupted

      • decodeURL

        public static ByteBuffer decodeURL​(ByteBuffer source)
                            throws IOException
        Decodes a Base64url encoded byte buffer into a new byte buffer. The returned byte buffer is a heap buffer, and it is therefor possible to retrieve the backing array using ByteBuffer.array(), ByteBuffer.arrayOffset() and Buffer.limit(). The latter is very important since the decoded array may be larger than the decoded data. This is due to length estimation which avoids an unnecessary array copy.
        Parameters:
        source - the Base64 content to decode
        Returns:
        a byte buffer containing the decoded output
        Throws:
        IOException - if the encoding is invalid or corrupted

      • decode

        public static ByteBuffer decode​(byte[] source,
                                int off,
                                int limit)
                         throws IOException
        Decodes a Base64 encoded byte array into a new byte buffer. The returned byte buffer is a heap buffer, and it is therefor possible to retrieve the backing array using ByteBuffer.array(), ByteBuffer.arrayOffset() and Buffer.limit(). The latter is very important since the decoded array may be larger than the decoded data. This is due to length estimation which avoids an unnecessary array copy.
        Parameters:
        source - the Base64 content to decode
        off - position to start decoding from in source
        limit - position to stop decoding in source (exclusive)
        Returns:
        a byte buffer containing the decoded output
        Throws:
        IOException - if the encoding is invalid or corrupted

      • decodeURL

        public static ByteBuffer decodeURL​(byte[] source,
                                   int off,
                                   int limit)
                            throws IOException
        Decodes a Base64url encoded byte array into a new byte buffer. The returned byte buffer is a heap buffer, and it is therefor possible to retrieve the backing array using ByteBuffer.array(), ByteBuffer.arrayOffset() and Buffer.limit(). The latter is very important since the decoded array may be larger than the decoded data. This is due to length estimation which avoids an unnecessary array copy.
        Parameters:
        source - the Base64url content to decode
        off - position to start decoding from in source
        limit - position to stop decoding in source (exclusive)
        Returns:
        a byte buffer containing the decoded output
        Throws:
        IOException - if the encoding is invalid or corrupted

      • createEncoderInputStream

        public static FlexBase64.EncoderInputStream createEncoderInputStream​(InputStream source,
                                                                     int bufferSize,
                                                                     boolean wrap)
        Creates an InputStream wrapper which encodes a source into base64 as it is read, until the source hits EOF. Upon hitting EOF, a standard base64 termination sequence will be readable. Clients can simply treat this input stream as if they were reading from a base64 encoded file. This stream attempts to read and encode in buffer size chunks from the source, in order to improve overall performance. Thus, BufferInputStream is not necessary and will lead to double buffering.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        source - an input source to read from
        bufferSize - the chunk size to buffer from the source
        wrap - whether or not the stream should wrap base64 output at 76 characters
        Returns:
        an encoded input stream instance.

      • createEncoderInputStream

        public static FlexBase64.EncoderInputStream createEncoderInputStream​(InputStream source)
        Creates an InputStream wrapper which encodes a source into base64 as it is read, until the source hits EOF. Upon hitting EOF, a standard base64 termination sequence will be readable. Clients can simply treat this input stream as if they were reading from a base64 encoded file. This stream attempts to read and encode in 8192 byte chunks. Thus, BufferedInputStream is not necessary as a source and will lead to double buffering.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        source - an input source to read from
        Returns:
        an encoded input stream instance.

      • createDecoderInputStream

        public static FlexBase64.DecoderInputStream createDecoderInputStream​(InputStream source,
                                                                     int bufferSize)
        Creates an InputStream wrapper which decodes a base64 input source into the decoded content as it is read, until the source hits EOF. Upon hitting EOF, a standard base64 termination sequence will be readable. Clients can simply treat this input stream as if they were reading from a base64 encoded file. This stream attempts to read and encode in buffer size byte chunks. Thus, BufferedInputStream is not necessary as a source and will lead to double buffering.

        Note that the end of a base64 stream can not reliably be detected, so if multiple base64 streams exist on the wire, the source stream will need to simulate an EOF when the boundary mechanism is detected.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        source - an input source to read from
        bufferSize - the chunk size to buffer before when reading from the target
        Returns:
        a decoded input stream instance.

      • createDecoderInputStream

        public static FlexBase64.DecoderInputStream createDecoderInputStream​(InputStream source)
        Creates an InputStream wrapper which decodes a base64 input source into the decoded content as it is read, until the source hits EOF. Upon hitting EOF, a standard base64 termination sequence will be readable. Clients can simply treat this input stream as if they were reading from a base64 encoded file. This stream attempts to read and encode in 8192 byte chunks. Thus, BufferedInputStream is not necessary as a source and will lead to double buffering.

        Note that the end of a base64 stream can not reliably be detected, so if multiple base64 streams exist on the wire, the source stream will need to simulate an EOF when the boundary mechanism is detected.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        source - an input source to read from
        Returns:
        a decoded input stream instance.

      • createEncoderOutputStream

        public static FlexBase64.EncoderOutputStream createEncoderOutputStream​(OutputStream target,
                                                                       int bufferSize,
                                                                       boolean wrap)
        Creates an OutputStream wrapper which base64 encodes and writes to the passed OutputStream target. When this stream is closed base64 padding will be added if needed. Alternatively if this represents an "inner stream", the FlexBase64.EncoderOutputStream.complete() method can be called to close out the inner stream without closing the wrapped target.

        All bytes written will be queued to a buffer in the specified size. This stream, therefore, does not require BufferedOutputStream, which would lead to double buffering.

        Parameters:
        target - an output target to write to
        bufferSize - the chunk size to buffer before writing to the target
        wrap - whether or not the stream should wrap base64 output at 76 characters
        Returns:
        an encoded output stream instance.

      • createEncoderOutputStream

        public static FlexBase64.EncoderOutputStream createEncoderOutputStream​(OutputStream output)
        Creates an OutputStream wrapper which base64 encodes and writes to the passed OutputStream target. When this stream is closed base64 padding will be added if needed. Alternatively if this represents an "inner stream", the FlexBase64.EncoderOutputStream.complete() method can be called to close out the inner stream without closing the wrapped target.

        All bytes written will be queued to an 8192 byte buffer. This stream, therefore, does not require BufferedOutputStream, which would lead to double buffering.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        output - the output stream to write encoded output to
        Returns:
        an encoded output stream instance.

      • createDecoderOutputStream

        public static FlexBase64.DecoderOutputStream createDecoderOutputStream​(OutputStream output,
                                                                       int bufferSize)
        Creates an OutputStream wrapper which decodes base64 content before writing to the passed OutputStream target.

        All bytes written will be queued to a buffer using the specified buffer size. This stream, therefore, does not require BufferedOutputStream, which would lead to double buffering.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        output - the output stream to write decoded output to
        bufferSize - the buffer size to buffer writes to
        Returns:
        a decoded output stream instance.

      • createDecoderOutputStream

        public static FlexBase64.DecoderOutputStream createDecoderOutputStream​(OutputStream output)
        Creates an OutputStream wrapper which decodes base64 content before writing to the passed OutputStream target.

        All bytes written will be queued to an 8192 byte buffer. This stream, therefore, does not require BufferedOutputStream, which would lead to double buffering.

        This stream is not thread-safe, and should not be shared between threads, without establishing a happens-before relationship.

        Parameters:
        output - the output stream to write decoded output to
        Returns:
        a decoded output stream instance.