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