1 /*
2 * Copyright (C) The Apache Software Foundation. All rights reserved.
3 *
4 * This software is published under the terms of the Apache Software License
5 * version 1.1, a copy of which has been included with this distribution in
6 * the LICENSE file.
7 */
8 package org.apache.mailet;
9
10 import java.util.Collection;
11
12 /***
13 * This interface define the behaviour of the message "routing" inside
14 * the mailet container. The match(Mail) method returns a Collection of
15 * recipients that meet this class's criteria.
16 * <p>
17 * An important feature of the mailet container is the ability to fork
18 * processing of messages. When a message first arrives at the server,
19 * it might have multiple recipients specified. As a message is passed
20 * to a matcher, the matcher might only "match" one of the listed
21 * recipients. It would then return only the matching recipient in
22 * the Collection. The mailet container should then duplicate the
23 * message splitting the recipient list across the two messages as per
24 * what the matcher returned.
25 * <p>
26 * <b>[THIS PARAGRAPH NOT YET IMPLEMENTED]</b>
27 * <i>The matcher can extend this forking to further separation by returning
28 * a Collection of Collection objects. This allows a matcher to fork
29 * multiple processes if there are multiple recipients that require
30 * separate processing. For example, we could write a ListservMatcher
31 * that handles multiple listservs. When someone cross-posts across
32 * multiple listservs that this matcher handles, it could put each
33 * listserv address (recipient) that it handles in a separate Collection
34 * object. By returning each of these Collections within a container
35 * Collection object, it could indicate to the mailet container how
36 * many forks to spawn.</i>
37 * <p>
38 * This interface defines methods to initialize a matcher, to match
39 * messages, and to remove a matcher from the server. These are known
40 * as life-cycle methods and are called in the following sequence:
41 * <ol>
42 * <li>The matcher is constructed, then initialized with the init method.</li>
43 * <li>Any calls from clients to the match method are handled.</li>
44 * <li>The matcher is taken out of service, then destroyed with the
45 * destroy method, then garbage collected and finalized.</li>
46 * </ol>
47 * In addition to the life-cycle methods, this interface provides the
48 * getMatcherConfig method, which the matcher can use to get any startup
49 * information, and the getMatcherInfo method, which allows the matcher
50 * to return basic information about itself, such as author, version,
51 * and copyright.
52 *
53 * @version 1.0.0, 24/04/1999
54 * @author Federico Barbieri <scoobie@pop.systemy.it>
55 * @author Serge Knystautas <sergek@lokitech.com>
56 */
57 public interface Matcher {
58
59 /***
60 * Called by the mailet container to indicate to a matcher that the matcher
61 * is being taken out of service. This method is only called once all threads
62 * within the matcher's service method have exited or after a timeout period
63 * has passed. After the mailet container calls this method, it will not call
64 * the match method again on this matcher.
65 * <p>
66 * This method gives the matcher an opportunity to clean up any resources that
67 * are being held (for example, memory, file handles, threads) and make sure
68 * that any persistent state is synchronized with the matcher's current state in memory.
69 */
70 void destroy();
71
72 /***
73 * Returns a MatcherConfig object, which contains initialization and
74 * startup parameters for this matcher.
75 * <p>
76 * Implementations of this interface are responsible for storing the
77 * MatcherConfig object so that this method can return it. The GenericMatcher
78 * class, which implements this interface, already does this.
79 *
80 * @return the MatcherConfig object that initializes this matcher
81 */
82 MatcherConfig getMatcherConfig();
83
84 /***
85 * Returns information about the matcher, such as author, version, and copyright.
86 * <p>
87 * The string that this method returns should be plain text and not markup
88 * of any kind (such as HTML, XML, etc.).
89 *
90 * @return a String containing matcher information
91 */
92 String getMatcherInfo();
93
94 /***
95 * Called by the mailet container to indicate to a matcher that the
96 * matcher is being placed into service.
97 * <p>
98 * The mailet container calls the init method exactly once after instantiating
99 * the matcher. The init method must complete successfully before the matcher
100 * can receive any messages.
101 *
102 * @param config - a MatcherConfig object containing the matcher's configuration
103 * and initialization parameters
104 * @throws javax.mail.MessagingException - if an exception has occurred that
105 * interferes with the matcher's normal operation
106 */
107 void init( MatcherConfig config ) throws javax.mail.MessagingException;
108
109 /***
110 * Takes a Mail message, looks at any pertinent information, and then returns a subset
111 * of recipients that meet the "match" conditions.
112 * <p>
113 * This method is only called after the matcher's init() method has completed
114 * successfully.
115 * <p>
116 * Matchers typically run inside multithreaded mailet containers that can handle
117 * multiple requests concurrently. Developers must be aware to synchronize access
118 * to any shared resources such as files, network connections, and as well as the
119 * matcher's class and instance variables. More information on multithreaded
120 * programming in Java is available in <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
121 * Java tutorial on multi-threaded programming</a>.
122 *
123 * @param mail - the Mail object that contains the message and routing information
124 * @return a Collection of String objects (recipients) that meet the match criteria
125 * @throws MessagingException - if an message or address parsing exception occurs or
126 * an exception that interferes with the matcher's normal operation
127 */
128 Collection match( Mail mail ) throws javax.mail.MessagingException;
129 }
This page was automatically generated by Maven