org.apache.mailet
Interface Matcher

All Known Implementing Classes:
AbstractQuotaMatcher, All, AttachmentFileNameIs, CommandForListserv, CommandListservMatcher, CompareNumericHeaderValue, FetchedFrom, FileRegexMatcher, GenericMatcher, GenericRecipientMatcher, GenericRegexMatcher, HasAttachment, HasHabeasWarrantMark, HasHeader, HasMailAttribute, HasMailAttributeWithValue, HasMailAttributeWithValueRegex, HostIs, HostIsLocal, IsSingleRecipient, IsSMIMEEncrypted, IsSMIMESigned, IsX509CertificateSubject, MatcherInverter, NESSpamCheck, RecipientIs, RecipientIsLocal, RecipientIsRegex, RelayLimit, SenderHostIs, SenderHostIsLocal, SenderIs, SenderIsLocal, SenderIsNull, SenderIsRegex, SizeGreaterThan, SMTPAuthSuccessful, SMTPAuthUserIs, SMTPIsAuthNetwork, SubjectIs, SubjectStartsWith, UserIs

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:

  1. The matcher is constructed.
  2. The init(org.apache.mailet.MatcherConfig) method is invoked once to initialize the matcher.
  3. The match(org.apache.mailet.Mail) method is invoked to match 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 matcher 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 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.
 String getMatcherInfo()
          Returns information about the matcher, such as author, version and copyright.
 void init(MatcherConfig config)
          Initializes this Matcher.
 Collection<MailAddress> 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

init

void init(MatcherConfig config)
          throws javax.mail.MessagingException
Initializes this Matcher.

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

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

match

Collection<MailAddress> match(Mail mail)
                              throws javax.mail.MessagingException
Takes a Mail message, looks at any pertinent information, and returns a subset of recipients that meet the match conditions.

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.

Parameters:
mail - the Mail to match
Returns:
the recipients that meet the match criteria as a Collection of String objects
Throws:
javax.mail.MessagingException - if any error occurs which prevents the Mail matching from completing successfully

destroy

void destroy()
Destroys this Matcher.

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.


getMatcherConfig

MatcherConfig getMatcherConfig()
Returns a MatcherConfig 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 MatcherConfig which they receive in the init(org.apache.mailet.MatcherConfig) method so that this method can return it.

Returns:
the MatcherConfig that this matcher was initialized with

getMatcherInfo

String getMatcherInfo()
Returns information about the matcher, such as author, version and copyright.

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


Copyright © 2008-2012 The Apache Software Foundation. All Rights Reserved.