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;
22  
23  import java.util.Collection;
24  import javax.mail.MessagingException;
25  
26  /**
27   * This interface defines the behaviour of the message "routing" inside
28   * the mailet container. At its heart is the {@link #match(Mail)} method,
29   * which inspects a Mail and returns a subset of its recipients which meet
30   * this Matcher's criteria.
31   * <p>
32   * An important feature of the mailet container is the ability to fork
33   * processing of messages. When a message first arrives at the server,
34   * it might have multiple recipients specified. When a message is passed
35   * to a matcher, the matcher might only match some of the listed recipients.
36   * The mailet container should then duplicate the message, splitting the
37   * recipient list across the two messages as per the match result, and
38   * proceed to process them separately.
39   * <p>
40   * The Matcher life cycle is controlled by the mailet container,
41   * which invokes the Matcher methods in the following order:
42   * <ol>
43   * <li>The matcher is constructed.
44   * <li>The {@link #init} method is invoked once to initialize the matcher.
45   * <li>The {@link #match} method is invoked to match mail messages.
46   *     This can occur an unlimited number of times, even concurrently.
47   * <li>At some point, such as when the mailet container is shut down,
48   *     the matcher is taken out of service and then destroyed by invoking
49   *     the {@link #destroy} method once.
50   * </ol>
51   * <p>
52   * In addition to the life-cycle methods, this interface provides the
53   * {@link #getMatcherConfig} method, which provides the Matcher with
54   * its configuration information and a {@link MailetContext} through which
55   * it can interact with the mailet container, and the {@link #getMatcherInfo}
56   * method, which provides basic information about the Matcher.
57   *
58   */
59  public interface Matcher {
60  
61      /**
62       * Initializes this Matcher.
63       * <p>
64       * This method is called only once, and must complete successfully
65       * before the {@link #match} method can be invoked.
66       *
67       * @param config a MatcherConfig containing the matcher's configuration
68       *          and initialization parameters
69       * @throws MessagingException if an error occurs
70       */
71      void init(MatcherConfig config) throws MessagingException;
72  
73      /**
74       * Takes a Mail message, looks at any pertinent information, and returns
75       * a subset of recipients that meet the match conditions.
76       * <p>
77       * Matchers typically run inside multithreaded mailet containers that can handle
78       * multiple requests concurrently. Developers must be aware to synchronize access
79       * to any shared resources such as files, network connections, and as well as the
80       * matcher's fields. More information on multithreaded programming in Java is
81       * available at <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
82       * Java tutorial on multi-threaded programming</a>.
83       *
84       * @param mail the Mail to match
85       * @return the recipients that meet the match criteria as a Collection of String objects
86       * @throws MessagingException if any error occurs which prevents the Mail
87       *         matching from completing successfully
88       */
89      Collection match(Mail mail) throws MessagingException;
90      
91      /**
92       * Destroys this Matcher.
93       * <p>
94       * This method is called only once, after all {@link #match} invocations
95       * have completed (or a timeout period has elapsed). After this method
96       * returns, this Matcher will no longer be used.
97       * <p>
98       * Implementations should use this method to release any resources that
99       * are being held (such as memory, file handles or threads) and make sure
100      * that any persistent information is properly stored.
101      * <p>
102      * Note that containers <code>SHOULD NOT</code> invoke this method before 
103      * {@link #init(MatcherConfig)} has been successfully completed. 
104      */
105     void destroy();
106     
107     /**
108      * Returns a MatcherConfig object, which provides initialization parameters
109      * and a {@link MailetContext} through which it can interact with the
110      * mailet container.
111      * <p>
112      * Implementations of this interface are responsible for storing the
113      * MatcherConfig which they receive in the {@link #init} method so
114      * that this method can return it.
115      *
116      * @return the MatcherConfig that this matcher was initialized with
117      */
118     MatcherConfig getMatcherConfig();
119 
120     /**
121      * Returns information about the matcher, such as author, version and
122      * copyright.
123      *
124      * @return the Mailet information (as a plain text string)
125      */
126     String getMatcherInfo();
127 }