net.rim.device.api.mime
Class MIMEInputStream

java.lang.Object
  |
  +--java.io.InputStream
        |
        +--net.rim.device.api.mime.MIMEInputStream

public class MIMEInputStream
extends InputStream

Input stream for reading a MIME encoded data stream.

This class implements a stream which reads in a MIME message and formats and parses the message into its constituent parts according to the MIME standard.


Constructor Summary
MIMEInputStream(InputStream input)
          Creates a new MIMEInputStream instance.
 
Method Summary
 int available()
          Retrieves number of available bytes.
 void close()
          Closes this input stream.
 String getContentDescription()
          Retrieves content description for this part.
 String getContentEncoding()
          Retrieves this part's content encoding.
 String getContentID()
          Retrieves this part's content ID.
 String getContentType()
          Retrieves this part's content type.
 String getContentTypeParameter(String attribute)
          Retrieves content type pararmeter by attribute.
 String getHeader(String headerFieldName)
          Retrieve header content for named header.
 Enumeration getHeaders()
          Retrieves enumeration of MIME headers.
 MIMEInputStream[] getParts()
          Retrieves all parts in this multi-part message.
 SharedInputStream getRawMIMEInputStream()
          Retrieves entire MIME part including headers.
 boolean isMultiPart()
          Determines if this is a multi-part message.
 int isPartComplete()
          Determines whether the entire contents of this MIME Part was read in or whether it was cutoff early.
 int read()
          Reads one byte from this stream.
 int read(byte[] buffer)
          Reads some bytes from this stream.
 int read(byte[] buffer, int offset, int length)
          Read specified number of bytes from this stream.
 long skip(long n)
          Skips over some bytes in this stream.
 
Methods inherited from class java.io.InputStream
mark, markSupported, reset
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MIMEInputStream

public MIMEInputStream(InputStream input)
                throws MIMEParsingException
Creates a new MIMEInputStream instance.

Parameters:
input - Input stream from which to read MIME encoded data.
Throws:
MIMEParsingException - If error encountered parsing input data.
Method Detail

available

public int available()
              throws IOException
Retrieves number of available bytes.

Invoke this method to find out the number of bytes you can freely read (or skip over) from this stream (that is, without being blocked by another invocation of one of this stream's methods, on this or another thread).

Note that if this is a multi part message, the amount available is from the first part.

Overrides:
available in class InputStream
Returns:
Number of bytes available for reading in this stream.
Throws:
IOException - If an I/O error occurs.

close

public void close()
           throws IOException
Closes this input stream.

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

Note that if this is a multi part message, then the first part is closed.

Overrides:
close in class InputStream
Throws:
IOException - If an I/O error occurs.

getContentDescription

public String getContentDescription()
Retrieves content description for this part.

Returns:
Content description for this part, or null if content not description present.

getContentEncoding

public String getContentEncoding()
Retrieves this part's content encoding.

Returns:
Content encoding used on this part's body; if no encoding specified (or if the data is decoded internally) this method returns null.

getContentID

public String getContentID()
Retrieves this part's content ID.

Returns:
Content ID for this part, or null if content ID not present.

getContentType

public String getContentType()
Retrieves this part's content type.

Returns:
Content type for this part (for example, "text/plain"); if no content type specified, then this method returns "text/plain".

getContentTypeParameter

public String getContentTypeParameter(String attribute)
Retrieves content type pararmeter by attribute.

Parameters:
attribute - Content type attribute key to look for.
Returns:
Parameter value for specified content type attribute, or null if no value found.

getHeader

public String getHeader(String headerFieldName)
Retrieve header content for named header. Note that the values have been converted to lower case.

Invoke this method to retrieve the header content for a particular header. For example, given this header

  Content-Type: text/plain; boundary=111
 
invoking this method as getHeader("Content-Type") retrieves the string "text/plain; boundary=111".
Parameters:
headerFieldName - Header name for which to retrieve the content.
Returns:
Content for named header.

getHeaders

public Enumeration getHeaders()
Retrieves enumeration of MIME headers. Note that the values have been converted to lower case.

Invoke this method to retrieve an enumeration of the headers found in this MIME part, including the "Content-Type", "Content-ID", etc. in addition to any extension fields. Also note that

Returns:
Headers in this MIME part.

getParts

public MIMEInputStream[] getParts()
Retrieves all parts in this multi-part message.

Invoke this method on a multi-part message to retrieve each contained part in a MIME input stream of its own.

Returns:
Array containing all the parts in this multi-part message; if this message is not a multi-part message, this method returns null. If this message is multi-part, but the data is cut off to early, then this will be an array of length 0.

getRawMIMEInputStream

public SharedInputStream getRawMIMEInputStream()
Retrieves entire MIME part including headers.

Invoke this method to retrieve this entire MIME part, including headers, in a shared input stream.

Returns:
Entire MIME part.

isMultiPart

public boolean isMultiPart()
Determines if this is a multi-part message.

Returns:
True if this message contains more than one MIME part; otherwise, false.

isPartComplete

public int isPartComplete()
Determines whether the entire contents of this MIME Part was read in or whether it was cutoff early.

Returns:
A ternary value depending on the context. If the entire part is present ( which can be determined if the final boundary was read, then 1 is returned. If the part is cut-off and we can determine that, then 0 is returned. If we aren't sure, because there are no boundaries around the part, then -1 is returned.
Since:
JDE 4.0.0

read

public int read()
         throws IOException
Reads one byte from this stream.

Invoke this method read one byte from this stream. Note that if this stream contains a multi-part message, this method reads the byte out of the first part.

This method blocks until input data is available, the end of the stream is detected (and then returns -1), or an exception is thrown.

Overrides:
read in class InputStream
Returns:
Byte of data, or -1 if no more data in this stream.
Throws:
IOException - If an I/O error occurs.

read

public int read(byte[] buffer)
         throws IOException
Reads some bytes from this stream.

Invoke this method to attempt to fill a provided output parameter byte array with data from this stream. Note that if this stream contains a multi-part message, this method reads bytes out of the first part.

Overrides:
read in class InputStream
Parameters:
buffer - Buffer to contain data.
Returns:
Actual number of bytes read from this stream; if no more data was available when you invoked this method, it returns -1.
Throws:
IOException - If an I/O error occurs.

read

public int read(byte[] buffer,
                int offset,
                int length)
         throws IOException
Read specified number of bytes from this stream.

Invoke this method to read some bytes from this stream. Note that if this stream contains a multi-part message, this method reads bytes out of the first part.

Overrides:
read in class InputStream
Parameters:
buffer - Buffer to contain data; must be large enough to contain desired number of bytes.
offset - First element in output parameter buffer at which to begin writing data; if not 0 then output parameter buffer must be at least offset + len elements long.
length - Number of bytes to read from this stream.
Returns:
Actual number of bytes read from this stream; if no more data was available when you invoked this method, it returns -1.
Throws:
IOException - If an I/O error occurs.

skip

public long skip(long n)
          throws IOException
Skips over some bytes in this stream.

Invoke this method to skip the read position over a specified number of bytes in this stream, discarding the skipped bytes.

Overrides:
skip in class InputStream
Parameters:
n - Number of bytes to skip; if negative, an IllegalArgumentException is thrown by the underlying SharedInputStream.
Returns:
Actual number of bytes skipped.
Throws:
IOException - Thrown if an I/O error occurs.



Copyright 1999-2008 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.