001 /****************************************************************
002 * Licensed to the Apache Software Foundation (ASF) under one *
003 * or more contributor license agreements. See the NOTICE file *
004 * distributed with this work for additional information *
005 * regarding copyright ownership. The ASF licenses this file *
006 * to you under the Apache License, Version 2.0 (the *
007 * "License"); you may not use this file except in compliance *
008 * with the License. You may obtain a copy of the License at *
009 * *
010 * http://www.apache.org/licenses/LICENSE-2.0 *
011 * *
012 * Unless required by applicable law or agreed to in writing, *
013 * software distributed under the License is distributed on an *
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015 * KIND, either express or implied. See the License for the *
016 * specific language governing permissions and limitations *
017 * under the License. *
018 ****************************************************************/
019
020
021 package org.apache.mailet.base;
022
023 import javax.mail.MessagingException;
024
025 import org.apache.mailet.Mail;
026 import org.apache.mailet.MailAddress;
027 import org.apache.mailet.MailetContext;
028 import org.apache.mailet.Matcher;
029 import org.apache.mailet.MatcherConfig;
030 import org.apache.mailet.MailetContext.LogLevel;
031
032 import java.util.Collection;
033
034 /**
035 * <p>GenericMatcher implements the Matcher and MatcherConfig interfaces.</p>
036 * <p>GenericMatcher makes writing matchers easier. It provides simple versions of
037 * the lifecycle methods init and destroy and of the methods in the MatcherConfig
038 * interface. GenericMatcher also implements the log method, declared in the
039 * MatcherContext interface.</p>
040 *
041 * <p>To write a generic matcher, you need only override the abstract match method.</p>
042 *
043 * @version 1.0.0, 24/04/1999
044 */
045 public abstract class GenericMatcher implements Matcher, MatcherConfig {
046 MatcherConfig config = null;
047
048 /**
049 * Called by the mailet container to indicate to a matcher that the
050 * matcher is being taken out of service.
051 */
052 public void destroy() {
053 //Do nothing
054 }
055
056 /**
057 * <p>Returns a String containing the value of the named initialization
058 * parameter, or null if the parameter does not exist.</p>
059 *
060 * <p>This method is supplied for convenience. It gets the value of the
061 * named parameter from the matcher's MatcherConfig object.</p>
062 *
063 * @return String a String containing the value of the initalization parameter
064 */
065 public String getCondition() {
066 return config.getCondition();
067 }
068
069 /**
070 * Returns this matcher's MatcherConfig object.
071 *
072 * @return MatcherConfig the MatcherConfig object that initialized this matcher
073 */
074 public MatcherConfig getMatcherConfig() {
075 return config;
076 }
077
078 /**
079 * Returns a reference to the MailetContext in which this matcher is
080 * running.
081 *
082 * @return MailetContext the MailetContext object passed to this matcher by the init method
083 */
084 public MailetContext getMailetContext() {
085 return getMatcherConfig().getMailetContext();
086 }
087
088 /**
089 * Returns information about the matcher, such as author, version, and
090 * copyright. By default, this method returns an empty string. Override
091 * this method to have it return a meaningful value.
092 *
093 * @return String information about this matcher, by default an empty string
094 */
095 public String getMatcherInfo() {
096 return "";
097 }
098
099 /**
100 * Returns the name of this matcher instance.
101 *
102 * @return the name of this matcher instance
103 */
104 public String getMatcherName() {
105 return config.getMatcherName();
106 }
107
108
109 /**
110 * <p>Called by the matcher container to indicate to a matcher that the
111 * matcher is being placed into service.</p>
112 *
113 * <p>This implementation stores the MatcherConfig object it receives from
114 * the matcher container for alter use. When overriding this form of the
115 * method, call super.init(config).</p>
116 *
117 * @param newConfig - the MatcherConfig object that contains
118 * configutation information for this matcher
119 * @throws MessagingException
120 * if an exception occurs that interrupts the matcher's normal operation
121 */
122 public void init(MatcherConfig newConfig) throws MessagingException {
123 config = newConfig;
124 init();
125 }
126
127 /**
128 * <p>A convenience method which can be overridden so that there's no
129 * need to call super.init(config).</p>
130 *
131 * <p>Instead of overriding init(MatcherConfig), simply override this
132 * method and it will be called by GenericMatcher.init(MatcherConfig config).
133 * The MatcherConfig object can still be retrieved via getMatcherConfig().</p>
134 *
135 * @throws MessagingException
136 * if an exception occurs that interrupts the matcher's normal operation
137 */
138 public void init() throws MessagingException {
139 //Do nothing... can be overridden
140 }
141
142 /**
143 * Writes the specified message to a matcher log file.
144 *
145 * @param message - a String specifying the message to be written to the log file
146 */
147 public void log(String message) {
148 getMailetContext().log(LogLevel.INFO, message);
149 }
150
151 /**
152 * Writes an explanatory message and a stack trace for a given Throwable
153 * exception to the matcher log file.
154 *
155 * @param message - a String that describes the error or exception
156 * @param t - the java.lang.Throwable error or exception
157 */
158 public void log(String message, Throwable t) {
159 getMailetContext().log(LogLevel.ERROR, message, 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<MailAddress> match(Mail mail) throws MessagingException;
176 }