|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Matcher
This interface defines the behaviour of the message "routing" inside
the mailet container. At its heart is the match(Mail)
method,
which inspects a Mail and returns a subset of its recipients which meet
this Matcher's criteria.
An important feature of the mailet container is the ability to fork processing of messages. When a message first arrives at the server, it might have multiple recipients specified. When a message is passed to a matcher, the matcher might only match some of the listed recipients. The mailet container should then duplicate the message, splitting the recipient list across the two messages as per the match result, and proceed to process them separately.
The Matcher life cycle is controlled by the mailet container, which invokes the Matcher methods in the following order:
init(org.apache.mailet.MatcherConfig)
method is invoked once to initialize the matcher.
match(org.apache.mailet.Mail)
method is invoked to match mail messages.
This can occur an unlimited number of times, even concurrently.
destroy()
method once.
In addition to the life-cycle methods, this interface provides the
getMatcherConfig()
method, which provides the Matcher with
its configuration information and a MailetContext
through which
it can interact with the mailet container, and the getMatcherInfo()
method, which provides basic information about the Matcher.
Method Summary | |
---|---|
void |
destroy()
Destroys this Matcher. |
MatcherConfig |
getMatcherConfig()
Returns a MatcherConfig object, which provides initialization parameters and a MailetContext through which it can interact with the
mailet container. |
java.lang.String |
getMatcherInfo()
Returns information about the matcher, such as author, version and copyright. |
void |
init(MatcherConfig config)
Initializes this Matcher. |
java.util.Collection |
match(Mail mail)
Takes a Mail message, looks at any pertinent information, and returns a subset of recipients that meet the match conditions. |
Method Detail |
---|
void init(MatcherConfig config) throws javax.mail.MessagingException
This method is called only once, and must complete successfully
before the match(org.apache.mailet.Mail)
method can be invoked.
config
- a MatcherConfig containing the matcher's configuration
and initialization parameters
javax.mail.MessagingException
- if an error occursjava.util.Collection match(Mail mail) throws javax.mail.MessagingException
Matchers 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, network connections, and as well as the matcher's fields. More information on multithreaded programming in Java is available at the Java tutorial on multi-threaded programming.
mail
- the Mail to match
javax.mail.MessagingException
- if any error occurs which prevents the Mail
matching from completing successfullyvoid destroy()
This method is called only once, after all match(org.apache.mailet.Mail)
invocations
have completed (or a timeout period has elapsed). After this method
returns, this Matcher 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.
Note that containers SHOULD NOT
invoke this method before
init(MatcherConfig)
has been successfully completed.
MatcherConfig getMatcherConfig()
MailetContext
through which it can interact with the
mailet container.
Implementations of this interface are responsible for storing the
MatcherConfig which they receive in the init(org.apache.mailet.MatcherConfig)
method so
that this method can return it.
java.lang.String getMatcherInfo()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |