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: ****************************************************************/package org.apache.mailet;
019:
020: import javax.mail.MessagingException;
021: import java.util.Collection;
022:
023: /**
024: * <p>GenericMatcher implements the Matcher and MatcherConfig interfaces.</p>
025: * <p>GenericMatcher makes writing matchers easier. It provides simple versions of
026: * the lifecycle methods init and destroy and of the methods in the MatcherConfig
027: * interface. GenericMatcher also implements the log method, declared in the
028: * MatcherContext interface.</p>
029: *
030: * <p>To write a generic matcher, you need only override the abstract match method.</p>
031: *
032: * @version 1.0.0, 24/04/1999
033: */
034: public abstract class GenericMatcher implements Matcher, MatcherConfig {
035: MatcherConfig config = null;
036:
037: /**
038: * Called by the mailet container to indicate to a matcher that the
039: * matcher is being taken out of service.
040: */
041: public void destroy() {
042: //Do nothing
043: }
044:
045: /**
046: * <p>Returns a String containing the value of the named initialization
047: * parameter, or null if the parameter does not exist.</p>
048: *
049: * <p>This method is supplied for convenience. It gets the value of the
050: * named parameter from the matcher's MatcherConfig object.</p>
051: *
052: * @return String a String containing the value of the initalization parameter
053: */
054: public String getCondition() {
055: return config.getCondition();
056: }
057:
058: /**
059: * Returns this matcher's MatcherConfig object.
060: *
061: * @return MatcherConfig the MatcherConfig object that initialized this matcher
062: */
063: public MatcherConfig getMatcherConfig() {
064: return config;
065: }
066:
067: /**
068: * Returns a reference to the MailetContext in which this matcher is
069: * running.
070: *
071: * @return MailetContext the MailetContext object passed to this matcher by the init method
072: */
073: public MailetContext getMailetContext() {
074: return getMatcherConfig().getMailetContext();
075: }
076:
077: /**
078: * Returns information about the matcher, such as author, version, and
079: * copyright. By default, this method returns an empty string. Override
080: * this method to have it return a meaningful value.
081: *
082: * @return String information about this matcher, by default an empty string
083: */
084: public String getMatcherInfo() {
085: return "";
086: }
087:
088: /**
089: * Returns the name of this matcher instance.
090: *
091: * @return the name of this matcher instance
092: */
093: public String getMatcherName() {
094: return config.getMatcherName();
095: }
096:
097: /**
098: * <p>Called by the matcher container to indicate to a matcher that the
099: * matcher is being placed into service.</p>
100: *
101: * <p>This implementation stores the MatcherConfig object it receives from
102: * the matcher container for alter use. When overriding this form of the
103: * method, call super.init(config).</p>
104: *
105: * @param MatcherConfig config - the MatcherConfig object that contains
106: * configutation information for this matcher
107: * @throws MessagingException
108: * if an exception occurs that interrupts the matcher's normal operation
109: */
110: public void init(MatcherConfig newConfig) throws MessagingException {
111: config = newConfig;
112: init();
113: }
114:
115: /**
116: * <p>A convenience method which can be overridden so that there's no
117: * need to call super.init(config).</p>
118: *
119: * <p>Instead of overriding init(MatcherConfig), simply override this
120: * method and it will be called by GenericMatcher.init(MatcherConfig config).
121: * The MatcherConfig object can still be retrieved via getMatcherConfig().</p>
122: *
123: * @throws MatcherException
124: * if an exception occurs that interrupts the matcher's normal operation
125: */
126: public void init() throws MessagingException {
127: //Do nothing... can be overridden
128: }
129:
130: /**
131: * Writes the specified message to a matcher log file, prepended by
132: * the matcher's name.
133: *
134: * @param msg - a String specifying the message to be written to the log file
135: */
136: public void log(String message) {
137: StringBuffer logBuffer = new StringBuffer(256).append(
138: getMatcherName()).append(": ").append(message);
139: getMailetContext().log(logBuffer.toString());
140: }
141:
142: /**
143: * Writes an explanatory message and a stack trace for a given Throwable
144: * exception to the matcher log file, prepended by the matcher's name.
145: *
146: * @param message - a String that describes the error or exception
147: * @param t - the java.lang.Throwable error or exception
148: */
149: public void log(String message, Throwable t) {
150: StringBuffer logBuffer = new StringBuffer(256).append(
151: getMatcherName()).append(": ").append(message);
152: getMailetContext().log(logBuffer.toString(), t);
153: }
154:
155: /**
156: * <p>Called by the matcher container to allow the matcher to process a
157: * message.</p>
158: *
159: * <p>This method is declared abstract so subclasses must override it.</p>
160: *
161: * @param mail - the Mail object that contains the MimeMessage and
162: * routing information
163: * @return java.util.Collection - the recipients that the mailet container should have the
164: * mailet affect.
165: * @throws javax.mail.MessagingException - if an exception occurs that interferes with the mailet's normal operation
166: * occurred
167: */
168: public abstract Collection match(Mail mail)
169: throws MessagingException;
170: }
|