net.rim.device.api.mime
Class MIMEOutputStream

java.lang.Object
  java.io.OutputStream
      net.rim.device.api.mime.MIMEOutputStream

public class MIMEOutputStream
extends OutputStream

Output stream for writing a MIME encoded data stream.

This class implements an output stream which can format output into parts according to the MIME standard.

Note: This class does no direct encoding of the actual data; it assumes that you encode your data before writing it to this stream.

Field Summary
static String	ENCODING_7BIT
static String	ENCODING_8BIT
static String	ENCODING_BASE64
static String	ENCODING_BINARY

Constructor Summary

MIMEOutputStream(OutputStream out, boolean isMultiPart, String encoding)
Creates a new MIMEOutputStream instance.

Method Summary
void	addContentTypeParameter(String attribute, String value) Adds a content type parameter for this part.
void	addHeaderField(String headerField) Adds a header field for this part.
void	close() Closes this output stream.
void	flush() Fluses this stream, writing out any remaining buffered data.
MIMEOutputStream	getPartOutputStream(boolean isMultiPart, String encoding) Creates a new MIME part for this stream.
void	setContentDescription(String contentDescription) Sets this part's content description.
void	setContentID(String contentID) Sets this part's content ID.
void	setContentType(String contentType) Sets this part's content type.
void	write(byte[] data) Writes a byte array of data to this stream.
void	write(byte[] buffer, int offset, int length) Writes some bytes from byte array to this stream.
void	write(int data) Writes byte to this stream.

Methods inherited from class java.lang.Object

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

Field Detail

ENCODING_7BIT

public static final String ENCODING_7BIT

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

ENCODING_8BIT

public static final String ENCODING_8BIT

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

ENCODING_BINARY

public static final String ENCODING_BINARY

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

ENCODING_BASE64

public static final String ENCODING_BASE64

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

Constructor Detail

MIMEOutputStream

public MIMEOutputStream(OutputStream out,
                        boolean isMultiPart,
                        String encoding)

Creates a new MIMEOutputStream instance.

Parameters:

out - Output stream to contain the data.

isMultiPart - True if this stream is to be a multi-part stream; false if this stream contains a single part.

encoding - Encoding scheme contained data will use (for example, "base64"; if null, then this builds a stream using the default, "7bit".

Method Detail

setContentType

public void setContentType(String contentType)
                    throws IllegalStateException

Sets this part's content type.

Parameters:

contentType - Content type for this part (for example, "text/plain"); if null, then this part's assumed type is "text/plain".

Throws:

IllegalStateException - If this is a multipart message and the content type does not start with "multipart".

setContentDescription

public void setContentDescription(String contentDescription)

Sets this part's content description.

Parameters:

contentDescription - Content description for this part; may be null.

addContentTypeParameter

public void addContentTypeParameter(String attribute,
                                    String value)

Adds a content type parameter for this part.

A content type parameter is a name value pair, associating an attribute with a value.

Parameters:

attribute - Content type parameter name.

value - Content type parameter value.

setContentID

public void setContentID(String contentID)

Sets this part's content ID.

Parameters:

contentID - Content ID for this part; may be null.

addHeaderField

public void addHeaderField(String headerField)

Adds a header field for this part.

The header name must begin with "Content-" or this method does nothing. The header field can span several multiple lines as long as line endings are marked with a carriage-return line-feed pair (CRLF).

Examples

 "Content-Internal: Message for Internal Use Only"

 "Content-Internal: Message for Internal Use Only; value=internal"
 

Parameters:

headerField - Header field for this part, including header name and value.

getPartOutputStream

public MIMEOutputStream getPartOutputStream(boolean isMultiPart,
                                            String encoding)
                                     throws IllegalStateException

Creates a new MIME part for this stream.

Invoke this method on a multi-part message to create a new part for it. This method retrieves a new MIME output stream you can use to write data into the new part.

Parameters:

isMultiPart - True if the new part will itself be a multi-part message.

encoding - Content encoding for this new part (for example, "base64").

Returns:

MIME output stream for the new part.

Throws:

IllegalStateException - If this stream is not already a multi-part message or if this stream has already been closed.

write

public void write(int data)
           throws IllegalStateException,
                  IOException

Writes byte to this stream.

Note: you may not use this method to write to a multi-part message. You should use getPartOutputStream to create a new single part (within this multi-part stream), and then invoke write on that.

Specified by:

write in class OutputStream

Parameters:

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

Throws:

IllegalStateException - If this stream is a multi-part message.

IOException - If an I/O error occurs; in particular, if this stream has already been closed.

write

public void write(byte[] data)
           throws IllegalStateException,
                  IOException

Writes a byte array of data to this stream.

Invoke this method to write all the bytes (in order) from a provided byte array to this output stream.

Note: you may not use this method to write to a multi-part message. You should use getPartOutputStream to create a new single part (within this multi-part stream), and then invoke write on that.

Overrides:

write in class OutputStream

Parameters:

data - Data to write.

Throws:

IllegalStateException - If this stream is a multi-part message.

IOException - If an I/O error occurs; in particular, if this stream has already been closed.

See Also:

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

write

public void write(byte[] buffer,
                  int offset,
                  int length)
           throws IllegalStateException,
                  IOException

Writes some bytes from byte array to this stream.

Invoke this method to write some of the bytes (in order) from a provided byte array to this output stream.

Note: you may not use this method to write to a multi-part message. You should use getPartOutputStream to create a new single part (within this multi-part stream), and then invoke write on that.

Overrides:

write in class OutputStream

Parameters:

buffer - Data to write.

offset - First byte from provided array to write.

length - Number of bytes from provided array to write.

Throws:

IllegalStateException - If this stream is a multi-part message.

IOException - If an I/O error occurs; in particular, if this stream has already been closed.

flush

public void flush()
           throws IOException

Fluses this stream, writing out any remaining buffered data.

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

Overrides:

flush in class OutputStream

Throws:

IOException - If an I/O error occurs.

close

public void close()
           throws IOException

Closes this output stream.

Invoke this method to close this sream and release any system resources it uses.

Overrides:

close in class OutputStream

Throws:

IOException - If an I/O error occurs.