com.sssw.srv.mail
Class AgoMailMessage

java.lang.Object
 |
 +--com.sssw.srv.mail.AgoMailMessage

public class AgoMailMessage

extends Object

Provides a simple API to access a received email message. Provides methods to access the commonly used hearders of ASCII and MIME email, and to access file attachments in MIME messages.

For a detailed inspection of MIME messages, call the getMIMEPart() method to get an AgoMIMEPart object representing the mail message. The AgoMIMEPart object provides access to everything in the message.

Constructor Summary

AgoMailMessage(AgoMIMEPart message)
The constructor for the AgoMailMessage class.

Method Summary

Enumeration	fieldBccElements() Returns an Enumeration of the bcc field of the mail message.
Enumeration	fieldCcElements() Returns an Enumeration of the cc field of the mail message.
String	fieldDate() Returns the Date field of the message or null if there is no Date field.
AgoMailAddressMailbox	fieldFrom() Returns the From field of the message or null if there is no From field.
Enumeration	fieldFromElements() Returns an Enumeration of the From field of the message.
String	fieldMessageID() Returns the MessageID field of the message or null if there is no MessageID field.
String	fieldOrganization() Returns the Organization field of the message or null if there is no Organizatin field.
Enumeration	fieldReplyToElements() Returns an Enumeration of the Reply-To field of the message.
AgoMailAddressMailbox	fieldSender() Returns the Sender field of the message or null if there is no Sender field.
String	fieldSubject() Returns the Subject field of the message or null if there is no Subject.
Enumeration	fieldToElements() Returns an Enumeration of the To field of the message.
Enumeration	fileAttachments() Returns an Enumeration of AgoFileAttachmentInputStream objects for the file attachments.
AgoMIMEPart	getMIMEPart() Returns an AgoMIMEPart object that represents the entire message.
String	messageText() Attempts to return the body of the message as a String.

Methods inherited from class java.lang.Object

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

Constructor Detail

AgoMailMessage

public AgoMailMessage(AgoMIMEPart message)

The constructor for the AgoMailMessage class.

Parameters:

message - the email message.

Method Detail

getMIMEPart

public AgoMIMEPart getMIMEPart()

Returns an AgoMIMEPart object that represents the entire message.

Usage:

Use this method to examine in detail the message headers or any of the parts of a MIME message. If the message is a multipart message, the AgoMIMEPart returned is in the form of a tree structure with subparts.

Example:

     AgoMIMEPart mimePart = msg.getMIMEPart();
 

fieldSubject

public String fieldSubject()

Returns the Subject field of the message or null if there is no Subject.

Example:

     String subject = msg.fieldSubject();
 

fieldDate

public String fieldDate()

Returns the Date field of the message or null if there is no Date field.

Usage:

The returned date is in String form as it is found in the message. It is not a Date object.

Example:

     String dt = msg.fieldDate();
 

fieldFrom

public AgoMailAddressMailbox fieldFrom()

Returns the From field of the message or null if there is no From field. The value is returned as an AgoMailAddressMailbox. The AgoMailAddressMailbox methods access the name and address parts of the From field.

Usage:

It is possible to have more than one From address in a message. This method returns only the first one. The fieldFromElements() method can be used to see all the From addresses.

Example:

     AgoMailAddressMailbox from = msg.fieldFrom();
 

See Also:

AgoMailMessage.fieldFromElements()

fieldFromElements

public Enumeration fieldFromElements()

Returns an Enumeration of the From field of the message. The Enumeration consists of AgoMailAddressMailbox objects. If there is no From field, an empty Enumeration is returned.

Usage:

Normally a From field contains a single mailbox. It is possible, however, for a Sender to be specified, and for a message to include multiple From entries. In a conforming RFC 822 message, if there is more than one From address, there must be a Sender field.

Example:

     Enumeration from = msg.fieldFromElements();
     while (from.hasMoreElements()) {
         AgoMailAddressMailbox mb = (AgoMailAddressMailbox)from.nextElement();
         // work with mailbox mb here
     }
 

fieldSender

public AgoMailAddressMailbox fieldSender()

Returns the Sender field of the message or null if there is no Sender field. The value is returned as an AgoMailAddressMailbox. The AgoMailAddressMailbox provides methods to access the name and address parts of the Sender field.

Usage:

