org.apache.mailet
Interface Mailet


public interface Mailet

A Mailet processes mail messages.

The Mailet life cycle is controlled by the mailet container, which invokes the Mailet methods in the following order:

  1. The mailet is constructed.
  2. The init(org.apache.mailet.MailetConfig) method is invoked once to initialize the mailet.
  3. The service(org.apache.mailet.Mail) method is invoked to process mail messages. This can occur an unlimited number of times, even concurrently.
  4. At some point, such as when the mailet container is shut down, the mailet is taken out of service and then destroyed by invoking the destroy() method once.

In addition to the life-cycle methods, this interface provides the getMailetConfig() method, which provides the Mailet with its initialization parameters and a MailetContext through which it can interact with the mailet container, and the getMailetInfo() method, which provides basic information about the Mailet.

Mailets are grouped by the mailet container's configuration into processors. Each processor is comprised of an ordered sequence of Mailets, each with a corresponding Matcher. A Mail message is processed by each Matcher-Mailet pair in order: If the mail is matched by the Matcher, it is passed to the Mailet's service method for processing, and if it is not matched, the Mailet is skipped and the mail moves on to the next Matcher-Mailet pair.

The service method performs all needed processing on the Mail, and may modify the message content, recipients, attributes, state, etc. When the method returns, the mail is passed on to the next Matcher-Mailer pair in the processor. If there are no subsequent mailets in the processor, it is moved to the error processor. Setting the Mail state to Mail.GHOST, or clearing its recipient list, both mean that no further processing is needed, which will cause the Mail to be dropped without ever reaching subsequent Mailets.

Instead of creating new messages, the mailet can put a message with new recipients at the top of the mail queue, or insert them immediately after it's execution through the API are provided by the MailetContext interface.


Method Summary
 void destroy()
          Destroys this Mailet.
 MailetConfig getMailetConfig()
          Returns a MailetConfig object, which provides initialization parameters and a MailetContext through which it can interact with the mailet container.
 java.lang.String getMailetInfo()
          Returns information about the mailet, such as author, version and copyright.
 void init(MailetConfig config)
          Initializes this Mailet.
 void service(Mail mail)
          Services a mail message.
 

Method Detail

init

void init(MailetConfig config)
          throws javax.mail.MessagingException
Initializes this Mailet.

This method is called only once, and must complete successfully before the service(org.apache.mailet.Mail) method can be invoked.

Parameters:
config - a MailetConfig containing the mailet's configuration and initialization parameters
Throws:
javax.mail.MessagingException - if an error occurs

service

void service(Mail mail)
             throws javax.mail.MessagingException
Services a mail message.

Mailets typically run inside multithreaded mailet containers that can handle multiple requests concurrently. Developers must be aware to synchronize access to any shared resources such as files and network connections, as well as the mailet's fields. More information on multithreaded programming in Java is available at the Java tutorial on multi-threaded programming.

Parameters:
mail - the Mail to process
Throws:
javax.mail.MessagingException - if any error occurs which prevents the Mail processing from completing successfully

destroy

void destroy()
Destroys this Mailet.

This method is called only once, after all service(org.apache.mailet.Mail) invocations have completed (or a timeout period has elapsed). After this method returns, this Mailet will no longer be used.

Implementations should use this method to release any resources that are being held (such as memory, file handles or threads) and make sure that any persistent information is properly stored.


getMailetConfig

MailetConfig getMailetConfig()
Returns a MailetConfig object, which provides initialization parameters and a MailetContext through which it can interact with the mailet container.

Implementations of this interface are responsible for storing the MailetConfig which they receive in the init(org.apache.mailet.MailetConfig) method so that this method can return it.

Returns:
the MailetConfig that this mailet was initialized with

getMailetInfo

java.lang.String getMailetInfo()
Returns information about the mailet, such as author, version and copyright.

Returns:
the Mailet information (as a plain text string)


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