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