View Javadoc

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