Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The Base64 class

Reference for java.util.Base64: basic, URL-safe and MIME encoders and decoders, padding, streaming wrappers and the IllegalArgumentException for bad input.

java.util.Base64 (Java 8) converts binary data to text made of 64 safe ASCII characters and back. It is used to put bytes into places that only accept text: JSON strings, URLs, HTTP headers, e-mail bodies, data URIs. Base64 is an encoding, not encryption; anyone can reverse it, so never use it to hide secrets.

Every three input bytes become four output characters, so the encoded form is about 33% larger. The class has three variants, each with an encoder and a decoder: basic, URL and filename safe, and MIME. You get them from the static methods getEncoder(), getUrlEncoder(), getMimeEncoder() and the matching get...Decoder() methods. Encoders and decoders are immutable and thread-safe.

Java
String encoded = Base64.getEncoder().encodeToString("hello".getBytes(StandardCharsets.UTF_8));
byte[] back = Base64.getDecoder().decode(encoded);

Try it

Java Encoding and decoding text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java MIME, errors and streaming

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
Base64.Encoder enc = Base64.getEncoder();       // also getUrlEncoder(), getMimeEncoder()
Base64.Decoder dec = Base64.getDecoder();       // also getUrlDecoder(), getMimeDecoder()
Method Description
Encoder.encodeToString(byte[]) Encodes to a String.
Encoder.encode(byte[]) Encodes to a byte[] of ASCII characters.
Encoder.encode(byte[] src, byte[] dst) Encodes into a supplied array and returns the length.
Encoder.withoutPadding() Returns an encoder that omits trailing =.
Encoder.wrap(OutputStream) An output stream that encodes what is written to it.
Decoder.decode(String), decode(byte[]) Decodes; returns byte[].
Decoder.wrap(InputStream) An input stream that decodes while reading.
getMimeEncoder(int lineLength, byte[] separator) MIME encoder with custom line length (rounded down to a multiple of 4) and separator.
Variant Alphabet and rules
Basic A-Z a-z 0-9 + / with = padding, no line breaks.
URL and filename safe - and _ instead of + and /.
MIME Basic alphabet, lines of at most 76 characters separated by \r\n; the decoder ignores characters outside the alphabet.

Throws: IllegalArgumentException from decoders for characters outside the alphabet (basic and URL), wrong padding or a truncated final group.

Usage notes

  • Specify the charset when converting text to bytes and back (StandardCharsets.UTF_8); the Base64 step itself only sees bytes.
  • Use the URL variant for tokens in URLs, cookies and file names. Mixing variants fails: + and / are errors for the URL decoder.
  • Padding. The decoder accepts unpadded input only for a correctly truncated last group. Without padding on the encoder side, remember to use a decoder that tolerates it (the Java decoders do).
  • Basic is strict. Whitespace or line breaks in the input cause an exception; use the MIME decoder to read wrapped text.
  • Large data should be streamed with wrap instead of building giant strings.
  • Not encryption. It offers no secrecy or integrity. For HTTP Basic auth you still need TLS.
  • Old classes. sun.misc.BASE64Encoder was removed long ago, and javax.xml.bind.DatatypeConverter is no longer in the JDK.
  • Hex is the other common text form of bytes: see HexFormat.