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