KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > mailet > Mail


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