org.apache.mailet
Interface MailetContext

All Known Implementing Classes:

James

public interface MailetContext

Defines a set of methods that a mailet or matcher uses to communicate with its mailet container, for example, to send a new message, to deliver a message locally, or write to a log file. The MailetContext object is contained within the MailetConfig and MatcherConfig objects, which the mailet container provides the mailets and matchers when they are initialized.

Version:

1.0.0, 24/04/1999

Author:

Federico Barbieri , Stefano Mazzocchi , Pierpaolo Fumagalli , Serge Knystautas

Method Summary

void	bounce(Mail mail, String message) Bounces the message using a standard format with the given message.
void	bounce(Mail mail, String message, MailAddress bouncer) Bounces the email message using the provided email address as the sender of the bounce.
Object	getAttribute(String name) Returns the mailet container attribute with the given name, or null if there is no attribute by that name.
Iterator	getAttributeNames() Returns an Iterator containing the attribute names available within this mailet context.
Collection	getMailServers(String host) Returns a Collection of Strings of hostnames or ip addresses that are specified as mail server listeners for the given hostname.
int	getMajorVersion() Returns the minor version of the Mailet API that this mailet container supports.
int	getMinorVersion() Returns the minor version of the Mailet API that this mailet container supports.
MailAddress	getPostmaster() Returns the postmaster's address for this mailet context.
String	getServerInfo() Returns the name and version of the mailet container on which the mailet is running.
boolean	isLocalServer(String serverName) Checks if a server is serviced by mail context
boolean	isLocalUser(String userAccount) Checks if a user account is exists in the mail context.
void	log(String message) Writes the specified message to a mailet log file, usually an event log.
void	log(String message, Throwable t) Writes an explanatory message and a stack trace for a given Throwable exception to the mailet log file.
void	removeAttribute(String name) Removes the attribute with the given name from the mailet context.
void	sendMail(MailAddress sender, Collection recipients, MimeMessage msg) Send an outgoing message to the top of this mailet container's root queue.
void	sendMail(MailAddress sender, Collection recipients, MimeMessage msg, String state) Send an outgoing message to the top of this mailet container queue for the appropriate processor that is specified.
void	sendMail(MimeMessage msg) Send an outgoing message to the top of this mailet container's root queue.
void	setAttribute(String name, Object object) Binds an object to a given attribute name in this mailet context.
void	storeMail(MailAddress sender, MailAddress recipient, MimeMessage msg) Stores mail into local accounts (POP3 by default)

Method Detail

bounce

public void bounce(Mail mail,
                   String message)
            throws MessagingException

Bounces the message using a standard format with the given message. Will be sent back to the sender from the postmaster as specified for this mailet context, adding message to top of mail server queue using sendMail().

Parameters:

mail - - the message that is to be bounced and sender to whom to return the message

message - - a descriptive message as to why the message bounced

MessagingException

bounce

public void bounce(Mail mail,
                   String message,
                   MailAddress bouncer)
            throws MessagingException

Bounces the email message using the provided email address as the sender of the bounce.

Parameters:

mail - - the message that is to be bounced and sender to whom to return the message

message - - a descriptive message as to why the message bounced

bouncer - - the address to give as the sender of the bounced message

MessagingException

getMailServers

public Collection getMailServers(String host)

Returns a Collection of Strings of hostnames or ip addresses that are specified as mail server listeners for the given hostname. This is done using MX records, and the hostnames or ip addresses are returned sorted by MX priority.

Parameters:

host - - the domain name for which to find mail servers

Returns:

a Collection of Strings of hostnames, sorted by priority

getPostmaster

public MailAddress getPostmaster()

Returns the postmaster's address for this mailet context.

Returns:

a MailAddress of the Postmaster's address

getAttribute

public Object getAttribute(String name)

Returns the mailet container attribute with the given name, or null if there is no attribute by that name. An attribute allows a mailet container to give the mailet additional information not already provided by this interface. See * your server documentation for information about its attributes. A list of supported attributes can be retrieved using getAttributeNames.

The attribute is returned as a java.lang.Object or some subclass. Attribute names should follow the same convention as package names. The Java Mailet API specification reserves names matching java.*, javax.*, and sun.*

