message.java

java Email you can use it to send email to others

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License. You can obtain
 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
 * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
 * Sun designates this particular file as subject to the "Classpath" exception
 * as provided by Sun in the GPL Version 2 section of the License file that
 * accompanied this code.  If applicable, add the following below the License
 * Header, with the fields enclosed by brackets [] replaced by your own
 * identifying information: "Portions Copyrighted [year]
 * [name of copyright owner]"
 *
 * Contributor(s):
 *
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

/*
 * @(#)Message.java	1.39 07/05/04
 */

package javax.mail;

import java.util.Vector;
import java.util.Date;
import java.util.Properties;
import java.io.*;
import javax.mail.search.SearchTerm;

/**
 * This class models an email message. This is an abstract class.  
 * Subclasses provide actual implementations. <p>
 *
 * Message implements the Part interface. Message contains a set of
 * attributes and a "content". Messages within a folder also have a 
 * set of flags that describe its state within the folder.<p>
 *
 * Message defines some new attributes in addition to those defined
 * in the <code>Part</code> interface. These attributes specify meta-data
 * for the message - i.e., addressing  and descriptive information about 
 * the message. <p>
 *
 * Message objects are obtained either from a Folder or by constructing
 * a new Message object of the appropriate subclass. Messages that have
 * been received are normally retrieved from a folder named "INBOX". <p>
 *
 * A Message object obtained from a folder is just a lightweight
 * reference to the actual message. The Message is 'lazily' filled 
 * up (on demand) when each item is requested from the message. Note
 * that certain folder implementations may return Message objects that
 * are pre-filled with certain user-specified items.
 
 * To send a message, an appropriate subclass of Message (e.g., 
 * MimeMessage) is instantiated, the attributes and content are 
 * filled in, and the message is sent using the <code>Transport.send</code> 
 * method. <p>
 *
 * @author John Mani
 * @author Bill Shannon
 * @author Max Spivak
 * @see	   javax.mail.Part
 */

public abstract class Message implements Part {

    /**
     * The number of this message within its folder, or zero if
     * the message was not retrieved from a folder.
     */
    protected int msgnum	= 0;

    /**
     * True if this message has been expunged.
     */
    protected boolean expunged 	= false;

    /**
     * The containing folder, if this message is obtained from a folder
     */
    protected Folder folder	= null;

    /**
     * The Session object for this Message
     */
    protected Session session	= null;

    /**
     * No-arg version of the constructor.
     */
    protected Message() { }

    /**
     * Constructor that takes a Folder and a message number. 
     * Used by Folder implementations.
     *
     * @param	folder	containing folder
     * @param	msgnum	this message's sequence number within this folder
     */
    protected Message(Folder folder, int msgnum) {
	this.folder = folder;
	this.msgnum = msgnum;
	session = folder.store.session;
    }

    /**
     * Constructor that takes a Session. Used for client created
     * Message objects.
     *
     * @param	session	A Session object
     */
    protected Message(Session session) {
	this.session = session;
    }

    /**
     * Returns the "From" attribute. The "From" attribute contains
     * the identity of the person(s) who wished this message to 
     * be sent. <p>
     * 
     * In certain implementations, this may be different
     * from the entity that actually sent the message. <p>
     *
     * This method returns <code>null</code> if this attribute
     * is not present in this message. Returns an empty array if
     * this attribute is present, but contains no addresses.
     *
     * @return          array of Address objects
     * @exception       MessagingException
     */
    public abstract Address[] getFrom() throws MessagingException;

    /**
     * Set the "From" attribute in this Message. The value of this
     * attribute is obtained from the property "mail.user". If this
     * property is absent, the system property "user.name" is used.
     *
     * @exception       MessagingException
     * @exception	IllegalWriteException if the underlying 
     *			implementation does not support modification 
     *			of existing values
     * @exception	IllegalStateException if this message is
     *			obtained from a READ_ONLY folder.
     */
    public abstract void setFrom() throws MessagingException;

    /**
     * Set the "From" attribute in this Message.
     *
     * @param address   the sender
     * @exception       MessagingException
     * @exception	IllegalWriteException if the underlying 
     *			implementation does not support modification 
     *			of existing values
     * @exception	IllegalStateException if this message is
     *			obtained from a READ_ONLY folder.
     */
    public abstract void setFrom(Address address) 
			throws MessagingException;

    /**
     * Add these addresses to the existing "From" attribute 
     *
     * @param addresses	the senders
     * @exception	IllegalWriteException if the underlying 
     *			implementation does not support modification 
     *			of existing values
     * @exception	IllegalStateException if this message is
     *			obtained from a READ_ONLY folder.
     * @exception       MessagingException
     */
    public abstract void addFrom(Address[] addresses) 
			throws MessagingException;

