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 to the mailets and matchers when they are initialized.

Version:

1.0.0, 24/04/1999

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 email message using the provided email address as the sender of the bounce.
java.lang.Object	getAttribute(java.lang.String name) Returns the mailet container attribute with the given name, or null if there is no attribute by that name.
java.util.Iterator	getAttributeNames() Returns an Iterator containing the attribute names available within this mailet context.
java.util.Collection	getMailServers(java.lang.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 major 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.
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 domainName) Returns an Iterator over HostAddress, a specialized subclass of javax.mail.URLName, which provides location information for servers that are specified as mail handlers for the given hostname.
boolean	isLocalServer(java.lang.String serverName) Checks if a server is serviced by mail context
boolean	isLocalUser(java.lang.String userAccount) Checks if a user account is exists in the mail context.
void	log(java.lang.String message) Writes the specified message to a mailet log file, usually an event log.
void	log(java.lang.String message, java.lang.Throwable t) Writes an explanatory message and a stack trace for a given Throwable exception to the mailet log file.
void	removeAttribute(java.lang.String name) Removes the attribute with the given name from the mailet context.
void	sendMail(Mail mail) Send 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 msg) Send 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 msg, java.lang.String state) Send an outgoing message to the top of this mailet container queue for the appropriate processor that is specified.
void	sendMail(javax.mail.internet.MimeMessage msg) Send an outgoing message to the top of this mailet container's root queue.
void	setAttribute(java.lang.String name, java.lang.Object object) Binds an object to a given attribute name in this mailet context.
void	storeMail(MailAddress sender, MailAddress recipient, javax.mail.internet.MimeMessage msg) Deprecated. - use sparingly. Service will be replaced with resource acquired via JNDI.

Method Detail

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 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

Throws:

javax.mail.MessagingException

bounce

void bounce(Mail mail,
            java.lang.String message,
            MailAddress bouncer)
            throws javax.mail.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

Throws:

javax.mail.MessagingException

getMailServers

java.util.Collection getMailServers(java.lang.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

MailAddress getPostmaster()

Returns the postmaster's address for this mailet context.

Returns:

a MailAddress of the Postmaster's address

getAttribute

java.lang.Object getAttribute(java.lang.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

java.util.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

int getMajorVersion()

Returns the major 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

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

java.lang.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

boolean isLocalServer(java.lang.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

boolean isLocalUser(java.lang.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

void log(java.lang.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.

Parameters:

message - - a String specifying the message to be written to the log file

log

void log(java.lang.String message,
         java.lang.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

throwable - - the Throwable error or exception

removeAttribute

void removeAttribute(java.lang.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

void sendMail(javax.mail.internet.MimeMessage msg)
              throws javax.mail.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:

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

sendMail

void sendMail(MailAddress sender,
              java.util.Collection recipients,
              javax.mail.internet.MimeMessage msg)
              throws javax.mail.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.

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:

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

sendMail

void sendMail(MailAddress sender,
              java.util.Collection recipients,
              javax.mail.internet.MimeMessage msg,
              java.lang.String state)
              throws javax.mail.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 This is a String that names a processor for which the message will be queued

Throws:

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

sendMail

void sendMail(Mail mail)
              throws javax.mail.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. The Mail object provides all envelope and content information

Parameters:

mail - - the message that is to sent

Throws:

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

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.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

void storeMail(MailAddress sender,
               MailAddress recipient,
               javax.mail.internet.MimeMessage msg)
               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)

msg - - the MimeMessage to store in a local mailbox

Throws:

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

getSMTPHostAddresses

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

Returns an Iterator over HostAddress, a specialized subclass of javax.mail.URLName, which provides location information for servers that are specified as mail handlers for the given hostname. This is done using MX records, and the HostAddress instances are returned sorted by MX priority. If no host is found for domainName, the Iterator returned will be empty and the first call to hasNext() will return false.

Parameters:

domainName - - the domain for which to find mail servers

Returns:

an Iterator over HostAddress instances, sorted by priority

Since:

Mailet API v2.2.0a16-unstable