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 java.util.Collection;
23  
24  /***
25   * This interface define the behaviour of the message "routing" inside
26   * the mailet container. The match(Mail) method returns a Collection of
27   * recipients that meet this class's criteria.
28   * <p>
29   * An important feature of the mailet container is the ability to fork
30   * processing of messages.  When a message first arrives at the server,
31   * it might have multiple recipients specified.  As a message is passed
32   * to a matcher, the matcher might only "match" one of the listed
33   * recipients.  It would then return only the matching recipient in
34   * the Collection.  The mailet container should then duplicate the
35   * message splitting the recipient list across the two messages as per
36   * what the matcher returned.
37   * <p>
38   * <b>[THIS PARAGRAPH NOT YET IMPLEMENTED]</b>
39   * <i>The matcher can extend this forking to further separation by returning
40   * a Collection of Collection objects.  This allows a matcher to fork
41   * multiple processes if there are multiple recipients that require
42   * separate processing.  For example, we could write a ListservMatcher
43   * that handles multiple listservs.  When someone cross-posts across
44   * multiple listservs that this matcher handles, it could put each
45   * listserv address (recipient) that it handles in a separate Collection
46   * object.  By returning each of these Collections within a container
47   * Collection object, it could indicate to the mailet container how
48   * many forks to spawn.</i>
49   * <p>
50   * This interface defines methods to initialize a matcher, to match
51   * messages, and to remove a matcher from the server. These are known
52   * as life-cycle methods and are called in the following sequence:
53   * <ol>
54   * <li>The matcher is constructed, then initialized with the init method.</li>
55   * <li>Any calls from clients to the match method are handled.</li>
56   * <li>The matcher is taken out of service, then destroyed with the
57   *      destroy method, then garbage collected and finalized.</li>
58   * </ol>
59   * In addition to the life-cycle methods, this interface provides the
60   * getMatcherConfig method, which the matcher can use to get any startup
61   * information, and the getMatcherInfo method, which allows the matcher
62   * to return basic information about itself, such as author, version,
63   * and copyright.
64   *
65   * @version 1.0.0, 24/04/1999
66   */
67  public interface Matcher {
68  
69      /***
70       * Called by the mailet container to indicate to a matcher that the matcher
71       * is being taken out of service. This method is only called once all threads
72       * within the matcher's service method have exited or after a timeout period
73       * has passed. After the mailet container calls this method, it will not call
74       * the match method again on this matcher.
75       * <p>
76       * This method gives the matcher an opportunity to clean up any resources that
77       * are being held (for example, memory, file handles, threads) and make sure
78       * that any persistent state is synchronized with the matcher's current state in memory.
79       */
80      void destroy();
81  
82      /***
83       * Returns a MatcherConfig object, which contains initialization and
84       * startup parameters for this matcher.
85       * <p>
86       * Implementations of this interface are responsible for storing the
87       * MatcherConfig object so that this method can return it. The GenericMatcher
88       * class, which implements this interface, already does this.
89       *
90       * @return the MatcherConfig object that initializes this matcher
91       */
92      MatcherConfig getMatcherConfig();
93  
94      /***
95       * Returns information about the matcher, such as author, version, and copyright.
96       * <p>
97       * The string that this method returns should be plain text and not markup
98       * of any kind (such as HTML, XML, etc.).
99       *
100      * @return a String containing matcher information
101      */
102     String getMatcherInfo();
103 
104     /***
105      * Called by the mailet container to indicate to a matcher that the
106      * matcher is being placed into service.
107      * <p>
108      * The mailet container calls the init method exactly once after instantiating
109      * the matcher. The init method must complete successfully before the matcher
110      * can receive any messages.
111      *
112      * @param config - a MatcherConfig object containing the matcher's configuration
113      *          and initialization parameters
114      * @throws javax.mail.MessagingException - if an exception has occurred that
115      *          interferes with the matcher's normal operation
116      */
117     void init( MatcherConfig config ) throws javax.mail.MessagingException;
118 
119     /***
120      * Takes a Mail message, looks at any pertinent information, and then returns a subset
121      * of recipients that meet the "match" conditions.
122      * <p>
123      * This method is only called after the matcher's init() method has completed
124      * successfully.
125      * <p>
126      * Matchers typically run inside multithreaded mailet containers that can handle
127      * multiple requests concurrently. Developers must be aware to synchronize access
128      * to any shared resources such as files, network connections, and as well as the
129      * matcher's class and instance variables. More information on multithreaded
130      * programming in Java is available in <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
131      * Java tutorial on multi-threaded programming</a>.
132      *
133      * @param mail - the Mail object that contains the message and routing information
134      * @return a Collection of String objects (recipients) that meet the match criteria
135      * @throws MessagingException - if an message or address parsing exception occurs or
136      *      an exception that interferes with the matcher's normal operation
137      */
138     Collection match( Mail mail ) throws javax.mail.MessagingException;
139 }