org.apache.mailet
Interface Matcher

All Known Implementing Classes:

AbstractNetworkMatcher, AbstractQuotaMatcher, AbstractStorageQuota, All, AttachmentFileNameIs, CommandForListserv, CommandListservMatcher, CompareNumericHeaderValue, FetchedFrom, FileRegexMatcher, GenericMatcher, GenericRecipientMatcher, GenericRegexMatcher, HasAttachment, HasHabeasWarrantMark, HasHeader, HasMailAttribute, HasMailAttributeWithValue, HasMailAttributeWithValueRegex, HostIs, HostIsLocal, InSpammerBlacklist, IsInWhiteList, IsSingleRecipient, IsSMIMEEncrypted, IsSMIMESigned, IsX509CertificateSubject, NESSpamCheck, RecipientIs, RecipientIsLocal, RecipientIsOverFixedQuota, RecipientIsRegex, RelayLimit, RemoteAddrInNetwork, RemoteAddrNotInNetwork, SenderHostIs, SenderInFakeDomain, SenderIs, SenderIsNull, SenderIsRegex, SizeGreaterThan, SMTPAuthSuccessful, SMTPAuthUserIs, SubjectIs, SubjectStartsWith, UserIs

public interface Matcher

This interface define the behaviour of the message "routing" inside the mailet container. The match(Mail) method returns a Collection of recipients that meet this class'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. As a message is passed to a matcher, the matcher might only "match" one of the listed recipients. It would then return only the matching recipient in the Collection. The mailet container should then duplicate the message splitting the recipient list across the two messages as per what the matcher returned.

[THIS PARAGRAPH NOT YET IMPLEMENTED] The matcher can extend this forking to further separation by returning a Collection of Collection objects. This allows a matcher to fork multiple processes if there are multiple recipients that require separate processing. For example, we could write a ListservMatcher that handles multiple listservs. When someone cross-posts across multiple listservs that this matcher handles, it could put each listserv address (recipient) that it handles in a separate Collection object. By returning each of these Collections within a container Collection object, it could indicate to the mailet container how many forks to spawn.

This interface defines methods to initialize a matcher, to match messages, and to remove a matcher from the server. These are known as life-cycle methods and are called in the following sequence:

1. The matcher is constructed, then initialized with the init method.
2. Any calls from clients to the match method are handled.
3. The matcher is taken out of service, then destroyed with the destroy method, then garbage collected and finalized.

In addition to the life-cycle methods, this interface provides the getMatcherConfig method, which the matcher can use to get any startup information, and the getMatcherInfo method, which allows the matcher to return basic information about itself, such as author, version, and copyright.

Version:

1.0.0, 24/04/1999

Method Summary

void	destroy() Called by the mailet container to indicate to a matcher that the matcher is being taken out of service.
MatcherConfig	getMatcherConfig() Returns a MatcherConfig object, which contains initialization and startup parameters for this matcher.
java.lang.String	getMatcherInfo() Returns information about the matcher, such as author, version, and copyright.
void	init(MatcherConfig config) Called by the mailet container to indicate to a matcher that the matcher is being placed into service.
java.util.Collection	match(Mail mail) Takes a Mail message, looks at any pertinent information, and then returns a subset of recipients that meet the "match" conditions.

Method Detail

destroy

void destroy()

Called by the mailet container to indicate to a matcher that the matcher is being taken out of service. This method is only called once all threads within the matcher's service method have exited or after a timeout period has passed. After the mailet container calls this method, it will not call the match method again on this matcher.

This method gives the matcher an opportunity to clean up any resources that are being held (for example, memory, file handles, threads) and make sure that any persistent state is synchronized with the matcher's current state in memory.

getMatcherConfig

MatcherConfig getMatcherConfig()

Returns a MatcherConfig object, which contains initialization and startup parameters for this matcher.

Implementations of this interface are responsible for storing the MatcherConfig object so that this method can return it. The GenericMatcher class, which implements this interface, already does this.

Returns:

the MatcherConfig object that initializes this matcher

getMatcherInfo

java.lang.String getMatcherInfo()

Returns information about the matcher, such as author, version, and copyright.

The string that this method returns should be plain text and not markup of any kind (such as HTML, XML, etc.).

Returns:

a String containing matcher information

init

void init(MatcherConfig config)
          throws javax.mail.MessagingException

Called by the mailet container to indicate to a matcher that the matcher is being placed into service.

The mailet container calls the init method exactly once after instantiating the matcher. The init method must complete successfully before the matcher can receive any messages.

Parameters:

config - - a MatcherConfig object containing the matcher's configuration and initialization parameters

Throws:

javax.mail.MessagingException - - if an exception has occurred that interferes with the matcher's normal operation

match

java.util.Collection match(Mail mail)
                           throws javax.mail.MessagingException

Takes a Mail message, looks at any pertinent information, and then returns a subset of recipients that meet the "match" conditions.

This method is only called after the matcher's init() method has completed successfully.

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 class and instance variables. More information on multithreaded programming in Java is available in the Java tutorial on multi-threaded programming.

Parameters:

mail - - the Mail object that contains the message and routing information

Returns:

a Collection of String objects (recipients) that meet the match criteria

Throws:

MessagingException - - if an message or address parsing exception occurs or an exception that interferes with the matcher's normal operation