org.apache.mailet
Interface Mail

All Superinterfaces:
java.lang.Cloneable, java.io.Serializable

public interface Mail
extends java.io.Serializable, java.lang.Cloneable

Wraps a MimeMessage with additional routing and processing information.

This includes

The Mail interface also defines constants for special processor names, such as "root" and "error".

Mail Attributes

While processing a Mail instance, a Mailet can associate additional information with it by using mail attributes. These attributes can then be queried by the same mailet or other mailets later on.

Some containers may also use attributes to provide envelope information.

Every attribute consists of a name and a value. Attribute names should follow the same convention as package names. The Mailet API specification reserves names matching org.apache.james.* and org.apache.mailet.*.

Attribute values can be arbitrary objects, but since Mail is Serializable, the attribute value must be Serializable as well.

The list of attributes which are currently associated with a Mail instance can be retrieved using the getAttributeNames() method, and given its name, the value of an attribute can be retrieved using the getAttribute(java.lang.String) method. It is also possible to remove one attribute or all attributes of a Mail instance.


Field Summary
static java.lang.String DEFAULT
           
static java.lang.String ERROR
           
static java.lang.String GHOST
           
static java.lang.String TRANSPORT
           
 
Method Summary
 java.io.Serializable getAttribute(java.lang.String name)
          Returns the value of the named Mail instance attribute, or null if the attribute does not exist.
 java.util.Iterator getAttributeNames()
          Returns an Iterator over the names of all attributes which are set in this Mail instance.
 java.lang.String getErrorMessage()
          The error message, if any, associated with this message.
 java.util.Date getLastUpdated()
          Returns the time at which this Mail was last updated.
 javax.mail.internet.MimeMessage getMessage()
          Returns the MimeMessage stored in this message.
 long getMessageSize()
          Returns the message size (including headers).
 java.lang.String getName()
          Returns the name of this message.
 java.util.Collection getRecipients()
          Returns the message recipients as a Collection of MailAddress objects, as specified by the SMTP "RCPT TO" command, or internally defined.
 java.lang.String getRemoteAddr()
          Returns the IP address of the remote server that sent this message.
 java.lang.String getRemoteHost()
          Returns the host name of the remote server that sent this message.
 MailAddress getSender()
          Returns the sender of the message, as specified by the SMTP "MAIL FROM" command, or internally defined.
 java.lang.String getState()
          Returns the current state of the message, such as GHOST, ERROR or DEFAULT.
 boolean hasAttributes()
          Returns whether this Mail instance has any attributes set.
 void removeAllAttributes()
          Removes all attributes associated with this Mail instance.
 java.io.Serializable removeAttribute(java.lang.String name)
          Removes the attribute with the given name from this Mail instance.
 java.io.Serializable setAttribute(java.lang.String name, java.io.Serializable object)
          Associates an attribute with the given name and value with this Mail instance.
 void setErrorMessage(java.lang.String msg)
          Sets the error message associated with this message.
 void setLastUpdated(java.util.Date lastUpdated)
          Sets the time at which this Mail was last updated.
 void setMessage(javax.mail.internet.MimeMessage message)
          Sets the MimeMessage wrapped by this Mail instance.
 void setName(java.lang.String newName)
          Set the name of this message.
 void setRecipients(java.util.Collection recipients)
          Sets the message recipients as a Collection of MailAddress objects.
 void setState(java.lang.String state)
          Sets the state of this message.
 

Field Detail

GHOST

static final java.lang.String GHOST
See Also:
Constant Field Values

DEFAULT

static final java.lang.String DEFAULT
See Also:
Constant Field Values

ERROR

static final java.lang.String ERROR
See Also:
Constant Field Values

TRANSPORT

static final java.lang.String TRANSPORT
See Also:
Constant Field Values
Method Detail

getName

java.lang.String getName()
Returns the name of this message.

Returns:
the message name
Since:
Mailet API v2.3

setName

void setName(java.lang.String newName)
Set the name of this message.

Parameters:
newName - the new message name
Since:
Mailet API v2.3

getMessage

javax.mail.internet.MimeMessage getMessage()
                                           throws javax.mail.MessagingException
Returns the MimeMessage stored in this message.

Returns:
the MimeMessage that this Mail object wraps
Throws:
javax.mail.MessagingException - when an error occurs while retrieving the message

getRecipients

