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 }