com.unboundid.util

Class Base64

java.lang.Object

com.unboundid.util.Base64

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class Base64
extends java.lang.Object

This class provides methods for encoding and decoding data in base64 as defined in RFC 4648. It provides a relatively compact way of representing binary data using only printable characters. It uses a six-bit encoding mechanism in which every three bytes of raw data is converted to four bytes of base64-encoded data, which means that it only requires about a 33% increase in size (as compared with a hexadecimal representation, which requires a 100% increase in size).

Base64 encoding is used in LDIF processing as per RFC 2849 to represent data that contains special characters or might otherwise be ambiguous. It is also used in a number of other areas (e.g., for the ASCII representation of certificates) where it is desirable to deal with a string containing only printable characters but the raw data may contain other characters outside of that range.

This class also provides support for the URL-safe variant (called base64url) as described in RFC 4648 section 5. This is nearly the same as base64, except that the '+' and '/' characters are replaced with '-' and '_', respectively. The padding may be omitted if the context makes the data size clear, but if padding is to be used then the URL-encoded "%3d" will be used instead of "=".

Example

The following examples demonstrate the process for base64-encoding raw data, and for decoding a string containing base64-encoded data back to the raw data used to create it:

 // Base64-encode some raw data:
 String base64String = Base64.encode(rawDataBytes);

 // Decode a base64 string back to raw data:
 byte[] decodedRawDataBytes;
 try
 {
   decodedRawDataBytes = Base64.decode(base64String);
 }
 catch (ParseException pe)
 {
   // The string did not represent a valid base64 encoding.
   decodedRawDataBytes = null;
 }
 

Method Summary

Modifier and Type	Method and Description
static byte[]	decode(java.lang.String data) Decodes the contents of the provided base64-encoded string.
static java.lang.String	decodeToString(java.lang.String data) Decodes the contents of the provided base64-encoded string to a string containing the raw data using the UTF-8 encoding.
static java.lang.String	encode(byte[] data) Encodes the provided data in base64 format.
static void	encode(byte[] data, ByteStringBuffer buffer) Appends a base64-encoded representation of the provided data to the given buffer.
static void	encode(byte[] data, int off, int length, ByteStringBuffer buffer) Appends a base64-encoded representation of the provided data to the given buffer.
static void	encode(byte[] data, int off, int length, java.lang.StringBuilder buffer) Appends a base64-encoded representation of the provided data to the given buffer.
static void	encode(byte[] data, java.lang.StringBuilder buffer) Appends a base64-encoded representation of the provided data to the given buffer.
static java.lang.String	encode(java.lang.String data) Encodes the UTF-8 representation of the provided string in base64 format.
static void	encode(java.lang.String data, ByteStringBuffer buffer) Appends a base64-encoded version of the contents of the provided buffer (using a UTF-8 representation) to the given buffer.
static void	encode(java.lang.String data, java.lang.StringBuilder buffer) Appends a base64-encoded version of the contents of the provided buffer (using a UTF-8 representation) to the given buffer.
static byte[]	urlDecode(java.lang.String data) Decodes the contents of the provided base64url-encoded string.
static java.lang.String	urlDecodeToString(java.lang.String data) Decodes the contents of the provided base64-encoded string to a string containing the raw data using the UTF-8 encoding.
static java.lang.String	urlEncode(byte[] data, boolean pad) Retrieves a base64url-encoded representation of the provided data to the given buffer.
static void	urlEncode(byte[] data, int off, int length, ByteStringBuffer buffer, boolean pad) Appends a base64url-encoded representation of the provided data to the given buffer.
static void	urlEncode(byte[] data, int off, int length, java.lang.StringBuilder buffer, boolean pad) Appends a base64url-encoded representation of the provided data to the given buffer.
static java.lang.String	urlEncode(java.lang.String data, boolean pad) Retrieves a base64url-encoded representation of the provided data to the given buffer.
static void	urlEncode(java.lang.String data, ByteStringBuffer buffer, boolean pad) Retrieves a base64url-encoded representation of the provided data to the given buffer.
static void	urlEncode(java.lang.String data, java.lang.StringBuilder buffer, boolean pad) Retrieves a base64url-encoded representation of the provided data to the given buffer.

Methods inherited from class java.lang.Object

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

Method Detail

encode

@NotNull
public static java.lang.String encode(@NotNull
                                               java.lang.String data)

Encodes the UTF-8 representation of the provided string in base64 format.

Parameters:

data - The raw data to be encoded. It must not be null.

Returns:

The base64-encoded representation of the provided data.

encode

@NotNull
public static java.lang.String encode(@NotNull
                                               byte[] data)

Encodes the provided data in base64 format.

Parameters:

data - The raw data to be encoded. It must not be null.

Returns:

The base64-encoded representation of the provided data.

encode

public static void encode(@NotNull
                          java.lang.String data,
                          @NotNull
                          java.lang.StringBuilder buffer)

Appends a base64-encoded version of the contents of the provided buffer (using a UTF-8 representation) to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

buffer - The buffer to which the base64-encoded data is to be written.

encode

public static void encode(@NotNull
                          java.lang.String data,
                          @NotNull
                          ByteStringBuffer buffer)

Appends a base64-encoded version of the contents of the provided buffer (using a UTF-8 representation) to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

buffer - The buffer to which the base64-encoded data is to be written.

encode

public static void encode(@NotNull
                          byte[] data,
                          @NotNull
                          java.lang.StringBuilder buffer)

