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