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