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 }