de.trantor.mail
Class MimeDecoder

java.lang.Object
  |
  +--de.trantor.mail.MimeDecoder

public class MimeDecoder

extends java.lang.Object

Is a helper class for decoding MIME data contained in e-mail messages. As the name implies, MimeDecoder allows a kind of read-only view of the MIME parts contained in a message, giving access to textual as well as binary content.

Every MimeDecoder works on and thus represents exactly one MIME part, which according to RFC 2045 - RFC 2049 may be either of the following two:

• A single-part, meaning that it's a leaf in the tree-like hierarchy of MIME parts. In this case content may be retrieved directly using the getBodyLine() or getBodyBytes() methods.
• A multi-part, meaning that it's an inner node in the hierarchy. In that case subordinate parts should be investigated. These parts may again be single-part as well as multi-part.

To start working with a MimeDecoder, a new instance has to be created for a given message, which results in a top-level MIME view of the message. Subordinate parts can then be accessed using the getPart() method that serves as a kind of factory method for MimeDecoders representing the lower MIME levels of the message.

Please note that a MimeDecoder is not notified of any changes to the underlying message it is working on, so changes to the message will make the MimeDecoder invalid. A new MimeDecoder should be created after changes have been applied. Otherwise the results are unpredictable and will most probably result in some kind of Exception.

One could argue that there should be a closer integration between the Message and the MimeDecoder classes that is able to handle these changes. The rationale for the given implementation is - again - memory savings. The MimeDecoder is actually an optional component that *can* be used on a Message if the application demands it. The Message class, on the other hand, is not dependent on the MimeDecoder at all, which means that the Message class can be deployed without having to deploy the MimeDecoder class, too.

A short note for implementators that want to understand the internal structure of the MimeDecoder class: The basic idea is that the MimeDecoder holds a direct reference to the message's Vector of lines (both header and body) as well as two integer fields telling where the part represented by the MimeDecoder starts and ends. In case of multi-parts, an additonal Vector holds all the occurences of the part boundary string, which makes it quite easy to create additional MimeDecoders for the subordinate MIME parts.

See Also:

Message, MimeDecoder(Message), getBodyLine(int), getBodyBytes(), getPart(int)

Constructor Summary

MimeDecoder(Message message)
Creates a new MimeDecoder for a given message.

Method Summary

byte[]	getBodyBytes() Returns the binary data contained in this MIME part.
java.lang.String	getBodyLine(int index) Returns a line of this MIME part's body its index.
int	getBodyLineCount() Returns the number of lines in this MIME part's body.
java.lang.String	getEncoding() Returns the encoding of this MIME part, which is deduced from the "Content-Transfer-Encoding:" header field.
java.lang.String	getName() Returns the filename of this MIME part, which is deduced from the "name=" sub-field of the "Content-Type:" header field.
MimeDecoder	getPart(int index) Returns a subordinate part of this MIME part.
int	getPartCount() Returns the number of MIME parts that constitute this MIME part.
static java.lang.String	getStringName(java.lang.String s) Returns the name contained in a name/value pair string.
static java.lang.String	getStringValue(java.lang.String s) Returns the value contained in a name/value pair string.
java.lang.String	getType() Returns the type of this MIME part, which is deduced from the "Content-Type:" header field.

Methods inherited from class java.lang.Object

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

Constructor Detail

MimeDecoder

public MimeDecoder(Message message)

Creates a new MimeDecoder for a given message. This constructor returns a new instance of the MimeDecoder class that grants access to a top-level MIME view of the message. Depending on the value returned by the getType() method, the message contains only this part -- in which case it can be accessed by the getBodyLine() or getBodyBytes() methods --, or it is constructed from a number of subordinate MIME parts which can be accessed one by one using the getPart() method.

See Also:

getBodyLine(int), getBodyBytes()

Method Detail

getBodyLineCount

public int getBodyLineCount()

Returns the number of lines in this MIME part's body.

See Also:

getBodyLine(int), getBodyBytes()

getBodyLine

public java.lang.String getBodyLine(int index)
                             throws java.lang.ArrayIndexOutOfBoundsException

Returns a line of this MIME part's body its index.

java.lang.ArrayIndexOutOfBoundsException

See Also:

getBodyLineCount(), getBodyBytes()

getBodyBytes

public byte[] getBodyBytes()

Returns the binary data contained in this MIME part. This method should only be invoked on MIME parts whose encoding is "base64", otherwise the result will be more or less arbitrary.

getPartCount

public int getPartCount()

Returns the number of MIME parts that constitute this MIME part. If the result is zero, this MIME part is a leaf in the tree-like hierarchy of MIME parts, and its contents can be retrieved by either the getBodyLine() or the getBodyBytes() methods. Otherwise the part is an inner node in the part hierarchy, and contains one or more subordinate MIME parts which can be accessed using the getPart() method.

getPart

public MimeDecoder getPart(int index)

Returns a subordinate part of this MIME part. This method should only be called if the getPartCount() method returns a value greater than zero, meaning that this MIME part is an inner node in the hierarchy of parts and has one ore more subordinate MIME parts. Note that this method acts as some kind of factory method for MimeDecoders that do not work on the top-level of a message, so the MimeDecoder objects are created on-demand and do not pollute the limited J2ME heap if they're not really needed.

getType

public java.lang.String getType()

Returns the type of this MIME part, which is deduced from the "Content-Type:" header field. Frequent header types that do work well in a J2ME environment are "text/plain", which means plain ASCII text, and "image/png" which means that the part holds a PNG image, probably encoded in base64 (the latter information can be retrieved by the getEncoding() method).

See Also:

getEncoding(), getName()

getName

public java.lang.String getName()

Returns the filename of this MIME part, which is deduced from the "name=" sub-field of the "Content-Type:" header field. This value will probably only hold a non-null value for binary attachments, for example images.

See Also:

getType(), getEncoding()

getEncoding

public java.lang.String getEncoding()

Returns the encoding of this MIME part, which is deduced from the "Content-Transfer-Encoding:" header field. The encoding tells us how data is to be retrieved from the MIME part. If the value is null, the part's contents can be retrieved line by line using the getBodyLine() method. If the encoding is "base64", the part's data should be retrieved using the getBodyBytes() method. Other encodings are currently not supported by the MimeDecoder itself.

getStringName

public static java.lang.String getStringName(java.lang.String s)

Returns the name contained in a name/value pair string. The name is everything up to, but not including, the first "=" sign in the string. If no "=" can be found, null is returned, assuming the string doesn't hold a name at all.

Note that this method is different from the getStringName() method of the Message class due to the different separator character.

See Also:

getStringValue(java.lang.String), Message.getStringName(java.lang.String)

getStringValue

public static java.lang.String getStringValue(java.lang.String s)

Returns the value contained in a name/value pair string. The value is everything following, but not including, the first "=" sign in the string. If no "=" can be found, the whole string is returned, assuming it holds only a value, but not name at all. The method unquotes values enclosed in double quotes automatically.

Note that this method is different from the getStringValue() method of the Message class due to the different separator character.

See Also:

getStringName(java.lang.String), Message.getStringValue(java.lang.String)