io.undertow.util

## Class FlexBase64

- java.lang.Object
- - io.undertow.util.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

### Nested Class Summary

Nested Classes
`static class` `FlexBase64.Decoder` Controls the decoding process.
`static class` `FlexBase64.DecoderInputStream` An input stream which decodes bytes as they are read from a stream with Base64 encoded data.
`static class` `FlexBase64.DecoderOutputStream` An output stream which decodes base64 data written to it, and writes the decoded output to the wrapped inner stream.
`static class` `FlexBase64.Encoder` Controls the encoding process.
`static class` `FlexBase64.EncoderInputStream` An input stream which encodes bytes as they are read from a stream.
`static class` `FlexBase64.EncoderOutputStream` An output stream which base64 encodes all passed data and writes it to the wrapped target output stream.

### Constructor Summary

Constructors
Constructor and Description
`FlexBase64()`

### Method Summary

All Methods Static Methods Concrete Methods
`static FlexBase64.Decoder` `createDecoder()` Creates a state driven base64 decoder.
`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.
`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.
`static FlexBase64.DecoderOutputStream` `createDecoderOutputStream(OutputStream output)` Creates an OutputStream wrapper which decodes base64 content before writing to the passed OutputStream target.
`static FlexBase64.DecoderOutputStream` `createDecoderOutputStream(OutputStream output, int bufferSize)` Creates an OutputStream wrapper which decodes base64 content before writing to the passed OutputStream target.
`static FlexBase64.Encoder` `createEncoder(boolean wrap)` Creates a state driven base64 encoder.
`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.
`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.
`static FlexBase64.EncoderOutputStream` `createEncoderOutputStream(OutputStream output)` Creates an OutputStream wrapper which base64 encodes and writes to the passed OutputStream target.
`static FlexBase64.EncoderOutputStream` `createEncoderOutputStream(OutputStream target, int bufferSize, boolean wrap)` Creates an OutputStream wrapper which base64 encodes and writes to the passed OutputStream target.
`static FlexBase64.Decoder` `createURLDecoder()` Creates a state driven base64url decoder.
`static FlexBase64.Encoder` `createURLEncoder(boolean wrap)` Creates a state driven base64url encoder.
`static ByteBuffer` `decode(byte[] source, int off, int limit)` Decodes a Base64 encoded byte array into a new byte buffer.
`static ByteBuffer` `decode(ByteBuffer source)` Decodes a Base64 encoded byte buffer into a new byte buffer.
`static ByteBuffer` `decode(String source)` Decodes a Base64 encoded string into a new byte buffer.
`static ByteBuffer` `decodeURL(byte[] source, int off, int limit)` Decodes a Base64url encoded byte array into a new byte buffer.
`static ByteBuffer` `decodeURL(ByteBuffer source)` Decodes a Base64url encoded byte buffer into a new byte buffer.
`static ByteBuffer` `decodeURL(String source)` Decodes a Base64url encoded string into a new byte buffer.
`static byte[]` `encodeBytes(byte[] source, int pos, int limit, boolean wrap)` Encodes a fixed and complete byte buffer into a Base64 byte array.
`static byte[]` `encodeBytesURL(byte[] source, int pos, int limit, boolean wrap)` Encodes a fixed and complete byte buffer into a Base64url byte array.
`static String` `encodeString(byte[] source, boolean wrap)` Encodes a fixed and complete byte array into a Base64 String.
`static String` `encodeString(byte[] source, int pos, int limit, boolean wrap)` Encodes a fixed and complete byte array into a Base64 String.
`static String` `encodeString(ByteBuffer source, boolean wrap)` Encodes a fixed and complete byte buffer into a Base64 String.
`static String` `encodeStringURL(byte[] source, boolean wrap)` Encodes a fixed and complete byte array into a Base64url String.
`static String` `encodeStringURL(byte[] source, int pos, int limit, boolean wrap)` Encodes a fixed and complete byte array into a Base64url String.
`static String` `encodeStringURL(ByteBuffer source, boolean wrap)` Encodes a fixed and complete byte buffer into a Base64url String.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### 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.