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:

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:

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