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 package org.apache.mailet;
21 import javax.mail.MessagingException;
22 import javax.mail.internet.MimeMessage;
23 import java.io.Serializable;
24 import java.util.Collection;
25 import java.util.Date;
26 import java.util.Iterator;
27
28 /***
29 * Wrap a MimeMessage with routing information (from SMTP) such
30 * as SMTP specified recipients, sender, and ip address and hostname
31 * of sending server. It also contains its state which represents
32 * which processor in the mailet container it is currently running.
33 * Special processor names are "root" and "error".
34 *
35 * @version CVS $Revision: 494012 $ $Date: 2007-01-08 10:23:58 +0000 (Mon, 08 Jan 2007) $
36 */
37 public interface Mail extends Serializable, Cloneable {
38 String GHOST = "ghost";
39 String DEFAULT = "root";
40 String ERROR = "error";
41 String TRANSPORT = "transport";
42 /***
43 * Returns the message name of this message
44 *
45 * @return the message name
46 * @since Mailet API v2.3
47 */
48 String getName();
49 /***
50 * Set the message name of this message
51 *
52 * @param newName new name
53 * @since Mailet API v2.3
54 */
55 void setName(String newName);
56 /***
57 * Returns the MimeMessage stored in this message
58 *
59 * @return the MimeMessage that this Mail object wraps
60 * @throws MessagingException - an error occured while loading this object
61 */
62 MimeMessage getMessage() throws MessagingException;
63 /***
64 * Returns a Collection of MailAddress objects that are recipients of this message
65 *
66 * @return a Collection of MailAddress objects that are recipients of this message
67 */
68 Collection getRecipients();
69 /***
70 * Method setRecipients.
71 * @param recipients a Collection of MailAddress Objects representing the recipients of this message
72 * @since Mailet API v3.0-unstable
73 */
74 void setRecipients(Collection recipients);
75 /***
76 * The sender of the message, as specified by the MAIL FROM header, or internally defined
77 *
78 * @return a MailAddress of the sender of this message
79 */
80 MailAddress getSender();
81 /***
82 * The current state of the message, such as GHOST, ERROR, or DEFAULT
83 *
84 * @return the state of this message
85 */
86 String getState();
87 /***
88 * The remote hostname of the server that connected to send this message
89 *
90 * @return a String of the hostname of the server that connected to send this message
91 */
92 String getRemoteHost();
93 /***
94 * The remote ip address of the server that connected to send this message
95 *
96 * @return a String of the ip address of the server that connected to send this message
97 */
98 String getRemoteAddr();
99 /***
100 * The error message, if any, associated with this message. Not sure why this is needed.
101 *
102 * @return a String of a descriptive error message
103 */
104 String getErrorMessage();
105 /***
106 * Sets the error message associated with this message. Not sure why this is needed.
107 *
108 * @param msg - a descriptive error message
109 */
110 void setErrorMessage(String msg);
111 /***
112 * Sets the MimeMessage associated with this message via the object.
113 *
114 * @param message - the new MimeMessage that this Mail object will wrap
115 */
116 void setMessage(MimeMessage message);
117 /***
118 * Sets the state of this message.
119 *
120 * @param state - the new state of this message
121 */
122 void setState(String state);
123 /***
124 * Returns the Mail session attribute with the given name, or null
125 * if there is no attribute by that name.
126 * An attribute allows a mailet to give this Mail instance additional information
127 * not already provided by this interface.<p>
128 * A list of currently set attributes can be retrieved using getAttributeNames.
129 * <p>
130 * The attribute is returned as a java.lang.Object or some subclass. Attribute
131 * names should follow the same convention as package names. The Mailet API
132 * specification reserves names matching <I>org.apache.james.*</I>
133 * and <I>org.apache.mailet.*</I>.
134 *
135 * @param name - a String specifying the name of the attribute
136 * @return an Object containing the value of the attribute, or null if no attribute
137 * exists matching the given name
138 * @since Mailet API v2.1
139 */
140 Serializable getAttribute(String name);
141 /***
142 * Returns an Iterator containing the attribute names currently available within
143 * this Mail instance. Use the getAttribute(java.lang.String) method with an
144 * attribute name to get the value of an attribute.
145 *
146 * @return an Iterator of attribute names
147 * @since Mailet API v2.1
148 */
149 Iterator getAttributeNames();
150 /***
151 * @return true if this Mail instance has any attributes set.
152 * @since Mailet API v2.1
153 **/
154 boolean hasAttributes();
155 /***
156 * Removes the attribute with the given name from this Mail instance. After
157 * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
158 * the attribute's value will return null.
159 *
160 * @param name - a String specifying the name of the attribute to be removed
161 * @return previous attribute value associated with specified name, or null
162 * if there was no mapping for name (null can also mean that null
163 * was bound to the name)
164 * @since Mailet API v2.1
165 */
166 Serializable removeAttribute(String name);
167 /***
168 * Removes all the attributes associated with this Mail instance.
169 * @since Mailet API v2.1
170 **/
171 void removeAllAttributes();
172 /***
173 * Binds an object to a given attribute name in this Mail instance. If the name
174 * specified is already used for an attribute, this method will remove the old
175 * attribute and bind the name to the new attribute.
176 * As instances of Mail is Serializable, it is necessary that the attributes being
177 * Serializable as well
178 * <p>
179 * Attribute names should follow the same convention as package names.
180 * The Mailet API specification reserves names matching <I>org.apache.james.*</I>
181 * and <I>org.apache.mailet.*</I>.
182 *
183 * @param name - a String specifying the name of the attribute
184 * @param object - a Serializable Object representing the attribute to be bound
185 * @return the object previously bound to the name, null if the name was
186 * not bound (null can also mean that null was bound to the name)
187 * @since Mailet API v2.1
188 */
189 Serializable setAttribute(String name, Serializable object);
190 /***
191 * @return message size
192 * @since Mailet API v2.3
193 */
194 long getMessageSize() throws MessagingException;
195 /***
196 * @return the last update date
197 * @since Mailet API v2.3
198 */
199 Date getLastUpdated();
200 /***
201 * @param lastUpdated the new last updated date
202 * @since Mailet API v2.3
203 */
204 void setLastUpdated(Date lastUpdated);
205 }