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


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