de.trantor.mail
Class Message

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

public class Message

extends java.lang.Object

Represents an internet mail message according to RFC 822. From the user's point of view, the class basically consists of two parts:

• An array-like structure holding the message's header lines. Each header line is stored in the textual format that is also used during transmission. To make access to the header data convenient, there are several methods for dealing with header lines as a whole, with names and fields separately and for searching specific header fields.
• An array-like structure holding the message's body lines. Again, several methods are provided to manipulate the body part of the message.

From the classes' internal point of view, both array-like structures are held in a single Vector instance to save memory.

One could argue that the fully textual representation of a message results in a slower operation than would be possible with - for example - a hashtable. This is true, but the representation has been chosen with regard to several concerns:

• The limited memory of J2ME devices. The textual representation requires a lot less memory than a data structure separating field names and field values would.
• The principal of minimal mangling. This principle dictates that a system (possibly) responsible for e-mail transfer (a mailing list processor, for example) should keep changes to the messages to a minimum. We're trying to adhere to this principle in order to not limit the possible applications of the Mail4ME package. Since the internal representation of an e-mail inside a Message instance is equal to the external one, there is no mangling at all, as long as the message header or body is not modified on purpose. Note that this would not be the case if the headers were kept in, say, a hashtable, because it would be complicated to reconstruct the original order of the header fields when converting the message to the external representation again.

Messages can be retrieved from a POP3 server using the Pop3Client class. They can be sent across the Internet using an instance of SmtpClient. Depending on the application, it might be necessary to enclose the message in an Envelope instance before sending it.

See Also:

Pop3Client, SmtpClient, Envelope

Constructor Summary

Message()
Contructs a new, totally empty message.

Message(java.lang.String from, java.lang.String to, java.lang.String subject)
Contructs a new message with the given sender ("From:" field), recipient ("To:" field) and subject, respectively.

Method Summary

int	addBodyLine(java.lang.String line) Adds a line to the message body, returning its index.
int	addHeaderLine(java.lang.String line) Adds a new line to the end of the message's header, returning its index.
java.lang.String[]	getAllHeaderValues(java.lang.String name) Returns the values of all occurences of the given header field in the this message.
java.lang.String	getBodyLine(int index) Returns a line of the message's body by its index.
int	getBodyLineCount() Returns the number of lines in the message's body.
static java.lang.String	getCanonicalDate(java.util.Calendar calendar, java.util.TimeZone timezone) Returns a formatted date.
static java.lang.String	getDisplayAddress(java.lang.String address) Returns the human-readable part of an address, that is, the part that usually holds the real-life name of a user.
int	getHeaderIndex(java.lang.String name) Searches for a header field.
int	getHeaderIndex(java.lang.String name, int startIndex) Searches for a header field.
java.lang.String	getHeaderLine(int index) Returns one of the message's header lines by its index.
int	getHeaderLineCount() Returns the number of available header lines.
java.lang.String	getHeaderName(int index) Returns the field name one of the given header line.
java.lang.String	getHeaderValue(int index) Returns the field value one of the given header line.
java.lang.String	getHeaderValue(java.lang.String name) Returns the value of the first occurence of the given header field.
java.lang.String	getHeaderValue(java.lang.String name, java.lang.String def) Returns the value of the first occurence of the given header field.
static java.lang.String	getMachineAddress(java.lang.String address) Returns the machine-readable part of an address, that is, the part that is actually used in delivering the message to a recipient.
static java.lang.String	getRandomString() Returns a random string.
static java.lang.String[]	getStringElements(java.lang.String list, char separator) Splits a list of elements into a String array.
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.
void	insertBodyLine(int index, java.lang.String line) Inserts a new line into the message's body, at the given index.
void	insertHeaderLine(int index, java.lang.String line) Inserts a new line at a given position into the message's header.
void	removeBodyLine(int index) Removes a line from the message's body.
void	removeHeaderLine(int index) Removes a complete header line.
void	setBodyLine(int index, java.lang.String line) Replaces the line of the message's body at the given index.
void	setHeaderLine(int index, java.lang.String line) Replaces the given header line by a new one.
void	setHeaderValue(java.lang.String name, java.lang.String value) Sets a header field to a given value.

Methods inherited from class java.lang.Object

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

Constructor Detail

Message

public Message()

Contructs a new, totally empty message.

See Also:

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

Message

public Message(java.lang.String from,
               java.lang.String to,
               java.lang.String subject)

Contructs a new message with the given sender ("From:" field), recipient ("To:" field) and subject, respectively. If any of the parameters is null, the corresponding field is not added to the message. The method ensures that the newly created message gets a message ID and a date field holding the current date/time.

