Class 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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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, 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, ByteStringBuffer 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.