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