org.apache.mailet
Interface MailetContext

public interface MailetContext

Defines a set of methods that can be used to interact with the mailet container. For example, it can be used to send a new message, to deliver a message locally, or to write to a log file.

Mailets and Matchers can retrieve a MailetContext through their respective MailetConfig and MatcherConfig objects, which are provided to them by the mailet container when they are initialized.

Mailet Context Attributes

The Mailet Context can provide additional configuration or other information not defined in this interface to Mailets and Matchers by using attributes. See your server documentation for information on the attributes it provides.

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.

The list of attributes which are currently associated with a mailet context 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.

Method Summary

void	bounce(Mail mail, java.lang.String message) Bounces the message using a standard format with the given message.
void	bounce(Mail mail, java.lang.String message, MailAddress bouncer) Bounces the message using a standard format with the given message.
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the named mailet context 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 mailet context.
java.util.Collection	getMailServers(java.lang.String domain) Returns the hostnames that are specified as mail handlers for the given domain name.
int	getMajorVersion() Returns the major version number of the Mailet API that this mailet container supports.
int	getMinorVersion() Returns the minor version number of the Mailet API that this mailet container supports.
MailAddress	getPostmaster() Returns the Postmaster address for this mailet context.
java.lang.String	getServerInfo() Returns the name and version of the mailet container on which the mailet is running.
java.util.Iterator	getSMTPHostAddresses(java.lang.String domain) Returns the SMTP host addresses specified as mail handlers for the given domain name.
boolean	isLocalEmail(MailAddress mailAddress) Checks if an address is local, i.e.
boolean	isLocalServer(java.lang.String hostname) Checks if a host name is local, i.e.
boolean	isLocalUser(java.lang.String userAccount) Deprecated. use isLocalEmail(MailAddress) instead
void	log(java.lang.String message) Writes the specified message to a mailet log.
void	log(java.lang.String message, java.lang.Throwable t) Writes the specified message to a mailet log, along with the stack trace of the given Throwable.
void	removeAttribute(java.lang.String name) Removes the attribute with the given name from this Mail instance.
void	sendMail(Mail mail) Sends an outgoing message to the top of this mailet container's root queue.
void	sendMail(MailAddress sender, java.util.Collection recipients, javax.mail.internet.MimeMessage message) Sends an outgoing message to the top of this mailet container's root queue.
void	sendMail(MailAddress sender, java.util.Collection recipients, javax.mail.internet.MimeMessage message, java.lang.String state) Sends an outgoing message to the top of this mailet container's queue for the specified processor.
void	sendMail(javax.mail.internet.MimeMessage message) Sends an outgoing message to the top of this mailet container's root queue.
void	setAttribute(java.lang.String name, java.lang.Object value) Associates an attribute with the given name and value with this mailet context.
void	storeMail(MailAddress sender, MailAddress recipient, javax.mail.internet.MimeMessage message) Deprecated. - use sparingly. Service will be replaced with resource acquired via JNDI.

Method Detail

getMajorVersion

int getMajorVersion()

Returns the major version number of the Mailet API that this mailet container supports. For example, if the mailet container supports version 1.2 of the Mailet API, this method returns 1.

Returns:

the major version number of the supported Mailet API

getMinorVersion

int getMinorVersion()

Returns the minor version number of the Mailet API that this mailet container supports. For example, if the mailet container supports version 1.2 of the Mailet API, this method returns 2.

Returns:

the minor version number of the supported Mailet API

getServerInfo

java.lang.String getServerInfo()

Returns the name and version of the mailet container on which the mailet is running.

The returned string is of the form <servername>/<versionnumber>, optionally followed by additional information in parentheses. For example, the JAMES mailet container may return the string "JAMES/1.2" or "JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86)".

Returns:

the server information string

getAttributeNames

java.util.Iterator getAttributeNames()

Returns an Iterator over the names of all attributes which are set in this mailet context.

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

getAttribute

java.lang.Object getAttribute(java.lang.String name)

Returns the value of the named mailet context 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

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.Object value)

Associates an attribute with the given name and value with this mailet context.

If an attribute with the given name already exists, it is replaced, and the previous value is returned.

Attribute names should follow the same convention as package names. The Mailet API specification reserves names matching org.apache.james.* and org.apache.mailet.*.

Parameters:

name - the attribute name

value - the attribute value

removeAttribute

void 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

Since:

Mailet API v2.1

log

void log(java.lang.String message)

Writes the specified message to a mailet log. The name and type of the mailet log is specific to the mailet container.

Parameters:

message - the message to be written to the log

log

void log(java.lang.String message,
         java.lang.Throwable t)

Writes the specified message to a mailet log, along with the stack trace of the given Throwable. The name and type of the mailet log is specific to the mailet container.

Parameters:

message - the message to be written to the log

t - the Throwable whose stack trace is to be written to the log

getPostmaster

MailAddress getPostmaster()

Returns the Postmaster address for this mailet context.

Returns:

the Postmaster address

isLocalServer

boolean isLocalServer(java.lang.String hostname)

Checks if a host name is local, i.e. this server is the final delivery destination for messages sent to this host.

