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 21 package org.apache.mailet.base; 22 23 import javax.mail.MessagingException; 24 25 import org.apache.mailet.Mail; 26 import org.apache.mailet.Mailet; 27 import org.apache.mailet.MailetConfig; 28 import org.apache.mailet.MailetContext; 29 30 import java.util.ArrayList; 31 import java.util.Collection; 32 import java.util.HashSet; 33 import java.util.Iterator; 34 35 /** 36 * GenericMailet makes writing mailets easier. It provides simple 37 * versions of the lifecycle methods init and destroy and of the methods 38 * in the MailetConfig interface. GenericMailet also implements the log 39 * method, declared in the MailetContext interface. 40 * <p> 41 * To write a generic mailet, you need only override the abstract service 42 * method. 43 * 44 * @version 1.0.0, 24/04/1999 45 */ 46 public abstract class GenericMailet implements Mailet, MailetConfig { 47 private MailetConfig config = null; 48 49 /** 50 * Called by the mailer container to indicate to a mailet that the 51 * mailet is being taken out of service. 52 */ 53 public void destroy() { 54 //Do nothing 55 } 56 57 /** 58 * <p>Gets a boolean valued init parameter.</p> 59 * <p>A convenience method. The result is parsed 60 * from the value of the named parameter in the {@link MailetConfig}.</p> 61 * @param name name of the init parameter to be queried 62 * @param defaultValue this value will be substituted when the named value 63 * cannot be parse or when the init parameter is absent 64 * @return true when the init parameter is <code>true</code> (ignoring case); 65 * false when the init parameter is <code>false</code> (ignoring case); 66 * otherwise the default value 67 * @throws NullPointerException before {@link #init(MailetConfig)} 68 */ 69 public boolean getInitParameter(String name, boolean defaultValue) { 70 if (config == null) { 71 throw new NullPointerException("Mailet configuration must be set before getInitParameter is called."); 72 } 73 return MailetUtil.getInitParameter(config, name, defaultValue); 74 } 75 76 /** 77 * Returns a String containing the value of the named initialization 78 * parameter, or null if the parameter does not exist. 79 * <p> 80 * This method is supplied for convenience. It gets the value of the 81 * named parameter from the mailet's MailetConfig object. 82 * 83 * @param name - a String specifying the name of the initialization parameter 84 * @return a String containing the value of the initalization parameter 85 */ 86 public String getInitParameter(String name) { 87 return config.getInitParameter(name); 88 } 89 90 /** 91 * Returns a String containing the value of the named initialization 92 * parameter, or defValue if the parameter does not exist. 93 * <p> 94 * This method is supplied for convenience. It gets the value of the 95 * named parameter from the mailet's MailetConfig object. 96 * 97 * @param name - a String specifying the name of the initialization parameter 98 * @param defValue - a String specifying the default value when the parameter 99 * is not present 100 * @return a String containing the value of the initalization parameter 101 */ 102 public String getInitParameter(String name, String defValue) { 103 String res = config.getInitParameter(name); 104 if (res == null) { 105 return defValue; 106 } else { 107 return res; 108 } 109 } 110 111 /** 112 * Returns the names of the mailet's initialization parameters as an 113 * Iterator of String objects, or an empty Iterator if the mailet has no 114 * initialization parameters. 115 * <p> 116 * This method is supplied for convenience. It gets the parameter names from 117 * the mailet's MailetConfig object. 118 * 119 * @return an Iterator of String objects containing the names of 120 * the mailet's initialization parameters 121 */ 122 public Iterator getInitParameterNames() { 123 return config.getInitParameterNames(); 124 } 125 126 /** 127 * Returns this Mailet's MailetConfig object. 128 * 129 * @return the MailetConfig object that initialized this mailet 130 */ 131 public MailetConfig getMailetConfig() { 132 return config; 133 } 134 135 /** 136 * Returns a reference to the MailetContext in which this mailet is 137 * running. 138 * 139 * @return the MailetContext object passed to this mailet by the init method 140 */ 141 public MailetContext getMailetContext() { 142 return getMailetConfig().getMailetContext(); 143 } 144 145 /** 146 * Returns information about the mailet, such as author, version, and 147 * copyright. By default, this method returns an empty string. Override 148 * this method to have it return a meaningful value. 149 * 150 * @return information about this mailet, by default an empty string 151 */ 152 public String getMailetInfo() { 153 return ""; 154 } 155 156 /** 157 * Returns the name of this mailet instance. 158 * 159 * @return the name of this mailet instance 160 */ 161 public String getMailetName() { 162 return config.getMailetName(); 163 } 164 165 166 /** 167 * <p>Called by the mailet container to indicate to a mailet that the 168 * mailet is being placed into service.</p> 169 * 170 * <p>This implementation stores the MailetConfig object it receives from 171 * the mailet container for later use. When overriding this form of the 172 * method, call super.init(config).</p> 173 * 174 * @param newConfig - the MailetConfig object that contains 175 * configutation information for this mailet 176 * @throws MessagingException 177 * if an exception occurs that interrupts the mailet's normal operation 178 */ 179 public void init(MailetConfig newConfig) throws MessagingException { 180 config = newConfig; 181 init(); 182 } 183 184 /** 185 * <p>A convenience method which can be overridden so that there's no 186 * need to call super.init(config).</p> 187 * 188 * Instead of overriding init(MailetConfig), simply override this 189 * method and it will be called by GenericMailet.init(MailetConfig config). 190 * The MailetConfig object can still be retrieved via getMailetConfig(). 191 * 192 * @throws MessagingException 193 * if an exception occurs that interrupts the mailet's normal operation 194 */ 195 public void init() throws MessagingException { 196 //Do nothing... can be overriden 197 } 198 199 /** 200 * Writes the specified message to a mailet log file. 201 * 202 * @param message - a String specifying the message to be written to the log file 203 */ 204 public void log(String message) { 205 getMailetContext().log(message); 206 } 207 208 /** 209 * Writes an explanatory message and a stack trace for a given Throwable 210 * exception to the mailet log file. 211 * 212 * @param message - a String that describes the error or exception 213 * @param t - the java.lang.Throwable to be logged 214 */ 215 public void log(String message, Throwable t) { 216 getMailetContext().log(message, t); 217 } 218 219 /** 220 * <p>Called by the mailet container to allow the mailet to process a 221 * message.</p> 222 * 223 * <p>This method is declared abstract so subclasses must override it.</p> 224 * 225 * @param mail - the Mail object that contains the MimeMessage and 226 * routing information 227 * @throws javax.mail.MessagingException - if an exception occurs that interferes with the mailet's normal operation 228 */ 229 public abstract void service(Mail mail) throws javax.mail.MessagingException; 230 231 232 233 /** 234 * Utility method: Checks if there are unallowed init parameters specified in the 235 * configuration file against the String[] allowedInitParameters. 236 * @param allowedArray array of strings containing the allowed parameter names 237 * @throws MessagingException if an unknown parameter name is found 238 */ 239 protected final void checkInitParameters(String[] allowedArray) throws MessagingException { 240 // if null then no check is requested 241 if (allowedArray == null) { 242 return; 243 } 244 245 Collection allowed = new HashSet(); 246 Collection bad = new ArrayList(); 247 248 for (int i = 0; i < allowedArray.length; i++) { 249 allowed.add(allowedArray[i]); 250 } 251 252 Iterator iterator = getInitParameterNames(); 253 while (iterator.hasNext()) { 254 String parameter = (String) iterator.next(); 255 if (!allowed.contains(parameter)) { 256 bad.add(parameter); 257 } 258 } 259 260 if (bad.size() > 0) { 261 throw new MessagingException("Unexpected init parameters found: " 262 + arrayToString(bad.toArray())); 263 } 264 } 265 266 /** 267 * Utility method for obtaining a string representation of an array of Objects. 268 */ 269 protected final String arrayToString(Object[] array) { 270 if (array == null) { 271 return "null"; 272 } 273 StringBuffer sb = new StringBuffer(1024); 274 sb.append("["); 275 for (int i = 0; i < array.length; i++) { 276 if (i > 0) { 277 sb.append(","); 278 } 279 sb.append(array[i]); 280 } 281 sb.append("]"); 282 return sb.toString(); 283 } 284 285 } 286 287