The Sender field is not commonly used and is often confused with the From field. The From field is used to describe the author of the message. The sender should describe who actually sent the message. The author and the sender are usually the same person. However, they would be different in the case of an assistant sending mail for a boss, or a group of people authoring a message which is obviously sent by just one member of the group. When a Sender is specified, it is possible for the message to have multiple entries in the From field (as specified in RFC 822). The AgoMailMessage.fieldFromElements() method exists for this uncommon situation.

Example:

     AgoMailAddressMailbox sender = msg.fieldSender();
 

fieldReplyToElements

public Enumeration fieldReplyToElements()

Returns an Enumeration of the Reply-To field of the message. The Enumeration consists of AgoMailAddressMailbox objects. If there is no Reply-To field, an empty Enumeration is returned.

Example:

     Enumeration replyTo = msg.fieldReplyToElements();
     while (replyTo.hasMoreElements()) {
         AgoMailAddressMailbox mb = (AgoMailAddressMailbox)replyTo.nextElement();
         // work with mailbox mb here
     }
 

fieldToElements

public Enumeration fieldToElements()

Returns an Enumeration of the To field of the message. The Enumeration consists of AgoMailAddressMailbox objects. If there is no To field, an empty Enumeration is returned.

Example:

     Enumeration to = msg.fieldToElements();
     while (to.hasMoreElements()) {
         AgoMailAddressMailbox mb = (AgoMailAddressMailbox)to.nextElement();
         // work with mailbox mb here
     }
 

fieldCcElements

public Enumeration fieldCcElements()

Returns an Enumeration of the cc field of the mail message. The Enumeration consists of AgoMailAddressMailbox objects. If there is no cc field, an empty Enumeration is returned.

Example:

     Enumeration cc = msg.fieldCcElements();
     while (cc.hasMoreElements()) {
         AgoMailAddressMailbox mb = (AgoMailAddressMailbox)cc.nextElement();
         // work with mailbox mb here
     }
 

fieldBccElements

public Enumeration fieldBccElements()

Returns an Enumeration of the bcc field of the mail message. The Enumeration consists of AgoMailAddressMailbox objects. If there is no Bcc field, an empty Enumeration is returned.

Usage:

For a conforming RFC 822 message, the fieldBccElements always returns an empty Enumeration since mail should never be received with a Bcc field still in it.

Example:

     Enumeration bcc = msg.fieldBccElements();
     while (bcc.hasMoreElements()) {
         AgoMailAddressMailbox mb = (AgoMailAddressMailbox)bcc.nextElement();
         // work with mailbox mb here
     }
 

fieldMessageID

public String fieldMessageID()

Returns the MessageID field of the message or null if there is no MessageID field.

Usage:

The MessageID is a long string which is unique to each message. It is of no interest unless except to track message threads and messages that reference other messages.

Example:

     String mesgID = msg.fieldMessageID();
 

fieldOrganization

public String fieldOrganization()

Returns the Organization field of the message or null if there is no Organizatin field.

Example:

     String org = msg.fieldOrganization();
 

messageText

public String messageText()
                   throws IOException

Attempts to return the body of the message as a String.

Usage:

This method might be used to parse the text of a message to take some action based on the contents, for example, to look for a SUBSCRIBE command. But there are many formats of mail. It might be a plain ASCII message, it might be a MIME message with a single text/plain part. It is increasingly common to receive mail which is a multipart/alternative with a text/html and a text/plain part. This method returns a String representing the body of the message in plain text.

The messageText() method uses the following algorithm:

• If the message is in plain ASCII, then the entire body is returned.
• If the message consists of a single text/plain part, then its contents are returned.
• If the message is a multipart, then the first text/plain part is returned.
• If the message is none of the above, or there is no text/plain part found in a multipart message, null is returned.

Example:

     String msgText = msg.messageText();
 

fileAttachments

public Enumeration fileAttachments()
                            throws IOException

Returns an Enumeration of AgoFileAttachmentInputStream objects for the file attachments.

Usage:

File attachments returned by this method are defined as follows: If the message is of Content-Type application, the whole message is considered an attachment. If this is a multipart message, then any part that is an application, or has a Content-Disposition header whose value is attachment, is considered an attachment. This applies only to the top level of the message. attachments.

Example:

     Enumeration attachments = msg.fileAttachments();