Appends a base64-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

buffer - The buffer to which the base64-encoded data is to be written.

encode

public static void encode(@NotNull
                          byte[] data,
                          int off,
                          int length,
                          @NotNull
                          java.lang.StringBuilder buffer)

Appends a base64-encoded representation of the provided data to the given buffer.

Parameters:

data - The array containing the raw data to be encoded. It must not be null.

off - The offset in the array at which the data to encode begins.

length - The number of bytes to be encoded.

buffer - The buffer to which the base64-encoded data is to be written.

encode

public static void encode(@NotNull
                          byte[] data,
                          @NotNull
                          ByteStringBuffer buffer)

Appends a base64-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

buffer - The buffer to which the base64-encoded data is to be written.

encode

public static void encode(@NotNull
                          byte[] data,
                          int off,
                          int length,
                          @NotNull
                          ByteStringBuffer buffer)

Appends a base64-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

off - The offset in the array at which the data to encode begins.

length - The number of bytes to be encoded.

buffer - The buffer to which the base64-encoded data is to be written.

urlEncode

@NotNull
public static java.lang.String urlEncode(@NotNull
                                                  java.lang.String data,
                                                  boolean pad)

Retrieves a base64url-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

pad - Indicates whether to pad the URL if necessary. Padding will use "%3d", as the URL-escaped representation of the equal sign.

Returns:

A base64url-encoded representation of the provided data to the given buffer.

urlEncode

public static void urlEncode(@NotNull
                             java.lang.String data,
                             @NotNull
                             java.lang.StringBuilder buffer,
                             boolean pad)

Retrieves a base64url-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

buffer - The buffer to which the base64-encoded data is to be written.

pad - Indicates whether to pad the URL if necessary. Padding will use "%3d", as the URL-escaped representation of the equal sign.

urlEncode

public static void urlEncode(@NotNull
                             java.lang.String data,
                             @NotNull
                             ByteStringBuffer buffer,
                             boolean pad)

Retrieves a base64url-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

buffer - The buffer to which the base64-encoded data is to be written.

pad - Indicates whether to pad the URL if necessary. Padding will use "%3d", as the URL-escaped representation of the equal sign.

urlEncode

@NotNull
public static java.lang.String urlEncode(@NotNull
                                                  byte[] data,
                                                  boolean pad)

Retrieves a base64url-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

pad - Indicates whether to pad the URL if necessary. Padding will use "%3d", as the URL-escaped representation of the equal sign.

Returns:

A base64url-encoded representation of the provided data to the given buffer.

urlEncode

public static void urlEncode(@NotNull
                             byte[] data,
                             int off,
                             int length,
                             @NotNull
                             java.lang.StringBuilder buffer,
                             boolean pad)

Appends a base64url-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

off - The offset in the array at which the data to encode begins.

length - The number of bytes to be encoded.

buffer - The buffer to which the base64-encoded data is to be written.

pad - Indicates whether to pad the URL if necessary. Padding will use "%3d", as the URL-escaped representation of the equal sign.

urlEncode

public static void urlEncode(@NotNull
                             byte[] data,
                             int off,
                             int length,
                             @NotNull
                             ByteStringBuffer buffer,
                             boolean pad)

Appends a base64url-encoded representation of the provided data to the given buffer.

Parameters:

data - The raw data to be encoded. It must not be null.

off - The offset in the array at which the data to encode begins.

length - The number of bytes to be encoded.

buffer - The buffer to which the base64-encoded data is to be written.

pad - Indicates whether to pad the URL if necessary. Padding will use "%3d", as the URL-escaped representation of the equal sign.

decode

@NotNull
public static byte[] decode(@NotNull
                                     java.lang.String data)
                              throws java.text.ParseException

Decodes the contents of the provided base64-encoded string.

Parameters:

data - The base64-encoded string to decode. It must not be null.

Returns:

A byte array containing the decoded data.

Throws:

java.text.ParseException - If the contents of the provided string cannot be parsed as base64-encoded data.

decodeToString

@NotNull
public static java.lang.String decodeToString(@NotNull
                                                       java.lang.String data)
                                                throws java.text.ParseException

Decodes the contents of the provided base64-encoded string to a string containing the raw data using the UTF-8 encoding.

Parameters:

data - The base64-encoded string to decode. It must not be null.

Returns:

A string containing the decoded data.

Throws:

java.text.ParseException - If the contents of the provided string cannot be parsed as base64-encoded data using the UTF-8 encoding.

urlDecode

@NotNull
public static byte[] urlDecode(@NotNull
                                        java.lang.String data)
                                 throws java.text.ParseException

Decodes the contents of the provided base64url-encoded string.

Parameters:

data - The base64url-encoded string to decode. It must not be null.

Returns:

A byte array containing the decoded data.

Throws:

java.text.ParseException - If the contents of the provided string cannot be parsed as base64url-encoded data.

urlDecodeToString

@NotNull
public static java.lang.String urlDecodeToString(@NotNull
                                                          java.lang.String data)
                                                   throws java.text.ParseException

Decodes the contents of the provided base64-encoded string to a string containing the raw data using the UTF-8 encoding.

Parameters:

data - The base64-encoded string to decode. It must not be null.

Returns:

A string containing the decoded data.

Throws:

java.text.ParseException - If the contents of the provided string cannot be parsed as base64-encoded data using the UTF-8 encoding.