Java Base64 Encoding and Decoding

1. Overview

In this tutorial, we explore the various utilities that provide Base64 encoding and decoding functionality in Java.

We’re mainly going to illustrate the new Java 8 APIs. Also, we use the utility APIs of Apache Commons.

2. Java 8 for Base 64

Java 8 has finally added Base64 capabilities to the standard API, via the java.util.Base64 utility class.

Let’s start by looking at a basic encoder process.

2.1. Java 8 Basic Base64

The basic encoder keeps things simple and encodes the input as-is, without any line separation.

The encoder maps the input to a set of characters in the A-Za-z0-9+/ character set.

Let’s first encode a simple String:

String originalInput = "test input";
String encodedString = Base64.getEncoder().encodeToString(originalInput.getBytes());

Note how we retrieve the full Encoder API via the simple getEncoder() utility method.

Let’s now decode that String back to the original form:

byte[] decodedBytes = Base64.getDecoder().decode(encodedString);
String decodedString = new String(decodedBytes);

2.2. Java 8 Base64 Encoding Without Padding

In Base64 encoding, the length of an output-encoded String must be a multiple of four. If necessary, the encoder adds one or two padding characters (=) at the end of the output as needed in order to meet this requirement.

Upon decoding, the decoder discards these extra padding characters. To dig deeper into padding in Base64, check out this detailed answer on Stack Overflow.

Sometimes, we need to skip the padding of the output. For instance, the resulting String will never be decoded back. So, we can simply choose to encode without padding:

String encodedString = 
  Base64.getEncoder().withoutPadding().encodeToString(originalInput.getBytes());

2.3. Java 8 URL Encoding

URL encoding is very similar to the basic encoder. Also, it uses the URL and Filename Safe Base64 alphabet. In addition, it does not add any line separation:

String originalUrl = "https://www.google.co.nz/?gfe_rd=cr&ei=dzbFV&gws_rd=ssl#q=java";
String encodedUrl = Base64.getUrlEncoder().encodeToString(originalURL.getBytes());

Decoding happens in much the same way. The getUrlDecoder() utility method returns a java.util.Base64.Decoder. So, we use it to decode the URL:

byte[] decodedBytes = Base64.getUrlDecoder().decode(encodedUrl);
String decodedUrl = new String(decodedBytes);

2.4. Java 8 MIME Encoding

Let’s start by generating some basic MIME input to encode:

private static StringBuilder getMimeBuffer() {
    StringBuilder buffer = new StringBuilder();
    for (int count = 0; count < 10; ++count) {
        buffer.append(UUID.randomUUID().toString());
    }
    return buffer;
}

The MIME encoder generates a Base64-encoded output using the basic alphabet. However, the format is MIME-friendly.

Each line of the output is no longer than 76 characters. Also, it ends with a carriage return followed by a linefeed (\r\n):

StringBuilder buffer = getMimeBuffer();
byte[] encodedAsBytes = buffer.toString().getBytes();
String encodedMime = Base64.getMimeEncoder().encodeToString(encodedAsBytes);

In the decoding process, we can use the getMimeDecoder() method that returns a java.util.Base64.Decoder:

byte[] decodedBytes = Base64.getMimeDecoder().decode(encodedMime);
String decodedMime = new String(decodedBytes);

3. Encoding/Decoding Using Apache Commons Code

First, we need to define the commons-codec dependency in the pom.xml:

<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.16.0</version>
</dependency>

The main API is the org.apache.commons.codec.binary.Base64 class. We can initialize it with various constructors:

• Base64(boolean urlSafe) creates the Base64 API by controlling the URL-safe mode (on or off).
• Base64(int lineLength) creates the Base64 API in a URL-unsafe mode and controls the length of the line (default is 76).
• Base64(int lineLength, byte[] lineSeparator) creates the Base64 API by accepting an extra line separator, which by default is CRLF (“\r\n”).

Once the Base64 API is created, both encoding and decoding are quite simple:

String originalInput = "test input";
Base64 base64 = new Base64();
String encodedString = new String(base64.encode(originalInput.getBytes()));

Moreover, the decode() method of the Base64 class returns the decoded string:

String decodedString = new String(base64.decode(encodedString.getBytes()));

Another option is using the static API of Base64 instead of creating an instance:

String originalInput = "test input";
String encodedString = new String(Base64.encodeBase64(originalInput.getBytes()));
String decodedString = new String(Base64.decodeBase64(encodedString.getBytes()));

4. Converting a String to a byte Array

Sometimes, we need to convert a String to a byte[]. The simplest way is to use the String getBytes() method:

String originalInput = "test input";
byte[] result = originalInput.getBytes();

assertEquals(originalInput.length(), result.length);

We can provide encoding as well and not depend on default encoding. As a result, it’s system-dependent:

String originalInput = "test input";
byte[] result = originalInput.getBytes(StandardCharsets.UTF_16);

assertTrue(originalInput.length() < result.length);

If our String is Base64 encoded, we can use the Base64 decoder:

String originalInput = "dGVzdCBpbnB1dA==";
byte[] result = Base64.getDecoder().decode(originalInput);

assertEquals("test input", new String(result));

We can also use the DatatypeConverter parseBase64Binary() method:

String originalInput = "dGVzdCBpbnB1dA==";
byte[] result = DatatypeConverter.parseBase64Binary(originalInput);

assertEquals("test input", new String(result));

Finally, we can convert a hexadecimal String to a byte[] using the DatatypeConverter.parseHexBinary method:

String originalInput = "7465737420696E707574";
byte[] result = DatatypeConverter.parseHexBinary(originalInput);

assertEquals("test input", new String(result));

5. Conclusion

This article explained the basics of how to do Base64 encoding and decoding in Java. We used the new APIs introduced in Java 8 and Apache Commons.

Finally, there are a few other APIs that provide similar functionality: jakarta.xml.bind.DataTypeConverter with printHexBinary and parseBase64Binary.

Code snippets can be found over on GitHub.