| org.apache.mailet.Matcher
All known Subclasses: org.apache.mailet.GenericMatcher,
| Matcher | | public interface Matcher (Code) | | 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:
- The matcher is constructed, then initialized with the init method.
- Any calls from clients to the match method are handled.
- 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.
Implementations of this interface are responsible for storing the
MatcherConfig object so that this method can return it. | | 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.
The mailet container calls the init method exactly once after instantiating
the matcher. | | 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.
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. |
| destroy | | void destroy()(Code) | | 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()(Code) | | 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.
the MatcherConfig object that initializes this matcher |
| getMatcherInfo | | String getMatcherInfo()(Code) | | 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.).
a String containing matcher information |
| init | | void init(MatcherConfig config) throws javax.mail.MessagingException(Code) | | 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 configurationand initialization parameters
throws:
javax.mail.MessagingException - - if an exception has occurred thatinterferes with the matcher's normal operation |
| match | | Collection match(Mail mail) throws javax.mail.MessagingException(Code) | | 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 a Collection of String objects (recipients) that meet the match criteria
throws:
MessagingException - - if an message or address parsing exception occurs oran exception that interferes with the matcher's normal operation |
|
|