Matcher


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