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:
JDE 4.6.0
Method Detail

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.

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:
JDE 4.0.2

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:
JDE 4.1.0

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 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.

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.

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.

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.

Overrides:
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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.