org.josef.util

Class Base64

java.lang.Object

org.josef.util.Base64

@Status(stage=DEVELOPMENT,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",at="2010-09-23",reason="Initial review") @Review(by="Kees Schotanus",at="2010-10-01",reason="Additional review since binary data and line breaks were handled incorrectly")
public final class Base64
extends Object

Base64 encoding and decoding.
Base64 encoding allows encoding binary data to printable ASCII and vice versa. For a technical background on Base64 encoding check out the article at WikiPedia by clicking here.
Note: This class supports an alphabet where the characters at index 63 and 64 are respectively a '+' and a '/'. Line breaks at variable positions are supported. Characters outside the 64 printable character range are treated as illegal.

Version:

1.0 $Revision: 5877 $

Author:

Kees Schotanus

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAXIMUM_ENCODED_LINE_LENGHT Maximum line length of a Base64 encoded line according to RFC 2045.
static int	NO_LINE_BREAKS_LENGTH Constant line length to be used when Base64 encoded output should not contain line breaks.

Method Summary

Modifier and Type	Method and Description
static byte[]	decode(byte[] input) Decodes the supplied Base64 encoded input.
static byte[]	decodeFromFile(String fileName) Decodes the Base64 encoded data from the supplied fileName.
static void	decodeToFile(byte[] input, String fileName) Decodes the supplied input to a file with the supplied fileName.
static byte[]	encode(byte[] input, int lineSize) Encodes the supplied input to a Base64 encoding.
static byte[]	encodeFromFile(String fileName, int lineSize) Encodes the information stored in the file identified by the supplied fileName.
static void	encodeToFile(byte[] input, String fileName, int lineSize) Encodes the supplied input to a file with the supplied fileName.

Methods inherited from class java.lang.Object

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

Field Detail

MAXIMUM_ENCODED_LINE_LENGHT

public static final int MAXIMUM_ENCODED_LINE_LENGHT

Maximum line length of a Base64 encoded line according to RFC 2045.

See Also:

Constant Field Values

NO_LINE_BREAKS_LENGTH

public static final int NO_LINE_BREAKS_LENGTH

Constant line length to be used when Base64 encoded output should not contain line breaks.
The value is computed using the following expression:
Integer.MAX_VALUE - Integer.MAX_VALUE % 4;

See Also:

Constant Field Values

Method Detail

encodeFromFile

public static byte[] encodeFromFile(String fileName,
                                    int lineSize)
                             throws IOException

Encodes the information stored in the file identified by the supplied fileName.

Parameters:

fileName - The name of the file to decode the data from.

lineSize - The length of the lines in the encoded output, normally either 64 or 76 (but must be divisible by 4).
After every group of lineSize bytes, a CR/LF pair is added to the file.

Returns:

The decoded information from the file with the supplied fileName.

Throws:

IOException - When the unencoded file could not be read.

NullPointerException - When the supplied fileName is null.

IllegalArgumentException - When the supplied fileName is empty or when the supplied lineSize is not divisible by 4 or when the lineSize <= 0.

See Also:

encode(byte[], int)

encodeToFile

public static void encodeToFile(byte[] input,
                                String fileName,
                                int lineSize)
                         throws IOException

Encodes the supplied input to a file with the supplied fileName.

Parameters:

input - The data to encode.

fileName - The name of the file to write the encoded data to.

lineSize - The length of the lines in the encoded output, normally either 64 or 76 (but must be divisible by 4).
After every group of lineSize bytes, a CR/LF pair is added to the file.

Throws:

IOException - When the encoded bytes could not be written.

NullPointerException - When either the supplied input array or the supplied fileName is null.

IllegalArgumentException - When the supplied fileName is empty or when the supplied lineSize is not divisible by 4 or when the lineSize <= 0.

See Also:

encode(byte[], int)

encode

public static byte[] encode(byte[] input,
                            int lineSize)

Encodes the supplied input to a Base64 encoding.
Encoding comes down to converting 3 input bytes into 4 output bytes. The 3 input bytes contain 4 groups of 6 bits. For every group of 6 bits the accompanying Base64 characters is looked up and added to the output. When the input does not consist of a multiple of 3 bytes, pad characters are used in the output so the output always contains a multiple of 4 characters (neglecting whitespace characters).

Parameters:

input - The input to encode.

lineSize - The length of the lines in the encoded output, normally either 64 or 76.
After this length a CR/LF pair is written to the encoded output. The line size must be divisible by 4.

Returns:

The Base64 encoded version of the supplied input.
The returned array may be empty but will never be null.

Throws:

NullPointerException - When the supplied input array is null.

IllegalArgumentException - When the supplied lineSize is not divisible by 4 or when the lineSize <= 0.

decodeFromFile

public static byte[] decodeFromFile(String fileName)
                             throws IOException

Decodes the Base64 encoded data from the supplied fileName.

Parameters:

fileName - The name of the file to decode the data from.

Returns:

The decoded information from the file with the supplied fileName.

Throws:

IOException - When the decoded bytes could not be read.

NullPointerException - When the supplied fileName is null.

IllegalArgumentException - When the supplied fileName is empty.

See Also:

decode(byte[])

decodeToFile

public static void decodeToFile(byte[] input,
                                String fileName)
                         throws IOException

Decodes the supplied input to a file with the supplied fileName.

Parameters:

input - The data to decode.

fileName - The name of the file to write the decoded data to.

Throws:

IOException - When the decoded bytes could not be written.

NullPointerException - When either the supplied input array or the supplied fileName is null.

IllegalArgumentException - When the supplied fileName is empty.

See Also:

decode(byte[])

decode

public static byte[] decode(byte[] input)

Decodes the supplied Base64 encoded input.
Technically the following happens here:

1. Every input byte is looked up in a decode table, giving 6 bits
2. 4 groups of 6 bits are converted to 3 bytes
3. The 3 bytes are added to the output

Parameters:

input - The input to decode.

Returns:

The decoded version of the supplied Base64 encoded input.
The returned array may be empty but will never be null.

Throws:

NullPointerException - When the supplied input array is null.

IllegalArgumentException - When the supplied input contains an invalid character.