java.util.Collection getRecipients()
Returns the message recipients as a Collection of MailAddress objects, as specified by the SMTP "RCPT TO" command, or internally defined.

Returns:
a Collection of MailAddress objects that are recipients of this message

setRecipients

void setRecipients(java.util.Collection recipients)
Sets the message recipients as a Collection of MailAddress objects.

Parameters:
recipients - the message recipients as a Collection of MailAddress Objects
Since:
Mailet API v2.4

getSender

MailAddress getSender()
Returns the sender of the message, as specified by the SMTP "MAIL FROM" command, or internally defined.

Returns:
the sender of this message

getState

java.lang.String getState()
Returns the current state of the message, such as GHOST, ERROR or DEFAULT.

Returns:
the state of this message

getRemoteHost

java.lang.String getRemoteHost()
Returns the host name of the remote server that sent this message.

Returns:
the host name of the remote server that sent this message

getRemoteAddr

java.lang.String getRemoteAddr()
Returns the IP address of the remote server that sent this message.

Returns:
the IP address of the remote server that sent this message

getErrorMessage

java.lang.String getErrorMessage()
The error message, if any, associated with this message.

Returns:
the error message associated with this message, or null

setErrorMessage

void setErrorMessage(java.lang.String msg)
Sets the error message associated with this message.

Parameters:
msg - the error message

setMessage

void setMessage(javax.mail.internet.MimeMessage message)
Sets the MimeMessage wrapped by this Mail instance.

Parameters:
message - the new message that this Mail instance will wrap

setState

void setState(java.lang.String state)
Sets the state of this message.

Parameters:
state - the new state of this message

getAttribute

java.io.Serializable getAttribute(java.lang.String name)
Returns the value of the named Mail instance attribute, or null if the attribute does not exist.

Parameters:
name - the attribute name
Returns:
the attribute value, or null if the attribute does not exist
Since:
Mailet API v2.1

getAttributeNames

java.util.Iterator getAttributeNames()
Returns an Iterator over the names of all attributes which are set in this Mail instance.

The getAttribute(java.lang.String) method can be called to retrieve an attribute's value given its name.

Returns:
an Iterator (of Strings) over all attribute names
Since:
Mailet API v2.1

hasAttributes

boolean hasAttributes()
Returns whether this Mail instance has any attributes set.

Returns:
true if this Mail instance has any attributes set, false if not
Since:
Mailet API v2.1

removeAttribute

java.io.Serializable removeAttribute(java.lang.String name)
Removes the attribute with the given name from this Mail instance.

Parameters:
name - the name of the attribute to be removed
Returns:
the value of the removed attribute, or null if there was no such attribute (or if the attribute existed and its value was null)
Since:
Mailet API v2.1

removeAllAttributes

void removeAllAttributes()
Removes all attributes associated with this Mail instance.

Since:
Mailet API v2.1

setAttribute

java.io.Serializable setAttribute(java.lang.String name,
                                  java.io.Serializable object)
Associates an attribute with the given name and value with this Mail instance. If an attribute with the given name already exists, it is replaced, and the previous value is returned.

Conventionally, attribute names should follow the namespacing guidelines for Java packages. The Mailet API specification reserves names matching org.apache.james.* and org.apache.mailet.*.

Parameters:
name - the attribute name
object - the attribute value
Returns:
the value of the previously existing attribute with the same name, or null if there was no such attribute (or if the attribute existed and its value was null)
Since:
Mailet API v2.1

getMessageSize

long getMessageSize()
                    throws javax.mail.MessagingException
Returns the message size (including headers).

This is intended as a guide suitable for processing heuristics, and not a precise indication of the number of outgoing bytes that would be produced were the email to be encoded for transport. In cases where an exact value is not readily available or is difficult to determine (for example, when the fully transfer encoded message is not available) a suitable estimate may be returned.

Returns:
the message size
Throws:
javax.mail.MessagingException - when the size cannot be retrieved
Since:
Mailet API v2.3

getLastUpdated

java.util.Date getLastUpdated()
Returns the time at which this Mail was last updated.

Returns:
the time at which this Mail was last updated
Since:
Mailet API v2.3

setLastUpdated

void setLastUpdated(java.util.Date lastUpdated)
Sets the time at which this Mail was last updated.

Parameters:
lastUpdated - the time at which this Mail was last modified
Since:
Mailet API v2.3


Copyright © 2007-2009 The Apache Software Foundation. All Rights Reserved.