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 javax.mail.MessagingException; 24 25 /** 26 * A Mailet processes mail messages. 27 * <p> 28 * The Mailet life cycle is controlled by the mailet container, 29 * which invokes the Mailet methods in the following order: 30 * <ol> 31 * <li>The mailet is constructed. 32 * <li>The {@link #init} method is invoked once to initialize the mailet. 33 * <li>The {@link #service} method is invoked to process mail messages. 34 * This can occur an unlimited number of times, even concurrently. 35 * <li>At some point, such as when the mailet container is shut down, 36 * the mailet is taken out of service and then destroyed by invoking 37 * the {@link #destroy} method once. 38 * </ol> 39 * <p> 40 * In addition to the life-cycle methods, this interface provides the 41 * {@link #getMailetConfig} method, which provides the Mailet with 42 * its initialization parameters and a {@link MailetContext} through which 43 * it can interact with the mailet container, and the {@link #getMailetInfo} 44 * method, which provides basic information about the Mailet. 45 * <p> 46 * Mailets are grouped by the mailet container's configuration into processors. 47 * Each processor is comprised of an ordered sequence of Mailets, each with a 48 * corresponding {@link Matcher}. A Mail message is processed by each 49 * Matcher-Mailet pair in order: If the mail is matched by the Matcher, it is 50 * passed to the Mailet's {@code service} method for processing, and if it is 51 * not matched, the Mailet is skipped and the mail moves on to the next 52 * Matcher-Mailet pair. 53 * <p> 54 * The {@code service} method performs all needed processing on the Mail, 55 * and may modify the message content, recipients, attributes, state, etc. 56 * When the method returns, the mail is passed on to the next Matcher-Mailer 57 * pair in the processor. If there are no subsequent mailets in the processor, 58 * it is moved to the error processor. 59 * Setting the Mail {@link Mail#setState state} to {@link Mail#GHOST}, or clearing its 60 * recipient list, both mean that no further processing is needed, which will 61 * cause the Mail to be dropped without ever reaching subsequent Mailets. 62 * <p> 63 * Instead of creating new messages, the mailet can put a message with new recipients 64 * at the top of the mail queue, or insert them immediately after it's execution 65 * through the API are provided by the MailetContext interface. 66 */ 67 public interface Mailet { 68 69 /** 70 * Initializes this Mailet. 71 * <p> 72 * This method is called only once, and must complete successfully 73 * before the {@link #service} method can be invoked. 74 * 75 * @param config a MailetConfig containing the mailet's configuration 76 * and initialization parameters 77 * @throws MessagingException if an error occurs 78 */ 79 void init(MailetConfig config) throws MessagingException; 80 81 /** 82 * Services a mail message. 83 * <p> 84 * Mailets typically run inside multithreaded mailet containers that can handle 85 * multiple requests concurrently. Developers must be aware to synchronize access 86 * to any shared resources such as files and network connections, as well as the 87 * mailet's fields. More information on multithreaded programming in Java is 88 * available at <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the 89 * Java tutorial on multi-threaded programming</a>. 90 * 91 * @param mail the Mail to process 92 * @throws MessagingException if any error occurs which prevents the Mail 93 * processing from completing successfully 94 */ 95 void service(Mail mail) throws MessagingException; 96 97 /** 98 * Destroys this Mailet. 99 * <p> 100 * This method is called only once, after all {@link #service} invocations 101 * have completed (or a timeout period has elapsed). After this method 102 * returns, this Mailet will no longer be used. 103 * <p> 104 * Implementations should use this method to release any resources that 105 * are being held (such as memory, file handles or threads) and make sure 106 * that any persistent information is properly stored. 107 */ 108 void destroy(); 109 110 /** 111 * Returns a MailetConfig object, which provides initialization parameters 112 * and a {@link MailetContext} through which it can interact with the 113 * mailet container. 114 * <p> 115 * Implementations of this interface are responsible for storing the 116 * MailetConfig which they receive in the {@link #init} method so 117 * that this method can return it. 118 * 119 * @return the MailetConfig that this mailet was initialized with 120 */ 121 MailetConfig getMailetConfig(); 122 123 /** 124 * Returns information about the mailet, such as author, version and 125 * copyright. 126 * 127 * @return the Mailet information (as a plain text string) 128 */ 129 String getMailetInfo(); 130 131 }