GenericMatcher


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