net.rim.device.api.io
Class Base64OutputStream

java.lang.Object
  java.io.OutputStream
      net.rim.device.api.io.Base64OutputStream

public class Base64OutputStream
extends OutputStream

Output stream for writing Base64 encoded data.

This class implements a stream for writing and encoding data using the Base64 encoding scheme (for a description of which, see RFC 2045).

Sample code

Example 1:

try
{
byte[] encoded = Base64OutputStream.encode(toEncode, 0, toEncode.length, false, false);
String encodedStr = new String(encoded, "UTF-8");
}
catch (IOException ioe)
{
}

Example 2:

// Encodes the given byte array in base64.
// Offset and length specify which part of the array to encode.
// The encoded data is returned as a String
public static String encodeBase64( byte[] toEncode, int offset, int length )
{
ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream( length );

Base64OutputStream base64OutputStream = new Base64OutputStream( byteArrayOutputStream );

try
{
base64OutputStream.write( toEncode, offset, length );
base64OutputStream.flush();
base64OutputStream.close();
}
catch (IOException ioe)
{
return null;
}

return byteArrayOutputStream.toString();
}

Constructor Summary

Base64OutputStream(OutputStream outputStream)
Constructs a new Base64OutputSream instance with underlying output stream.

Base64OutputStream(OutputStream outputStream, boolean insertCR, boolean insertLF)
Constructs a new Base64OutputStream instance with specific newline and carriage return settings.

Base64OutputStream(OutputStream outputStream, boolean insertCR, boolean insertLF, int newlineTrigger)
Constructs a new Base64OutputStream instance with specific newline and carriage return settings.

Method Summary
void	close() Closes this output stream.
static byte[]	encode(byte[] input, int inputOffset, int inputLength, boolean insertCR, boolean insertLF) Encodes the provided input into Base 64 and returns the encoded result.
static String	encodeAsString(byte[] input, int inputOffset, int inputLength, boolean insertCR, boolean insertLF) Encodes the provided input into Base 64 and returns the encoded result.
void	flush() Flushes this stream, writing out any remaining buffered data.
void	write(byte[] data) Writes encoded byte array of data to this stream.
void	write(byte[] data, int dataOffset, int dataLength) Writes some encoded bytes from byte array to this stream.
void	write(int data) Writes encoded byte to this stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

Base64OutputStream

public Base64OutputStream(OutputStream outputStream)

Constructs a new Base64OutputSream instance with underlying output stream.

This builds a Base64 output stream that, by default, inserts no newlines or carriage returns. As a result, the output might not be compatible with some mail transports.

Parameters:

outputStream - Underlying output stream to contain the data.

Base64OutputStream

public Base64OutputStream(OutputStream outputStream,
                          boolean insertCR,
                          boolean insertLF)

Constructs a new Base64OutputStream instance with specific newline and carriage return settings.

This builds a Base64 output stream that can, by default, insert newlines and/or carriage returns. If activated, this stream inserts line end characters (either none, CR, LF, or CR/LF) after every 76 encoded characters.

Parameters:

outputStream - Underlying output stream to contain the data.

insertCR - If true, insert carriage returns (0x0D) after every 76 encoded characters.

insertLF - If true, insert line feeds (0x0A) after every 76 encoded characters (and after the carriage return if the insertCR parameter is also true).

Base64OutputStream

public Base64OutputStream(OutputStream outputStream,
                          boolean insertCR,
                          boolean insertLF,
                          int newlineTrigger)

Constructs a new Base64OutputStream instance with specific newline and carriage return settings.

This builds a Base64 output stream that can, by default, insert newlines and/or carriage returns. If activated, this stream inserts line end characters (either none, CR, LF, or CR/LF) after every _linefeedTrigger*4 encoded characters.

Parameters:

outputStream - Underlying output stream to contain the data.

insertCR - If true, insert carriage returns (0x0D) after every _linefeedTrigger*4 encoded characters.

insertLF - If true, insert line feeds (0x0A) after every _linefeedTrigger*4 encoded characters (and after the carriage return if the insertCR parameter is also true).

linefeedTrigger - Four times linefeedTrigger is the number of encoded characters before the specified newline and/or carriage return.

Since:

BlackBerry API 4.6.0

Method Detail

write

public void write(int data)
           throws IOException

Writes encoded byte to this stream.

Invoke this method to encode, and then write, a single byte to this stream.

Specified by:

write in class OutputStream

Parameters:

data - Data to encode and write; this method encodes and writes the eight lower bits of this integer, and ignores the higher 24 bits.

Throws:

IOException - If the encoder is closed or the underlying stream has a problem.

write

public void write(byte[] data)
           throws IOException

Writes encoded byte array of data to this stream.

Invoke this method to encode, and then write, the bytes contained in the input array to this stream.

Overrides:

write in class OutputStream

Parameters:

data - Data to write.

Throws:

IOException - If the encoder is closed or the underlying stream has a problem.

See Also:

OutputStream.write(byte[], int, int)

write

public void write(byte[] data,
                  int dataOffset,
                  int dataLength)
           throws IOException

Writes some encoded bytes from byte array to this stream.

Invoke this method to encode, and then write, some bytes contained in the input array to this stream.

Overrides:

write in class OutputStream

Parameters:

data - Data to write.

dataOffset - First byte from provided array to encode and write.

dataLength - Number of bytes from provided array to encode and write.

Throws:

IOException - If the encoder is closed or the underlying stream has a problem.

flush

public void flush()
           throws IOException

Flushes this stream, writing out any remaining buffered data.

Invoke this method to force this stream to write out any data it has currently buffered.

Note: Eventually, you must invoke Base64OutputStream.close() to ensure that the output is padded correctly.

Overrides:

flush in class OutputStream

Throws:

IOException - If the encoder is closed or the underlying stream has a problem.

close

public void close()
           throws IOException

Closes this output stream.

Invoke this method to force this stream to write out all its buffered data, and close this stream and release any system resources it uses.

Overrides:

close in class OutputStream

Throws:

IOException - If the underlying stream has a problem.

encodeAsString

public static String encodeAsString(byte[] input,
                                    int inputOffset,
                                    int inputLength,
                                    boolean insertCR,
                                    boolean insertLF)
                             throws IOException

Encodes the provided input into Base 64 and returns the encoded result.

Parameters:

input - The input data to encode

inputOffset - The offset into the array

inputLength - The length of the array

insertCR - Set to true if you want to insert a CR after every 76th encoded character

insertLF - Set to true if you want to insert a LF after every 76th encoded character

Returns:

The encoded input as a byte array

Throws:

IOException - Thrown if an encoding error occurred

Since:

BlackBerry API 4.1.0

encode

public static byte[] encode(byte[] input,
                            int inputOffset,
                            int inputLength,
                            boolean insertCR,
                            boolean insertLF)
                     throws IOException

Encodes the provided input into Base 64 and returns the encoded result.

Parameters:

input - The input data to encode

inputOffset - The offset into the array

inputLength - The length of the array

insertCR - Set to true if you want to insert a CR after every 76th encoded character

insertLF - Set to true if you want to insert a LF after every 76th encoded character

Returns:

The encoded input as a byte array

Throws:

IOException - Thrown if an encoding error occurred

Since:

BlackBerry API 4.0.2