View Javadoc

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 }