View Javadoc

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 }