001: /****************************************************************
002: * Licensed to the Apache Software Foundation (ASF) under one *
003: * or more contributor license agreements. See the NOTICE file *
004: * distributed with this work for additional information *
005: * regarding copyright ownership. The ASF licenses this file *
006: * to you under the Apache License, Version 2.0 (the *
007: * "License"); you may not use this file except in compliance *
008: * with the License. You may obtain a copy of the License at *
009: * *
010: * http://www.apache.org/licenses/LICENSE-2.0 *
011: * *
012: * Unless required by applicable law or agreed to in writing, *
013: * software distributed under the License is distributed on an *
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015: * KIND, either express or implied. See the License for the *
016: * specific language governing permissions and limitations *
017: * under the License. *
018: ****************************************************************/package org.apache.mailet;
019:
020: import javax.mail.MessagingException;
021: import javax.mail.internet.MimeMessage;
022: import java.io.Serializable;
023: import java.util.Collection;
024: import java.util.Date;
025: import java.util.Iterator;
026:
027: /**
028: * Wrap a MimeMessage with routing information (from SMTP) such
029: * as SMTP specified recipients, sender, and ip address and hostname
030: * of sending server. It also contains its state which represents
031: * which processor in the mailet container it is currently running.
032: * Special processor names are "root" and "error".
033: *
034: * @version CVS $Revision: 494012 $ $Date: 2007-01-08 11:23:58 +0100 (Mo, 08 Jan 2007) $
035: */
036: public interface Mail extends Serializable, Cloneable {
037: String GHOST = "ghost";
038: String DEFAULT = "root";
039: String ERROR = "error";
040: String TRANSPORT = "transport";
041:
042: /**
043: * Returns the message name of this message
044: *
045: * @return the message name
046: * @since Mailet API v2.3
047: */
048: String getName();
049:
050: /**
051: * Set the message name of this message
052: *
053: * @param newName new name
054: * @since Mailet API v2.3
055: */
056: void setName(String newName);
057:
058: /**
059: * Returns the MimeMessage stored in this message
060: *
061: * @return the MimeMessage that this Mail object wraps
062: * @throws MessagingException - an error occured while loading this object
063: */
064: MimeMessage getMessage() throws MessagingException;
065:
066: /**
067: * Returns a Collection of MailAddress objects that are recipients of this message
068: *
069: * @return a Collection of MailAddress objects that are recipients of this message
070: */
071: Collection getRecipients();
072:
073: /**
074: * Method setRecipients.
075: * @param recipients a Collection of MailAddress Objects representing the recipients of this message
076: * @since Mailet API v3.0-unstable
077: */
078: void setRecipients(Collection recipients);
079:
080: /**
081: * The sender of the message, as specified by the MAIL FROM header, or internally defined
082: *
083: * @return a MailAddress of the sender of this message
084: */
085: MailAddress getSender();
086:
087: /**
088: * The current state of the message, such as GHOST, ERROR, or DEFAULT
089: *
090: * @return the state of this message
091: */
092: String getState();
093:
094: /**
095: * The remote hostname of the server that connected to send this message
096: *
097: * @return a String of the hostname of the server that connected to send this message
098: */
099: String getRemoteHost();
100:
101: /**
102: * The remote ip address of the server that connected to send this message
103: *
104: * @return a String of the ip address of the server that connected to send this message
105: */
106: String getRemoteAddr();
107:
108: /**
109: * The error message, if any, associated with this message. Not sure why this is needed.
110: *
111: * @return a String of a descriptive error message
112: */
113: String getErrorMessage();
114:
115: /**
116: * Sets the error message associated with this message. Not sure why this is needed.
117: *
118: * @param msg - a descriptive error message
119: */
120: void setErrorMessage(String msg);
121:
122: /**
123: * Sets the MimeMessage associated with this message via the object.
124: *
125: * @param message - the new MimeMessage that this Mail object will wrap
126: */
127: void setMessage(MimeMessage message);
128:
129: /**
130: * Sets the state of this message.
131: *
132: * @param state - the new state of this message
133: */
134: void setState(String state);
135:
136: /**
137: * Returns the Mail session attribute with the given name, or null
138: * if there is no attribute by that name.
139: * An attribute allows a mailet to give this Mail instance additional information
140: * not already provided by this interface.<p>
141: * A list of currently set attributes can be retrieved using getAttributeNames.
142: * <p>
143: * The attribute is returned as a java.lang.Object or some subclass. Attribute
144: * names should follow the same convention as package names. The Mailet API
145: * specification reserves names matching <I>org.apache.james.*</I>
146: * and <I>org.apache.mailet.*</I>.
147: *
148: * @param name - a String specifying the name of the attribute
149: * @return an Object containing the value of the attribute, or null if no attribute
150: * exists matching the given name
151: * @since Mailet API v2.1
152: */
153: Serializable getAttribute(String name);
154:
155: /**
156: * Returns an Iterator containing the attribute names currently available within
157: * this Mail instance. Use the getAttribute(java.lang.String) method with an
158: * attribute name to get the value of an attribute.
159: *
160: * @return an Iterator of attribute names
161: * @since Mailet API v2.1
162: */
163: Iterator getAttributeNames();
164:
165: /**
166: * @return true if this Mail instance has any attributes set.
167: * @since Mailet API v2.1
168: **/
169: boolean hasAttributes();
170:
171: /**
172: * Removes the attribute with the given name from this Mail instance. After
173: * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
174: * the attribute's value will return null.
175: *
176: * @param name - a String specifying the name of the attribute to be removed
177: * @return previous attribute value associated with specified name, or null
178: * if there was no mapping for name (null can also mean that null
179: * was bound to the name)
180: * @since Mailet API v2.1
181: */
182: Serializable removeAttribute(String name);
183:
184: /**
185: * Removes all the attributes associated with this Mail instance.
186: * @since Mailet API v2.1
187: **/
188: void removeAllAttributes();
189:
190: /**
191: * Binds an object to a given attribute name in this Mail instance. If the name
192: * specified is already used for an attribute, this method will remove the old
193: * attribute and bind the name to the new attribute.
194: * As instances of Mail is Serializable, it is necessary that the attributes being
195: * Serializable as well
196: * <p>
197: * Attribute names should follow the same convention as package names.
198: * The Mailet API specification reserves names matching <I>org.apache.james.*</I>
199: * and <I>org.apache.mailet.*</I>.
200: *
201: * @param name - a String specifying the name of the attribute
202: * @param object - a Serializable Object representing the attribute to be bound
203: * @return the object previously bound to the name, null if the name was
204: * not bound (null can also mean that null was bound to the name)
205: * @since Mailet API v2.1
206: */
207: Serializable setAttribute(String name, Serializable object);
208:
209: /**
210: * @return message size
211: * @since Mailet API v2.3
212: */
213: long getMessageSize() throws MessagingException;
214:
215: /**
216: * @return the last update date
217: * @since Mailet API v2.3
218: */
219: Date getLastUpdated();
220:
221: /**
222: * @param lastUpdated the new last updated date
223: * @since Mailet API v2.3
224: */
225: void setLastUpdated(Date lastUpdated);
226: }
|