javabase64 1.3 manual

Index

Requirements
Installation
Javadocs
Quickstart
Encoding with Base64OutputStream
Decoding with Base64InputStream

Requirements

To run the javabase64 library you need a Java Runtime Environment J2SE v. 1.2 or later.

Installation

Add the javabase64-1.3.jar file to your application classpath, and you'll be automatically enabled to the use of the javabase64 classes.

Javadocs

Here come the javabase64 javadocs.

Quickstart

The javabase64 library consists of two streams and a utility class.

The it.sauronsoftware.base64.Base64 utility class is, in most of cases, has everything you need to encode and decode.

First of all, you should tell apart if you have to encode/decode a string or a binary stream.

If you want to encode a string, you can easily call:

String encoded = Base64.encode("Hello, world!");

The result of this operation is a Base64 encoded string, that you can decode back later by calling:

String decoded = Base64.decode(encoded);

You can force the use of a specific charset during strings encoding and decoding operations:

String encoded = Base64.encode("Hello, world!", "UTF-8");
String decoded = Base64.decode(encoded, "UTF-8");

If you are working with binary data (i.e. images) you can use other forms of the encode() and decode() methods.

If data are not large and you handle them directly in memory, using a byte array:

byte[] source = ...; // load your data here
byte[] encoded = Base64.encode(source);
byte[] decoded = Base64.decode(encoded);

Larger data are better handled with streams. The next sample code encodes a file to another, using java.io.InputStream and java.io.OutputStream objects:

InputStream inputStream = new FileInputStream("source.jpg");
OutputStream outputStream = new FileOutputStream("encoded.b64");
Base64.encode(inputStream, outputStream);
outputStream.close();
inputStream.close();

In similar manner, a stream can be decoded:

InputStream inputStream = new FileInputStream("encoded.b64");
OutputStream outputStream = new FileOutputStream("decoded.jpg");
Base64.decode(inputStream, outputStream);
outputStream.close();
inputStream.close();

Shortcuts for java.io.File objects are provided. Encoding from a file to another:

File source = new File("source.jpg");
File encoded = new File("encoded.b64");
Base64.encode(source, encoded);

Decoding from a file to another:

File encoded = new File("encoded.b64");
File decoded = new File("decoded.jpg");
Base64.decode(encoded, decoded);

Encoding with Base64OutputStream

You can gain more control on the encoding process by avoiding the use of the static utilities in the Base64 class and by using directly a it.sauronsoftware.base64.Base64OutputStream instance.

The Base64OutputStream extends java.io.OutputStream and works as many other well know Java streams.

You can create a Base64OutputStream by wrapping another existing OutputStream:

Base64OutputStream encodingStream = new Base64OutputStream(myOutputStream);

I.e. you can send encoded data directly to a file by calling:

Base64OutputStream encodingStream = new Base64OutputStream(new FileOutputStream("encoded.b64"));

Now you can write your bytes in the stream as you would do with a common output stream. Data will be automatically encoded by the Base64OutputStream class.

encodingStream.write(bytes);

Don't forget to close the stream when the writing operation is completed. This is necessary to finalize the encoded data line.

encodingStream.close();

By default, Base64OutputStream wraps to a new line every 76 bytes sent to the underlying output stream. This behavior can be changed by supplying an alternative wrapAt value to the Base64OutputStream constructor:

Base64OutputStream encodingStream = new Base64OutputStream(myOutputStream, 48);

A value less than 1 disables wrapping:

Base64OutputStream encodingStream = new Base64OutputStream(myOutputStream, 0);

Decoding with Base64InputStream

You can gain more control on the decoding process by using a it.sauronsoftware.base64.Base64InputStream instance.

The Base64InputStream extends java.io.InputStream and works as many other well know Java streams.

You can create a Base64InputStream by wrapping another existing InputStream:

Base64InputStream decodingStream = new Base64InputStream(myInputStream);

I.e. you can read decoded data directly from an encoded file by calling:

Base64InputStream decodingStream = new Base64InputStream(new FileInputStream("encoded.b64"));

Now you can read your bytes from the stream as you would do with a common input stream. Data will be automatically decoded by the Base64InputStream class.

decodingStream.read(bytes);

Don't forget to close the stream when the reading operation is completed.

decodingStream.close();