See Also:

Message()

Method Detail

getHeaderLine

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

Returns one of the message's header lines by its index.

java.lang.ArrayIndexOutOfBoundsException

See Also:

addHeaderLine(java.lang.String), getHeaderLineCount(), setHeaderLine(int, java.lang.String), insertHeaderLine(int, java.lang.String), removeHeaderLine(int)

getHeaderName

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

Returns the field name one of the given header line. The field name is everything up to, but not including the first ':' of the line. If the given header line does not contain a ':' character at all, the line is assumed not to hold a correct header field, and null is returned instead.

java.lang.ArrayIndexOutOfBoundsException

See Also:

getHeaderValue(int), getHeaderValue(java.lang.String), getHeaderValue(java.lang.String, java.lang.String), getAllHeaderValues(java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String), getHeaderIndex(java.lang.String, int)

getHeaderValue

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

Returns the field value one of the given header line. The field value is everything that follows the first ':' of the line. Leading and trailing spaces are removed. If the given header line does not contain a ':' character at all, the line is assumed to hold a nameless value, and the whole line is returned instead.

java.lang.ArrayIndexOutOfBoundsException

See Also:

getHeaderName(int), getHeaderValue(java.lang.String), getHeaderValue(java.lang.String, java.lang.String), getAllHeaderValues(java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String), getHeaderIndex(java.lang.String, int)

getHeaderIndex

public int getHeaderIndex(java.lang.String name,
                          int startIndex)

Searches for a header field. The method returns the index of the first header line that contains the given field name, and it starts searching from the given index. If the header field can't be found, -1 is returned instead.

See Also:

getHeaderName(int), getHeaderValue(int), getHeaderValue(java.lang.String), getHeaderValue(java.lang.String, java.lang.String), getAllHeaderValues(java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String)

getHeaderIndex

public int getHeaderIndex(java.lang.String name)

Searches for a header field. The method returns the index of the first header line that contains the given field name, and it starts searching from the first header line. If the header field can't be found, -1 is returned instead.

See Also:

getHeaderName(int), getHeaderValue(int), getHeaderValue(java.lang.String), getHeaderValue(java.lang.String, java.lang.String), getAllHeaderValues(java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String, int)

getHeaderValue

public java.lang.String getHeaderValue(java.lang.String name)

Returns the value of the first occurence of the given header field. If the field doesn't exist, null is returned instead.

See Also:

getHeaderName(int), getHeaderValue(int), getHeaderValue(java.lang.String, java.lang.String), getAllHeaderValues(java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String), getHeaderIndex(java.lang.String, int)

getHeaderValue

public java.lang.String getHeaderValue(java.lang.String name,
                                       java.lang.String def)

Returns the value of the first occurence of the given header field. If the field does not exist at all, the specified default value is returned instead.

See Also:

getHeaderName(int), getHeaderValue(int), getHeaderValue(java.lang.String), getAllHeaderValues(java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String), getHeaderIndex(java.lang.String, int)

getAllHeaderValues

public java.lang.String[] getAllHeaderValues(java.lang.String name)

Returns the values of all occurences of the given header field in the this message. The results are stored in a string array. If the given field doesn't exist at all, an empty array is returned.

See Also:

getHeaderName(int), getHeaderValue(int), getHeaderValue(java.lang.String), getHeaderValue(java.lang.String, java.lang.String), setHeaderValue(java.lang.String, java.lang.String), getHeaderIndex(java.lang.String), getHeaderIndex(java.lang.String, int)

setHeaderLine

public void setHeaderLine(int index,
                          java.lang.String line)

Replaces the given header line by a new one.

See Also:

addHeaderLine(java.lang.String), getHeaderLineCount(), getHeaderLine(int), insertHeaderLine(int, java.lang.String), removeHeaderLine(int)

getHeaderLineCount

public int getHeaderLineCount()

Returns the number of available header lines.

See Also:

addHeaderLine(java.lang.String), getHeaderLine(int), setHeaderLine(int, java.lang.String), insertHeaderLine(int, java.lang.String), removeHeaderLine(int)

addHeaderLine

public int addHeaderLine(java.lang.String line)

Adds a new line to the end of the message's header, returning its index.

See Also:

getHeaderLineCount(), getHeaderLine(int), setHeaderLine(int, java.lang.String), insertHeaderLine(int, java.lang.String), removeHeaderLine(int)

insertHeaderLine

public void insertHeaderLine(int index,
                             java.lang.String line)

Inserts a new line at a given position into the message's header.

See Also:

addHeaderLine(java.lang.String), getHeaderLineCount(), getHeaderLine(int), setHeaderLine(int, java.lang.String), removeHeaderLine(int)

