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