Parameters:

name - - a String specifying the name of the attribute

Returns:

an Object containing the value of the attribute, or null if no attribute exists matching the given name

getAttributeNames

public Iterator getAttributeNames()

Returns an Iterator containing the attribute names available within this mailet context. Use the getAttribute(java.lang.String) method with an attribute name to get the value of an attribute.

Returns:

an Iterator of attribute names

getMajorVersion

public int getMajorVersion()

Returns the minor version of the Mailet API that this mailet container supports. All implementations that comply with Version 1.2 must have this method return the integer 1.

Returns:

1

getMinorVersion

public int getMinorVersion()

Returns the minor version of the Mailet API that this mailet container supports. All implementations that comply with Version 1.2 must have this method return the integer 2.

Returns:

2

getServerInfo

public String getServerInfo()

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

The form of the returned string is servername/versionnumber. For example, JAMES may return the string JAMES/1.2.

The mailet container may return other optional information after the primary string in parentheses, for example, JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86).

Returns:

a String containing at least the mailet container name and version number

isLocalServer

public boolean isLocalServer(String serverName)

Checks if a server is serviced by mail context

Parameters:

serverName - - name of server.

Returns:

true if server is local, i.e. serviced by this mail context

isLocalUser

public boolean isLocalUser(String userAccount)

Checks if a user account is exists in the mail context.

Parameters:

userAccount - - user identifier.

Returns:

true if the acount is a local account

log

public void log(String message)

Writes the specified message to a mailet log file, usually an event log. The name and type of the mailet log file is specific to the mailet container.

log

public void log(String message,
                Throwable t)

Writes an explanatory message and a stack trace for a given Throwable exception to the mailet log file.

Parameters:

message - - a String that describes the error or exception

removeAttribute

public void removeAttribute(String name)

Removes the attribute with the given name from the mailet context. After removal, subsequent calls to getAttribute(java.lang.String) to retrieve the attribute's value will return null.

Parameters:

name - - a String specifying the name of the attribute to be removed

sendMail

public void sendMail(MimeMessage msg)
              throws MessagingException

Send an outgoing message to the top of this mailet container's root queue. This is the equivalent of opening an SMTP session to localhost. This uses sender and recipients as specified in the message itself.

Parameters:

msg - - the MimeMessage of the headers and body content of the outgoing message

Throws:

MessagingException - - if the message fails to parse

sendMail

public void sendMail(MailAddress sender,
                     Collection recipients,
                     MimeMessage msg)
              throws MessagingException

Send an outgoing message to the top of this mailet container's root queue. Is the equivalent of opening an SMTP session to localhost.

Parameters:

sender - - the sender of the message

recipients - - a Collection of MailAddress objects of recipients

msg - - the MimeMessage of the headers and body content of the outgoing message

Throws:

MessagingException - - if the message fails to parse

sendMail

public void sendMail(MailAddress sender,
                     Collection recipients,
                     MimeMessage msg,
                     String state)
              throws MessagingException

Send an outgoing message to the top of this mailet container queue for the appropriate processor that is specified.

Parameters:

sender - - the sender of the message

recipients - - a Collection of MailAddress objects of recipients

msg - - the MimeMessage of the headers and body content of the outgoing message

state - - the state of the message, indicates which processor to use

Throws:

MessagingException - - if the message fails to parse

setAttribute

public void setAttribute(String name,
                         Object object)

Binds an object to a given attribute name in this mailet context. If the name specified is already used for an attribute, this method will remove the old attribute and bind the name to the new attribute.

Attribute names should follow the same convention as package names. The Java Mailet API specification reserves names matching java.*, javax.*, and sun.*.

Parameters:

name - - a String specifying the name of the attribute

object - - an Object representing the attribute to be bound

storeMail

public void storeMail(MailAddress sender,
                      MailAddress recipient,
                      MimeMessage msg)
               throws MessagingException

Stores mail into local accounts (POP3 by default)

Parameters:

sender - - the sender of the incoming message

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

msg - - the MimeMessage to store in a local mailbox

Throws:

MessagingException - - if the message fails to parse