removeHeaderLine

public void removeHeaderLine(int index)

Removes a complete header line.

See Also:

addHeaderLine(java.lang.String), getHeaderLineCount(), getHeaderLine(int), setHeaderLine(int, java.lang.String), insertHeaderLine(int, java.lang.String)

setHeaderValue

public void setHeaderValue(java.lang.String name,
                           java.lang.String value)

Sets a header field to a given value. This method changes the first occurence of the given header field to the given value. If the field doesn't exist in the message's header, it is appended as a new header line. If the value parameter is null, an attempt is made to remove the given field from the header.

See Also:

getHeaderName(int), getHeaderValue(int), getHeaderValue(java.lang.String), getHeaderValue(java.lang.String, java.lang.String), getAllHeaderValues(java.lang.String), getHeaderIndex(java.lang.String), getHeaderIndex(java.lang.String, int)

getBodyLine

public java.lang.String getBodyLine(int index)

Returns a line of the message's body by its index.

See Also:

getBodyLineCount(), setBodyLine(int, java.lang.String), addBodyLine(java.lang.String), removeBodyLine(int), insertBodyLine(int, java.lang.String)

setBodyLine

public void setBodyLine(int index,
                        java.lang.String line)

Replaces the line of the message's body at the given index.

See Also:

getBodyLine(int), getBodyLineCount(), addBodyLine(java.lang.String), removeBodyLine(int), insertBodyLine(int, java.lang.String)

getBodyLineCount

public int getBodyLineCount()

Returns the number of lines in the message's body.

See Also:

getBodyLine(int), setBodyLine(int, java.lang.String), addBodyLine(java.lang.String), removeBodyLine(int), insertBodyLine(int, java.lang.String)

addBodyLine

public int addBodyLine(java.lang.String line)

Adds a line to the message body, returning its index.

See Also:

getBodyLine(int), getBodyLineCount(), setBodyLine(int, java.lang.String), removeBodyLine(int), insertBodyLine(int, java.lang.String)

insertBodyLine

public void insertBodyLine(int index,
                           java.lang.String line)

Inserts a new line into the message's body, at the given index.

See Also:

getBodyLine(int), getBodyLineCount(), setBodyLine(int, java.lang.String), addBodyLine(java.lang.String), removeBodyLine(int)

removeBodyLine

public void removeBodyLine(int index)

Removes a line from the message's body.

See Also:

getBodyLine(int), getBodyLineCount(), setBodyLine(int, java.lang.String), addBodyLine(java.lang.String), insertBodyLine(int, java.lang.String)

getMachineAddress

public static java.lang.String getMachineAddress(java.lang.String address)

Returns the machine-readable part of an address, that is, the part that is actually used in delivering the message to a recipient. For an address like, say,

   "Joerg Pleumann" <joerg@pleumann.de>
 

this would be "joerg@pleumann.de" (without the quotes).

getDisplayAddress

public static java.lang.String getDisplayAddress(java.lang.String address)

Returns the human-readable part of an address, that is, the part that usually holds the real-life name of a user. For an address like, say,

   "Joerg Pleumann" <joerg@pleumann.de>
 

this would be "Joerg Pleumann" (without the quotes).

getCanonicalDate

public static java.lang.String getCanonicalDate(java.util.Calendar calendar,
                                                java.util.TimeZone timezone)

Returns a formatted date. This method converts the given date/time/zone information into the textual format defined by RFC 822, that is, into a string looking like this:

   Mon, 01 Jan 1970 23:59:59 GMT+1000
 

If the timezone parameter is null, no zone information is appended to the result.

getStringElements

public static java.lang.String[] getStringElements(java.lang.String list,
                                                   char separator)

Splits a list of elements into a String array. The method takes a String holding a list of elements as well as a separator character. It splits the list with regard to the given separator and puts each element into a newly created String array. Occurences of the separator character enclosed in double quotes are not treated as separators. The method can be used to separate those message headers that hold several sub-attributes in one value (for example a list of recipients in one "From:" field or the various pieces of information stored in the "Content-Type:" field of a MIME message.

See Also:

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

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.

See Also:

getStringElements(java.lang.String, char), getStringValue(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.

See Also:

getStringElements(java.lang.String, char), getStringName(java.lang.String)

getRandomString

public static java.lang.String getRandomString()

Returns a random string. The method uses the system's millisecond timer and an additional random number to create a string that can serve as a basis for (hopefully) unique identifiers in messages or MIME parts. It is recommended to use this string in conjunction with another string that identifies the user or the user's system, for example an e-mail address or a hostname, to ensure uniqueness across machine boundaries.