    /**
     * This inner class defines the types of recipients allowed by
     * the Message class. The currently defined types are TO,
     * CC and BCC.
     *
     * Note that this class only has a protected constructor, thereby
     * restricting new Recipient types to either this class or subclasses.
     * This effectively implements an enumeration of the allowed Recipient
     * types.
     *
     * The following code sample shows how to use this class to obtain
     * the "TO" recipients from a message.
     * <blockquote><pre>
     *
     * Message msg = folder.getMessages(1);
     * Address[] a = m.getRecipients(Message.RecipientType.TO);
     *
     * </pre></blockquote><p>
     *
     * @see javax.mail.Message#getRecipients
     * @see javax.mail.Message#setRecipients
     * @see javax.mail.Message#addRecipients
     */
    public static class RecipientType implements Serializable {
	/**
	 * The "To" (primary) recipients.
	 */
	public static final RecipientType TO = new RecipientType("To");
	/**
	 * The "Cc" (carbon copy) recipients.
	 */
	public static final RecipientType CC = new RecipientType("Cc");
	/**
	 * The "Bcc" (blind carbon copy) recipients.
	 */
	public static final RecipientType BCC = new RecipientType("Bcc");

	/**
	 * The type of recipient, usually the name of a corresponding
	 * Internet standard header.
	 *
	 * @serial
	 */
	protected String type;

	private static final long serialVersionUID = -7479791750606340008L;

	/**
	 * Constructor for use by subclasses.
	 */
	protected RecipientType(String type) {
	    this.type = type;
	}

	/**
	 * When deserializing a RecipientType, we need to make sure to
	 * return only one of the known static final instances defined
	 * in this class.  Subclasses must implement their own
	 * <code>readResolve</code> method that checks for their known
	 * instances before calling this super method.
	 */
	protected Object readResolve() throws ObjectStreamException {
	    if (type.equals("To"))
		return TO;
	    else if (type.equals("Cc"))
		return CC;
	    else if (type.equals("Bcc"))
		return BCC;
	    else
		throw new InvalidObjectException(
		    "Attempt to resolve unknown RecipientType: " + type);
	}

	public String toString() {
	    return type;
	}
    }

    /**
     * Get all the recipient addresses of the given type. <p>
     *
     * This method returns <code>null</code> if no recipients of
     * the given type are present in this message. It may return an 
     * empty array if the header is present, but contains no addresses.
     *
     * @param type      the recipient type
     * @return          array of Address objects
     * @exception       MessagingException
     * @see Message.RecipientType#TO
     * @see Message.RecipientType#CC
     * @see Message.RecipientType#BCC
     */
    public abstract Address[] getRecipients(RecipientType type)
                                throws MessagingException;

    /**
     * Get all the recipient addresses for the message.
     * The default implementation extracts the TO, CC, and BCC
     * recipients using the <code>getRecipients</code> method. <p>
     *
     * This method returns <code>null</code> if none of the recipient
     * headers are present in this message.  It may Return an empty array
     * if any recipient header is present, but contains no addresses.
     *
     * @return          array of Address objects
     * @exception       MessagingException
     * @see Message.RecipientType#TO
     * @see Message.RecipientType#CC
     * @see Message.RecipientType#BCC
     * @see #getRecipients
     */
    public Address[] getAllRecipients() throws MessagingException {
	Address[] to = getRecipients(RecipientType.TO);
	Address[] cc = getRecipients(RecipientType.CC);
	Address[] bcc = getRecipients(RecipientType.BCC);

	if (cc == null && bcc == null)
	    return to;		// a common case

	int numRecip =
	    (to != null ? to.length : 0) +
	    (cc != null ? cc.length : 0) +
	    (bcc != null ? bcc.length : 0);
	Address[] addresses = new Address[numRecip];
	int pos = 0;
	if (to != null) {
	    System.arraycopy(to, 0, addresses, pos, to.length);
	    pos += to.length;
	}
	if (cc != null) {
	    System.arraycopy(cc, 0, addresses, pos, cc.length);
	    pos += cc.length;
	}
	if (bcc != null) {
	    System.arraycopy(bcc, 0, addresses, pos, bcc.length);
	    pos += bcc.length;
	}
	return addresses;
    }

    /**
     * Set the recipient addresses.  All addresses of the specified
     * type are replaced by the addresses parameter.
     *
     * @param type      the recipient type
     * @param addresses the addresses
     * @exception       MessagingException
     * @exception	IllegalWriteException if the underlying 
     *			implementation does not support modification 
     *			of existing values
     * @exception	IllegalStateException if this message is
     *			obtained from a READ_ONLY folder.
     */
    public abstract void setRecipients(RecipientType type, Address[] addresses)
                                throws MessagingException;

    /**
     * Set the recipient address.  All addresses of the specified
     * type are replaced by the address parameter. <p>
     *
     * The default implementation uses the <code>setRecipients</code> method.
     *