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