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
21 package org.apache.mailet.base;
22
23 import javax.mail.MessagingException;
24
25 import org.apache.mailet.Mail;
26 import org.apache.mailet.MailetContext;
27 import org.apache.mailet.Matcher;
28 import org.apache.mailet.MatcherConfig;
29
30 import java.util.Collection;
31
32 /**
33 * <p>GenericMatcher implements the Matcher and MatcherConfig interfaces.</p>
34 * <p>GenericMatcher makes writing matchers easier. It provides simple versions of
35 * the lifecycle methods init and destroy and of the methods in the MatcherConfig
36 * interface. GenericMatcher also implements the log method, declared in the
37 * MatcherContext interface.</p>
38 *
39 * <p>To write a generic matcher, you need only override the abstract match method.</p>
40 *
41 * @version 1.0.0, 24/04/1999
42 */
43 public abstract class GenericMatcher implements Matcher, MatcherConfig {
44 MatcherConfig config = null;
45
46 /**
47 * Called by the mailet container to indicate to a matcher that the
48 * matcher is being taken out of service.
49 */
50 public void destroy() {
51 //Do nothing
52 }
53
54 /**
55 * <p>Returns a String containing the value of the named initialization
56 * parameter, or null if the parameter does not exist.</p>
57 *
58 * <p>This method is supplied for convenience. It gets the value of the
59 * named parameter from the matcher's MatcherConfig object.</p>
60 *
61 * @return String a String containing the value of the initalization parameter
62 */
63 public String getCondition() {
64 return config.getCondition();
65 }
66
67 /**
68 * Returns this matcher's MatcherConfig object.
69 *
70 * @return MatcherConfig the MatcherConfig object that initialized this matcher
71 */
72 public MatcherConfig getMatcherConfig() {
73 return config;
74 }
75
76 /**
77 * Returns a reference to the MailetContext in which this matcher is
78 * running.
79 *
80 * @return MailetContext the MailetContext object passed to this matcher by the init method
81 */
82 public MailetContext getMailetContext() {
83 return getMatcherConfig().getMailetContext();
84 }
85
86 /**
87 * Returns information about the matcher, such as author, version, and
88 * copyright. By default, this method returns an empty string. Override
89 * this method to have it return a meaningful value.
90 *
91 * @return String information about this matcher, by default an empty string
92 */
93 public String getMatcherInfo() {
94 return "";
95 }
96
97 /**
98 * Returns the name of this matcher instance.
99 *
100 * @return the name of this matcher instance
101 */
102 public String getMatcherName() {
103 return config.getMatcherName();
104 }
105
106
107 /**
108 * <p>Called by the matcher container to indicate to a matcher that the
109 * matcher is being placed into service.</p>
110 *
111 * <p>This implementation stores the MatcherConfig object it receives from
112 * the matcher container for alter use. When overriding this form of the
113 * method, call super.init(config).</p>
114 *
115 * @param newConfig - the MatcherConfig object that contains
116 * configutation information for this matcher
117 * @throws MessagingException
118 * if an exception occurs that interrupts the matcher's normal operation
119 */
120 public void init(MatcherConfig newConfig) throws MessagingException {
121 config = newConfig;
122 init();
123 }
124
125 /**
126 * <p>A convenience method which can be overridden so that there's no
127 * need to call super.init(config).</p>
128 *
129 * <p>Instead of overriding init(MatcherConfig), simply override this
130 * method and it will be called by GenericMatcher.init(MatcherConfig config).
131 * The MatcherConfig object can still be retrieved via getMatcherConfig().</p>
132 *
133 * @throws MessagingException
134 * if an exception occurs that interrupts the matcher's normal operation
135 */
136 public void init() throws MessagingException {
137 //Do nothing... can be overridden
138 }
139
140 /**
141 * Writes the specified message to a matcher log file.
142 *
143 * @param message - a String specifying the message to be written to the log file
144 */
145 public void log(String message) {
146 getMailetContext().log(message);
147 }
148
149 /**
150 * Writes an explanatory message and a stack trace for a given Throwable
151 * exception to the matcher log file.
152 *
153 * @param message - a String that describes the error or exception
154 * @param t - the java.lang.Throwable error or exception
155 */
156 public void log(String message, Throwable t) {
157 getMailetContext().log(message, t);
158 }
159
160 /**
161 * <p>Called by the matcher container to allow the matcher to process a
162 * message.</p>
163 *
164 * <p>This method is declared abstract so subclasses must override it.</p>
165 *
166 * @param mail - the Mail object that contains the MimeMessage and
167 * routing information
168 * @return java.util.Collection - the recipients that the mailet container should have the
169 * mailet affect.
170 * @throws javax.mail.MessagingException - if an exception occurs that interferes with the mailet's normal operation
171 * occurred
172 */
173 public abstract Collection match(Mail mail) throws MessagingException;
174 }