001: /****************************************************************
002: * Licensed to the Apache Software Foundation (ASF) under one *
003: * or more contributor license agreements. See the NOTICE file *
004: * distributed with this work for additional information *
005: * regarding copyright ownership. The ASF licenses this file *
006: * to you under the Apache License, Version 2.0 (the *
007: * "License"); you may not use this file except in compliance *
008: * with the License. You may obtain a copy of the License at *
009: * *
010: * http://www.apache.org/licenses/LICENSE-2.0 *
011: * *
012: * Unless required by applicable law or agreed to in writing, *
013: * software distributed under the License is distributed on an *
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015: * KIND, either express or implied. See the License for the *
016: * specific language governing permissions and limitations *
017: * under the License. *
018: ****************************************************************/package org.apache.mailet;
019:
020: import java.util.Collection;
021:
022: /**
023: * This interface define the behaviour of the message "routing" inside
024: * the mailet container. The match(Mail) method returns a Collection of
025: * recipients that meet this class's criteria.
026: * <p>
027: * An important feature of the mailet container is the ability to fork
028: * processing of messages. When a message first arrives at the server,
029: * it might have multiple recipients specified. As a message is passed
030: * to a matcher, the matcher might only "match" one of the listed
031: * recipients. It would then return only the matching recipient in
032: * the Collection. The mailet container should then duplicate the
033: * message splitting the recipient list across the two messages as per
034: * what the matcher returned.
035: * <p>
036: * <b>[THIS PARAGRAPH NOT YET IMPLEMENTED]</b>
037: * <i>The matcher can extend this forking to further separation by returning
038: * a Collection of Collection objects. This allows a matcher to fork
039: * multiple processes if there are multiple recipients that require
040: * separate processing. For example, we could write a ListservMatcher
041: * that handles multiple listservs. When someone cross-posts across
042: * multiple listservs that this matcher handles, it could put each
043: * listserv address (recipient) that it handles in a separate Collection
044: * object. By returning each of these Collections within a container
045: * Collection object, it could indicate to the mailet container how
046: * many forks to spawn.</i>
047: * <p>
048: * This interface defines methods to initialize a matcher, to match
049: * messages, and to remove a matcher from the server. These are known
050: * as life-cycle methods and are called in the following sequence:
051: * <ol>
052: * <li>The matcher is constructed, then initialized with the init method.</li>
053: * <li>Any calls from clients to the match method are handled.</li>
054: * <li>The matcher is taken out of service, then destroyed with the
055: * destroy method, then garbage collected and finalized.</li>
056: * </ol>
057: * In addition to the life-cycle methods, this interface provides the
058: * getMatcherConfig method, which the matcher can use to get any startup
059: * information, and the getMatcherInfo method, which allows the matcher
060: * to return basic information about itself, such as author, version,
061: * and copyright.
062: *
063: * @version 1.0.0, 24/04/1999
064: */
065: public interface Matcher {
066:
067: /**
068: * Called by the mailet container to indicate to a matcher that the matcher
069: * is being taken out of service. This method is only called once all threads
070: * within the matcher's service method have exited or after a timeout period
071: * has passed. After the mailet container calls this method, it will not call
072: * the match method again on this matcher.
073: * <p>
074: * This method gives the matcher an opportunity to clean up any resources that
075: * are being held (for example, memory, file handles, threads) and make sure
076: * that any persistent state is synchronized with the matcher's current state in memory.
077: */
078: void destroy();
079:
080: /**
081: * Returns a MatcherConfig object, which contains initialization and
082: * startup parameters for this matcher.
083: * <p>
084: * Implementations of this interface are responsible for storing the
085: * MatcherConfig object so that this method can return it. The GenericMatcher
086: * class, which implements this interface, already does this.
087: *
088: * @return the MatcherConfig object that initializes this matcher
089: */
090: MatcherConfig getMatcherConfig();
091:
092: /**
093: * Returns information about the matcher, such as author, version, and copyright.
094: * <p>
095: * The string that this method returns should be plain text and not markup
096: * of any kind (such as HTML, XML, etc.).
097: *
098: * @return a String containing matcher information
099: */
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)
116: throws javax.mail.MessagingException;
117:
118: /**
119: * Takes a Mail message, looks at any pertinent information, and then returns a subset
120: * of recipients that meet the "match" conditions.
121: * <p>
122: * This method is only called after the matcher's init() method has completed
123: * successfully.
124: * <p>
125: * Matchers typically run inside multithreaded mailet containers that can handle
126: * multiple requests concurrently. Developers must be aware to synchronize access
127: * to any shared resources such as files, network connections, and as well as the
128: * matcher's class and instance variables. More information on multithreaded
129: * programming in Java is available in <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
130: * Java tutorial on multi-threaded programming</a>.
131: *
132: * @param mail - the Mail object that contains the message and routing information
133: * @return a Collection of String objects (recipients) that meet the match criteria
134: * @throws MessagingException - if an message or address parsing exception occurs or
135: * an exception that interferes with the matcher's normal operation
136: */
137: Collection match(Mail mail) throws javax.mail.MessagingException;
138: }
|