Parameters:

hostname - the host name to check

Returns:

true if server is local, false otherwise

isLocalUser

boolean isLocalUser(java.lang.String userAccount)

Deprecated. use isLocalEmail(MailAddress) instead

Checks if a user account is local, i.e. the account exists locally and this server is the final delivery destination for messages sent to this address.

This given user account string should contain the full user address, i.e. user@domain. If the domain part is missing, "localhost" will be used as the domain name.

Parameters:

userAccount - the full address of the account to be checked

Returns:

true if the account is a local account, false otherwise

isLocalEmail

boolean isLocalEmail(MailAddress mailAddress)

Checks if an address is local, i.e. its account exists locally and this server is the final delivery destination for messages sent to this address.

Parameters:

mailAddress - the full address of the account to be checked

Returns:

true if the account is a local account, false otherwise

Since:

Mailet API 2.4

getMailServers

java.util.Collection getMailServers(java.lang.String domain)

Returns the hostnames that are specified as mail handlers for the given domain name. The host names are determined using DNS lookup of MX records and are returned sorted by priority (as detailed in the SMTP RFC).

Parameters:

domain - the domain name whose mail handling hosts are requested

Returns:

the sorted mail-handling hostnames for the domain

getSMTPHostAddresses

java.util.Iterator getSMTPHostAddresses(java.lang.String domain)

Returns the SMTP host addresses specified as mail handlers for the given domain name. This is equivalent to calling the getMailServers(java.lang.String) method and then performing address resolution lookups on all returned host names in order. The results are returned as instances of HostAddress containing the host and address information.

Parameters:

domain - the domain whose mail handling SMTP host addresses are requested

Returns:

an Iterator over HostAddress, in proper order of priority, or an empty iterator if no hosts are found

Since:

Mailet API v2.3

sendMail

void sendMail(javax.mail.internet.MimeMessage message)
              throws javax.mail.MessagingException

Sends an outgoing message to the top of this mailet container's root queue. This is functionally equivalent to having opened an SMTP session to the local host and delivering the message using the sender and recipients from within the message itself.

Parameters:

message - the message to send

Throws:

javax.mail.MessagingException - if an error occurs accessing or sending the message

sendMail

void sendMail(MailAddress sender,
              java.util.Collection recipients,
              javax.mail.internet.MimeMessage message)
              throws javax.mail.MessagingException

Sends an outgoing message to the top of this mailet container's root queue. This is functionally equivalent to having opened an SMTP session to the local host and delivering the message using the given sender and recipients.

Parameters:

sender - the message sender

recipients - the message recipients as a Collection of MailAddress objects

message - the message to send

Throws:

javax.mail.MessagingException - if an error occurs accessing or sending the message

sendMail

void sendMail(MailAddress sender,
              java.util.Collection recipients,
              javax.mail.internet.MimeMessage message,
              java.lang.String state)
              throws javax.mail.MessagingException

Sends an outgoing message to the top of this mailet container's queue for the specified processor.

Parameters:

sender - the message sender

recipients - the message recipients as a Collection of MailAddress objects

message - the message to send

state - the state of the message, indicating the name of the processor for which the message will be queued

Throws:

javax.mail.MessagingException - if an error occurs accessing or sending the message

sendMail

void sendMail(Mail mail)
              throws javax.mail.MessagingException

Sends an outgoing message to the top of this mailet container's root queue. This is the equivalent of opening an SMTP session to localhost. The Mail object provides all envelope and content information

Parameters:

mail - - the message that is to sent

Throws:

javax.mail.MessagingException - if an error occurs accessing or sending the message

bounce

void bounce(Mail mail,
            java.lang.String message)
            throws javax.mail.MessagingException

Bounces the message using a standard format with the given message.

The message will be sent to the original sender from the postmaster address as configured in this mailet context, adding the message to top of mail server queue using sendMail.

Parameters:

mail - the message to bounce, with the original sender

message - a descriptive message explaining why the message bounced

Throws:

javax.mail.MessagingException - if an error occurs accessing or sending the message

bounce

void bounce(Mail mail,
            java.lang.String message,
            MailAddress bouncer)
            throws javax.mail.MessagingException

Bounces the message using a standard format with the given message.

The message will be sent to the original sender from the given address, adding the message to top of mail server queue using sendMail.

Parameters:

mail - the message to bounce, with the original sender

message - a descriptive message explaining why the message bounced

bouncer - the address used as the sender of the bounce message

Throws:

javax.mail.MessagingException - if an error occurs accessing or sending the message

storeMail

void storeMail(MailAddress sender,
               MailAddress recipient,
               javax.mail.internet.MimeMessage message)
               throws javax.mail.MessagingException

Deprecated. - use sparingly. Service will be replaced with resource acquired via JNDI.

Stores the message is in the local repository associated with recipient for later retrieval, e.g., by a POP3 or IMAP service.

Parameters:

sender - - the sender of the incoming message

recipient - - the user who is receiving this message (as a complete email address)

message - - the MimeMessage to store in a local mailbox

Throws:

javax.mail.MessagingException - - if the message fails to parse