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

Modifier and Type	Class and Description
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

Modifier and Type	Method and Description
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 "ell"
    FlexBase64.ecncodeString("hello".getBytes("US-ASCII"), 1, 4);
 

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 "ell"
    FlexBase64.ecncodeStringURL("hello".getBytes("US-ASCII"), 1, 4);
 

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.ecncodeString("hello".getBytes("US-ASCII"), 1, 4);
 

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.ecncodeStringURL("hello".getBytes("US-ASCII"), 1, 4);
 

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.