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 import javax.mail.MessagingException;
23 import javax.mail.internet.MimeMessage;
24 import java.io.Serializable;
25 import java.util.Collection;
26 import java.util.Date;
27 import java.util.Iterator;
28
29 /**
30 * <p>Wraps a MimeMessage with additional routing and processing information.
31 * <p>This includes
32 * <ul>
33 * <li>a unique name</li>
34 * <li>envelope properties such the SMTP-specified sender ("MAIL FROM") and recipients ("RCPT TO")</li>
35 * <li>the IP address and hostname of the sending server</li>
36 * <li>the processing state, which also represents the processor in
37 * the mailet container which is currently processing the message</li>
38 * <li>the time at which the Mail was last updated</li>
39 * <li>additional processing attributes (see below)</li>
40 * </ul>
41 * <p>
42 * The Mail interface also defines constants for special processor names,
43 * such as "root" and "error".
44 * <p>
45 * <b>Mail Attributes</b>
46 * <p>
47 * While processing a Mail instance, a Mailet can associate additional
48 * information with it by using mail attributes. These attributes can
49 * then be queried by the same mailet or other mailets later on.
50 * <p>
51 * Some containers may also use attributes to provide envelope information.
52 * <p>
53 * Every attribute consists of a name and a value.
54 * Attribute names should follow the same convention as package names.
55 * The Mailet API specification reserves names matching
56 * <i>org.apache.james.*</i> and <i>org.apache.mailet.*</i>.
57 * <p>
58 * Attribute values can be arbitrary objects, but since Mail is
59 * Serializable, the attribute value must be Serializable as well.
60 * <p>
61 * The list of attributes which are currently associated with a Mail
62 * instance can be retrieved using the {@link #getAttributeNames}
63 * method, and given its name, the value of an attribute can be
64 * retrieved using the {@link #getAttribute} method. It is also
65 * possible to remove {@link #removeAttribute one} attribute or
66 * {@link #removeAllAttributes() all} attributes of a Mail instance.
67 */
68 public interface Mail extends Serializable, Cloneable {
69 String GHOST = "ghost";
70 String DEFAULT = "root";
71 String ERROR = "error";
72 String TRANSPORT = "transport";
73 /**
74 * Returns the name of this message.
75 *
76 * @return the message name
77 * @since Mailet API v2.3
78 */
79 String getName();
80
81 /**
82 * Set the name of this message.
83 *
84 * @param newName the new message name
85 * @since Mailet API v2.3
86 */
87 void setName(String newName);
88
89 /**
90 * Returns the MimeMessage stored in this message.
91 *
92 * @return the MimeMessage that this Mail object wraps
93 * @throws MessagingException when an error occurs while retrieving the message
94 */
95 MimeMessage getMessage() throws MessagingException;
96
97 /**
98 * Returns the message recipients as a Collection of MailAddress objects,
99 * as specified by the SMTP "RCPT TO" command, or internally defined.
100 *
101 * @return a Collection of MailAddress objects that are recipients of this message
102 */
103 Collection getRecipients();
104
105 /**
106 * Sets the message recipients as a Collection of MailAddress objects.
107 *
108 * @param recipients the message recipients as a Collection of MailAddress Objects
109 * @since Mailet API v2.4
110 */
111 void setRecipients(Collection recipients);
112
113 /**
114 * Returns the sender of the message, as specified by the SMTP "MAIL FROM" command,
115 * or internally defined.
116 *
117 * @return the sender of this message
118 */
119 MailAddress getSender();
120
121 /**
122 * Returns the current state of the message, such as GHOST, ERROR or DEFAULT.
123 *
124 * @return the state of this message
125 */
126 String getState();
127
128 /**
129 * Returns the host name of the remote server that sent this message.
130 *
131 * @return the host name of the remote server that sent this message
132 */
133 String getRemoteHost();
134
135 /**
136 * Returns the IP address of the remote server that sent this message.
137 *
138 * @return the IP address of the remote server that sent this message
139 */
140 String getRemoteAddr();
141
142 /**
143 * The error message, if any, associated with this message.
144 *
145 * @return the error message associated with this message, or null
146 */
147 String getErrorMessage();
148
149 /**
150 * Sets the error message associated with this message.
151 *
152 * @param msg the error message
153 */
154 void setErrorMessage(String msg);
155
156 /**
157 * Sets the MimeMessage wrapped by this Mail instance.
158 *
159 * @param message the new message that this Mail instance will wrap
160 */
161 void setMessage(MimeMessage message);
162
163 /**
164 * Sets the state of this message.
165 *
166 * @param state the new state of this message
167 */
168 void setState(String state);
169
170 /**
171 * Returns the value of the named Mail instance attribute,
172 * or null if the attribute does not exist.
173 *
174 * @param name the attribute name
175 * @return the attribute value, or null if the attribute does not exist
176 * @since Mailet API v2.1
177 */
178 Serializable getAttribute(String name);
179
180 /**
181 * Returns an Iterator over the names of all attributes which are set
182 * in this Mail instance.
183 * <p>
184 * The {@link #getAttribute} method can be called to
185 * retrieve an attribute's value given its name.
186 *
187 * @return an Iterator (of Strings) over all attribute names
188 * @since Mailet API v2.1
189 */
190 Iterator getAttributeNames();
191
192 /**
193 * Returns whether this Mail instance has any attributes set.
194 *
195 * @return true if this Mail instance has any attributes set, false if not
196 * @since Mailet API v2.1
197 */
198 boolean hasAttributes();
199
200 /**
201 * Removes the attribute with the given name from this Mail instance.
202 *
203 * @param name the name of the attribute to be removed
204 * @return the value of the removed attribute, or null
205 * if there was no such attribute (or if the attribute existed
206 * and its value was null)
207 * @since Mailet API v2.1
208 */
209 Serializable removeAttribute(String name);
210
211 /**
212 * Removes all attributes associated with this Mail instance.
213 * @since Mailet API v2.1
214 **/
215 void removeAllAttributes();
216
217 /**
218 * Associates an attribute with the given name and value with this Mail instance.
219 * If an attribute with the given name already exists, it is replaced, and the
220 * previous value is returned.
221 * <p>
222 * Conventionally, attribute names should follow the namespacing guidelines
223 * for Java packages.
224 * The Mailet API specification reserves names matching
225 * <i>org.apache.james.*</i> and <i>org.apache.mailet.*</i>.
226 *
227 * @param name the attribute name
228 * @param object the attribute value
229 * @return the value of the previously existing attribute with the same name,
230 * or null if there was no such attribute (or if the attribute existed
231 * and its value was null)
232 * @since Mailet API v2.1
233 */
234 Serializable setAttribute(String name, Serializable object);
235
236 /**
237 * Returns the message size (including headers).
238 * <p>
239 * This is intended as a guide suitable for processing heuristics, and not
240 * a precise indication of the number of outgoing bytes that would be produced
241 * were the email to be encoded for transport.
242 * In cases where an exact value is not readily available or is difficult to
243 * determine (for example, when the fully transfer encoded message is not available)
244 * a suitable estimate may be returned.
245 *
246 * @return the message size
247 * @throws MessagingException when the size cannot be retrieved
248 * @since Mailet API v2.3
249 */
250 long getMessageSize() throws MessagingException;
251
252 /**
253 * Returns the time at which this Mail was last updated.
254 * @return the time at which this Mail was last updated
255 * @since Mailet API v2.3
256 */
257 Date getLastUpdated();
258
259 /**
260 * Sets the time at which this Mail was last updated.
261 * @param lastUpdated the time at which this Mail was last modified
262 * @since Mailet API v2.3
263 */
264 void setLastUpdated(Date lastUpdated);
265 }