com.hunnysoft.jmime
Class Base64Decoder

java.lang.Object
  com.hunnysoft.jmime.Base64Decoder

public class Base64Decoder

extends java.lang.Object

Class that performs base64 decoding.

Base64 encoding encodes binary data into printable ASCII characters. The encoding is required because binary data cannot pass reliably through the Internet mail system. The encoding method is really quite simple: a group of three 8-bit bytes (3 x 8 bits = 24 bits) is encoded into a group of four printable characters. Only 64 different printable characters are used, so six bits uniquely identify each character. The four printable characters sufficiently encode the original three bytes (4 x 6 bits = 24 bits). The characters that occur in the encoding include the upper- and lower-case letters, the digits, and the characters "+" and "/". RFC 2045 describes the details of base64 encoding.

Base64Decoder provides two interfaces for performing base64 decoding.

A high-level interface decodes from an input ByteString to an output ByteString. This interface comprises a single method, decode(ByteString).

A low-level interface allows decoding by passing multiple buffers to the decoder. The correct procedure for using this interface is described below.

Using the Low-Level Interface

The low-level interface allows you to decode data one buffer at a time; thus you may decode data of unlimited size using a limited amount of memory. For example, if you want to decode data from an input file to an output file, you may read from the input file one buffer at a time, pass each buffer to the decoder, and write to the output file one buffer at a time.

The low-level interface comprises two methods: start() and decodeSegment(ByteBuffer,ByteBuffer). The procedure is described here:

1. Call start() to initialize the decoder.
2. Initialize an input buffer and an output buffer. These buffers are instances of ByteBuffer. To initialize an input buffer named inBuf, set inBuf.bytes to a byte array that contains the data to be decoded, set inBuf.pos to the offset of the beginning of the data in inBuf.bytes, and set inBuf.endPos to the offset of the first byte past the end of the data in inBuf.bytes. To initialize an output buffer named outBuf, set outBuf.bytes to a byte array, set outBuf.pos to zero, and set outBuf.endPos to the length of the array referenced by outBuf.bytes.
3. Call decodeSegment(ByteBuffer,ByteBuffer) with the input buffer and output buffer as arguments.
4. Check to see if the output buffer is full or if the input buffer is empty. If outBuf.pos == outBuf.endPos, then the output buffer is full, and you must make room in the output buffer before you call decodeSegment again. If inBuf.pos == inBuf.endPos, then the input buffer is empty, and you must supply the input buffer with more data before you call decodeSegment again.
5. Repeat steps 3 and 4 until the last input buffer is empty.

You may use the same decoder object for multiple decode operations.

Dealing With Errors

The decoder correctly decodes all data that is correctly encoded. However, if the data is not correctly encoded, the decoder detects these errors. All decoding errors are treated as fatal errors -- the decoder does not try to recover. The decoder notifies your application of decoding errors by throwing a DecodeException. Your program code should catch this exception.

See Also:

Base64DecoderW, Base64 in RFC 2045

Constructor Summary

Base64Decoder()
Default constructor.

Method Summary

ByteString	decode(ByteString encoded) Performs single-step buffer-to-buffer base64 decoding.
void	decodeSegment(ByteBuffer inBuf, ByteBuffer outBuf) Decodes data from the input buffer to the output buffer.
void	start() Starts a multiple-buffer decode operation.

Methods inherited from class java.lang.Object

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

Constructor Detail

Base64Decoder

public Base64Decoder()

Default constructor.

Method Detail

start

public void start()

Starts a multiple-buffer decode operation.

If you use the low-level interface for multiple-buffer decoding, you must call start to begin the decode operation. You may use a Base64Decoder instance for many decode operations, but you must call start to begin each operation.

For more information on using the low-level interface, see the overview section for Base64Decoder.

You do not need to call this method if you use the decode(ByteString) method for decoding.

decodeSegment

public void decodeSegment(ByteBuffer inBuf,
                          ByteBuffer outBuf)
                   throws DecodeException

Decodes data from the input buffer to the output buffer.

This method is an essential part of the low-level interface and performs most of the work of decoding for the Base64Decoder class. It takes an input buffer and an output buffer as parameters, and decodes data from the input buffer until the input buffer is empty or the output buffer is full. In other words, one of the following conditions is guaranteed to be satisfied when the method returns:

• inBuf.pos == inBuf.endPos (input buffer empty)
• outBuf.pos == outBuf.endPos (output buffer full)

You may call the method multiple times to decode multiple buffers of input data. However, before you call the method, both of the following conditions should be true:

• inBuf.pos < inBuf.endPos (input buffer data available)
• outBuf.pos < outBuf.endPos (output buffer space available)

For more information on using the low-level interface, see the overview section for Base64Decoder.

Parameters:

inBuf - input buffer

outBuf - output buffer

Throws:

DecodeException - if the decoder detects an error

decode

public ByteString decode(ByteString encoded)
                  throws DecodeException

Performs single-step buffer-to-buffer base64 decoding.

To perform base64 decoding using this method, create a ByteString containing the data you want to decode and pass it as the method's argument. The returned ByteString contains the decoded output.

This method makes it very simple to perform base64 decoding. The disadvantage of this method is that it requires all the data to be kept in memory for processing. You may use the low-level interface, described in the overview section, to perform base64 decoding of large data using limited memory.

This method uses the low-level interface internally.

Parameters:

encoded - byte string containing the encoded data

Returns:

byte string containing the decoded data

Throws:

DecodeException - if the decoder detects an error