mail.java

java mail,java mailjava mailjava mailjava mail

/****************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
 ****************************************************************/

package org.apache.mailet;
import javax.mail.MessagingException;
import javax.mail.internet.MimeMessage;
import java.io.Serializable;
import java.util.Collection;
import java.util.Date;
import java.util.Iterator;

/**
 * Wrap a MimeMessage with routing information (from SMTP) such
 * as SMTP specified recipients, sender, and ip address and hostname
 * of sending server.  It also contains its state which represents
 * which processor in the mailet container it is currently running.
 * Special processor names are "root" and "error".
 *
 * @version CVS $Revision: 494012 $ $Date: 2007-01-08 11:23:58 +0100 (Mo, 08 Jan 2007) $
 */
public interface Mail extends Serializable, Cloneable {
    String GHOST = "ghost";
    String DEFAULT = "root";
    String ERROR = "error";
    String TRANSPORT = "transport";
    /**
     * Returns the message name of this message
     * 
     * @return the message name
     * @since Mailet API v2.3
     */
    String getName();
    /**
     * Set the message name of this message
     * 
     * @param newName new name
     * @since Mailet API v2.3
     */
    void setName(String newName);
    /**
     * Returns the MimeMessage stored in this message
     *
     * @return the MimeMessage that this Mail object wraps
     * @throws MessagingException - an error occured while loading this object
     */
    MimeMessage getMessage() throws MessagingException;
    /**
     * Returns a Collection of MailAddress objects that are recipients of this message
     *
     * @return a Collection of MailAddress objects that are recipients of this message
     */
    Collection getRecipients();
    /**
     * Method setRecipients.
     * @param recipients a Collection of MailAddress Objects representing the recipients of this message
     * @since Mailet API v3.0-unstable
     */
    void setRecipients(Collection recipients);
    /**
     * The sender of the message, as specified by the MAIL FROM header, or internally defined
     *
     * @return a MailAddress of the sender of this message
     */
    MailAddress getSender();
    /**
     * The current state of the message, such as GHOST, ERROR, or DEFAULT
     *
     * @return the state of this message
     */
    String getState();
    /**
     * The remote hostname of the server that connected to send this message
     *
     * @return a String of the hostname of the server that connected to send this message
     */
    String getRemoteHost();
    /**
     * The remote ip address of the server that connected to send this message
     *
     * @return a String of the ip address of the server that connected to send this message
     */
    String getRemoteAddr();
    /**
     * The error message, if any, associated with this message.  Not sure why this is needed.
     *
     * @return a String of a descriptive error message
     */
    String getErrorMessage();
    /**
     * Sets the error message associated with this message.  Not sure why this is needed.
     *
     * @param msg - a descriptive error message
     */
    void setErrorMessage(String msg);
    /**
     * Sets the MimeMessage associated with this message via the object.
     *
     * @param message - the new MimeMessage that this Mail object will wrap
     */
    void setMessage(MimeMessage message);
    /**
     * Sets the state of this message.
     *
     * @param state - the new state of this message
     */
    void setState(String state);
    /**
     * Returns the Mail session attribute with the given name, or null
     * if there is no attribute by that name.
     * An attribute allows a mailet to give this Mail instance additional information
     * not already provided by this interface.<p>
     * A list of currently set attributes can be retrieved using getAttributeNames.
     * <p>
     * The attribute is returned as a java.lang.Object or some subclass. Attribute
     * names should follow the same convention as package names. The Mailet API
     * specification reserves names matching <I>org.apache.james.*</I>
     * and <I>org.apache.mailet.*</I>.
     *
     * @param name - a String specifying the name of the attribute
     * @return an Object containing the value of the attribute, or null if no attribute
     *      exists matching the given name
     * @since Mailet API v2.1
     */
    Serializable getAttribute(String name);
    /**
     * Returns an Iterator containing the attribute names currently available within
     * this Mail instance.  Use the getAttribute(java.lang.String) method with an
     * attribute name to get the value of an attribute.
     *
     * @return an Iterator of attribute names
     * @since Mailet API v2.1
     */
    Iterator getAttributeNames();
    /**
     * @return true if this Mail instance has any attributes set.
     * @since Mailet API v2.1
     **/
    boolean hasAttributes();
    /**
     * Removes the attribute with the given name from this Mail instance. After
     * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
     * the attribute's value will return null.
     *
     * @param name - a String specifying the name of the attribute to be removed
     * @return previous attribute value associated with specified name, or null
     * if there was no mapping for name (null can also mean that null
     * was bound to the name)
     * @since Mailet API v2.1
     */
    Serializable removeAttribute(String name);
    /**
     * Removes all the attributes associated with this Mail instance.  
     * @since Mailet API v2.1
     **/
    void removeAllAttributes();
    /**
     * Binds an object to a given attribute name in this Mail instance. If the name
     * specified is already used for an attribute, this method will remove the old
     * attribute and bind the name to the new attribute.
     * As instances of Mail is Serializable, it is necessary that the attributes being
     * Serializable as well
     * <p>
     * Attribute names should follow the same convention as package names.
     * The Mailet API specification reserves names matching <I>org.apache.james.*</I>
     * and <I>org.apache.mailet.*</I>.
     *
     * @param name - a String specifying the name of the attribute
     * @param object - a Serializable Object representing the attribute to be bound
     * @return the object previously bound to the name, null if the name was
     * not bound (null can also mean that null was bound to the name)
     * @since Mailet API v2.1
     */
    Serializable setAttribute(String name, Serializable object);
    /**
     * @return message size
     * @since Mailet API v2.3
     */
    long getMessageSize() throws MessagingException;
    /**
     * @return the last update date
     * @since Mailet API v2.3
     */
    Date getLastUpdated();
    /**
     * @param lastUpdated the new last updated date
     * @since Mailet API v2.3
     */
    void setLastUpdated(Date lastUpdated);
}