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