com.hunnysoft.jmime
Class Base64Encoder

java.lang.Object
  com.hunnysoft.jmime.Base64Encoder

public class Base64Encoder
extends java.lang.Object

Class that performs base64 encoding.

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.

Base64Encoder provides two interfaces for performing base64 encoding.

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

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

Base64Encoder allows you to change certain options, which affect the behavior of the encoder:

• Maximum Line Length The value of this option determines the maximum length of a line in the encoder's output. If you don't want any line breaks at all, you may set the maximum line length to a very large value (for example, Integer.MAX_VALUE). The allowed values must be a multiple of 4, and the library enforces this restriction by rounding down any value that is not a multiple of 4 (for example, it rounds 73, 74, or 75 down to 72). The default value is 72.

• Output CR LF If you set this option to true, then the encoder uses CR LF as the end-of-line characters in the encoded output. If you set this option to false, then the encoder uses LF alone. The default value is true if TextUtil.EOL is TextUtil.CRLF_EOL.

• Suppress Final Newline If you set this option to true, then the encoder does not put a final newline (CR LF, or LF) at the end of the encoded output, unless the last line of output is a full line. If you set this option to false, then the encoder always adds a newline to the end of the encoded output, even if the last line is a partial line. If you don't want any end-of-line characters in the output, you may set this option to true and set the Maximum Line Length to a very large value. The default value is false (meaning that a final newline is always added).

Using the Low-Level Interface

The low-level interface allows you to encode binary data one buffer at a time; thus you may encode data of unlimited size using a limited amount of memory. For example, if you want to encode 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 encoder, and write to the output file one buffer at a time.

The low-level interface comprises three methods: start(), encodeSegment(ByteBuffer,ByteBuffer), and finish(ByteBuffer). The procedure is described here:

1. Call start() to initialize the encoder.
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 encoded, 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 encodeSegment(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 encodeSegment 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 encodeSegment again.
5. Repeat steps 3 and 4 until the last input buffer is empty.
6. Call finish(ByteBuffer) to flush any internally buffered data to the output buffer. If the output buffer is full after finish returns, you must make room in the output buffer and call finish again. If finish returns and the output buffer is not full, then the encoding is finished.

You may use the same encoder object for multiple encode operations.

See Also:

Base64EncoderW, Base64 in RFC 2045

Constructor Summary

Base64Encoder()
Default constructor.

Method Summary

ByteString	encode(ByteString decoded) Performs single-step buffer-to-buffer base64 encoding.
void	encodeSegment(ByteBuffer inBuf, ByteBuffer outBuf) Encodes data from the input buffer to the output buffer.
void	finish(ByteBuffer outBuf) Finishes a multiple-buffer encode operation.
int	maxLineLen() Gets the maximum line length of the encoded output.
boolean	outputCrLf() Gets the CRLF end-of-line characters option.
void	setMaxLineLen(int len) Sets the maximum line length of the encoded output.
void	setOutputCrLf(boolean b) Sets the CRLF end-of-line characters option.
void	setSuppressFinalNewline(boolean b) Sets the option to suppress a final newline in the output.
void	start() Starts a multiple-buffer encode operation.
boolean	suppressFinalNewline() Gets the option to suppress a final newline in the output.

Methods inherited from class java.lang.Object

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

Constructor Detail

Base64Encoder

public Base64Encoder()

Default constructor.

The constructor sets default values for all the options.

Method Detail

setMaxLineLen

public void setMaxLineLen(int len)

Sets the maximum line length of the encoded output.

For MIME-compliant Internet mail, lines should be no longer than 76 characters. However, for applications other than mail, there may be no limit on line length. You may use this option to cause the encoder to output lines of any length. You may even force output without any line breaks by setting the maximum line length to a very large value (for example, Integer.MAX_VALUE) and by setting the Suppress Final Newline option to true.

This method forces the maximum line length to be a multiple of 4. If len is not a multiple of 4, then the method rounds it down to the nearest multiple of 4.

The default value is 72.

Parameters:

len - maximum line length of the encoded output

maxLineLen

public int maxLineLen()

Gets the maximum line length of the encoded output.

Returns:

maximum line length of the encoded output

See Also:

setMaxLineLen(int)

setOutputCrLf

public void setOutputCrLf(boolean b)

Sets the CRLF end-of-line characters option.

If this option is true, then the encoder uses CR LF as the end-of-line characters in the encoded output. If this option is false, then the encoder uses LF alone.

Normally, you do not need to set this option, because the encoder performs correctly by default. When your program starts, and before you create any threads, set TextUtil.EOL to either TextUtil.LF_EOL or TextUtil.CRLF_EOL. (The default is TextUtil.LF_EOL.) Then, the base64 encoder sets the value of this option based on the value of TextUtil.EOL.

Parameters:

b - true value causes the encoder to output CR LF for the end-of-line characters; false causes it to output LF.

outputCrLf

public boolean outputCrLf()

Gets the CRLF end-of-line characters option.

Returns:

boolean value of this option

See Also:

setOutputCrLf(boolean)

setSuppressFinalNewline

public void setSuppressFinalNewline(boolean b)

Sets the option to suppress a final newline in the output.

If this option is true, then the encoder does not put a final newline (CR LF, or LF) at the end of the encoded output, unless the last line of output is a full line. If this option is false, then the encoder always adds a newline to the end of the encoded output, even if the last line is a partial line. If you don't want any end-of-line characters in the output, you may set this option to true and set the Maximum Line Length to a very large value.

The default value is false (meaning that the encoder always adds a final newline).

Parameters:

b - if true, the encoder suppresses a final newline; if false, the encoder always adds a final newline

suppressFinalNewline

public boolean suppressFinalNewline()

Gets the option to suppress a final newline in the output.

Returns:

boolean value of this option

See Also:

setSuppressFinalNewline(boolean)

start

public void start()

Starts a multiple-buffer encode operation.

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

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

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

encodeSegment

public void encodeSegment(ByteBuffer inBuf,
                          ByteBuffer outBuf)

Encodes 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 encoding for the Base64Encoder class. It takes an input buffer and an output buffer as parameters, and encodes 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 encode 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 Base64Encoder.

Parameters:

inBuf - input buffer

outBuf - output buffer

finish

public void finish(ByteBuffer outBuf)

Finishes a multiple-buffer encode operation.

When you use the low-level interface, the encoder buffers some data internally. Therefore, after you have passed all input data to the encoder, you must call this method to flush the internal buffer.

The following condition must be satisfied when you call the method:

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

The above condition must also be satisified after the method returns in order to guarantee that all output data has been written to the output buffer. You may need to call finish more than once before the above condition is satisfied when the method returns.

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

Parameters:

outBuf - output buffer

encode

public ByteString encode(ByteString decoded)

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

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

This method makes it very simple to perform base64 encoding. 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 encoding of large data using limited memory.

This method uses the low-level interface internally. Any options set for the encoder object have the same effect using either this method or the low-level interface.

Parameters:

decoded - byte string containing the data to be encoded

Returns:

byte string containing the encoded data