folder.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.
 */

/*
 * @(#)Folder.java	1.58 07/05/04
 */

package javax.mail;

import java.io.*;
import java.lang.*;
import java.util.Vector;
import java.util.StringTokenizer;
import javax.mail.search.SearchTerm;
import javax.mail.event.*;

/**
 * Folder is an abstract class that represents a folder for mail
 * messages. Subclasses implement protocol specific Folders.<p>
 *
 * Folders can contain Messages, other Folders or both, thus providing
 * a tree-like hierarchy rooted at the Store's default folder. (Note 
 * that some Folder implementations may not allow both Messages and 
 * other Folders in the same Folder).<p>
 *
 * The interpretation of folder names is implementation dependent.
 * The different levels of hierarchy in a folder's full name
 * are separated from each other by the hierarchy delimiter 
 * character.<p>
 *
 * The case-insensitive full folder name (that is, the full name
 * relative to the default folder for a Store) <strong>INBOX</strong>
 * is reserved to mean the "primary folder for this user on this
 * server".  Not all Stores will provide an INBOX folder, and not
 * all users will have an INBOX folder at all times.  The name
 * <strong>INBOX</strong> is reserved to refer to this folder,
 * when it exists, in Stores that provide it. <p>
 *
 * A Folder object obtained from a Store need not actually exist
 * in the backend store. The <code>exists</code> method tests whether
 * the folder exists or not. The <code>create</code> method
 * creates a Folder. <p>
 *
 * A Folder is initially in the closed state. Certain methods are valid
 * in this state; the documentation for those methods note this.  A
 * Folder is opened by calling its 'open' method. All Folder methods,
 * except <code>open</code>, <code>delete</code> and 
 * <code>renameTo</code>, are valid in this state. <p>
 *
 * The only way to get a Folder is by invoking the 
 * <code>getFolder</code> method on Store, Folder, or Session, or by invoking 
 * the <code>list</code> or <code>listSubscribed</code> methods 
 * on Folder. Folder objects returned by the above methods are not 
 * cached by the Store. Thus, invoking the <code>getFolder</code> method
 * with the same folder name multiple times will return distinct Folder 
 * objects.  Likewise for the <code>list</code> and <code>listSubscribed</code>
 * methods. <p>
 *
 * The Message objects within the Folder are cached by the Folder.
 * Thus, invoking <code>getMessage(msgno)</code> on the same message number
 * multiple times will return the same Message object, until an 
 * expunge is done on this Folder. <p>
 *
 * Note that a Message's message number can change within a
 * session if the containing Folder is expunged using the expunge
 * method.  Clients that use message numbers as references to messages
 * should be aware of this and should be prepared to deal with 
 * situation (probably by flushing out existing message number references
 * and reloading them). Because of this complexity, it is better for
 * clients to use Message objects as references to messages, rather than
 * message numbers. Expunged Message objects still have to be
 * pruned, but other Message objects in that folder are not affected by the 
 * expunge.
 *
 * @author John Mani
 * @author Bill Shannon
 */

public abstract class Folder {

    /**
     * The parent store.
     */
    protected Store store;

    /**
     * The open mode of this folder.  The open mode is
     * <code>Folder.READ_ONLY</code>, <code>Folder.READ_WRITE</code>,
     * or -1 if not known.
     * @since	JavaMail 1.1
     */
    protected int mode = -1;

    /**
     * Constructor that takes a Store object.
     *
     * @param store the Store that holds this folder
     */
    protected Folder(Store store) {
	this.store = store;
    }

    /**
     * Returns the name of this Folder. <p>
     *
     * This method can be invoked on a closed Folder.
     *
     * @return		name of the Folder
     */
    public abstract String getName();

    /**
     * Returns the full name of this Folder. If the folder resides under
     * the root hierarchy of this Store, the returned name is relative
     * to the root. Otherwise an absolute name, starting with the 
     * hierarchy delimiter, is returned. <p>
     *
     * This method can be invoked on a closed Folder.
     *
     * @return		full name of the Folder
     */
    public abstract String getFullName();

    /**
     * Return a URLName representing this folder.  The returned URLName
     * does <em>not</em> include the password used to access the store.
     *
     * @return	the URLName representing this folder
     * @see	URLName
     * @since	JavaMail 1.1
     */
    public URLName getURLName() throws MessagingException {
	URLName storeURL = getStore().getURLName();
	String fullname = getFullName();
	StringBuffer encodedName = new StringBuffer();
	char separator = getSeparator();

	if (fullname != null) {
	    /*
	    // We need to encode each of the folder's names.
	    StringTokenizer tok = new StringTokenizer(
		fullname, new Character(separator).toString(), true);

	    while (tok.hasMoreTokens()) {
		String s = tok.nextToken();
		if (s.charAt(0) == separator)
		    encodedName.append(separator);
		else
		    // XXX - should encode, but since there's no decoder...
		    //encodedName.append(java.net.URLEncoder.encode(s));
		    encodedName.append(s);
	    }
	    */
	    // append the whole thing, until we can encode
	    encodedName.append(fullname);
	}

	/*
	 * Sure would be convenient if URLName had a
	 * constructor that took a base URLName.
	 */
	return new URLName(storeURL.getProtocol(), storeURL.getHost(),
			    storeURL.getPort(), encodedName.toString(),
			    storeURL.getUsername(),
			    null /* no password */);
    }

    /**
     * Returns the Store that owns this Folder object.
     * This method can be invoked on a closed Folder.
     * @return 		the Store
     */
    public Store getStore() {
	return store;
    }

    /**
     * Returns the parent folder of this folder.
     * This method can be invoked on a closed Folder. If this folder
     * is the top of a folder hierarchy, this method returns null. <p>
     *
     * Note that since Folder objects are not cached, invoking this method
     * returns a new distinct Folder object.
     *
     * @return		Parent folder
     */
    public abstract Folder getParent() throws MessagingException;

    /**
     * Tests if this folder physically exists on the Store.
     * This method can be invoked on a closed Folder.
     *
     * @return true if the folder exists, otherwise false
     * @see    #create
     * @exception	MessagingException typically if the connection 
     *			to the server is lost.
     */
    public abstract boolean exists() throws MessagingException;

    /**
     * Returns a list of Folders belonging to this Folder's namespace
     * that match the specified pattern. Patterns may contain the wildcard
     * characters <code>"%"</code>, which matches any character except hierarchy
     * delimiters, and <code>"*"</code>, which matches any character. <p>
     *
     * As an example, given the folder hierarchy: <pre>
     *    Personal/
     *       Finance/
     *          Stocks
     *          Bonus
     *          StockOptions
     *       Jokes
     * </pre>
     * <code>list("*")</code> on "Personal" will return the whole 
     * hierarchy. <br>
     * <code>list("%")</code> on "Personal" will return "Finance" and 
     * "Jokes". <br>
     * <code>list("Jokes")</code> on "Personal" will return "Jokes".<br>
     * <code>list("Stock*")</code> on "Finance" will return "Stocks"
     * and "StockOptions". <p>
     *
     * Folder objects are not cached by the Store, so invoking this
     * method on the same pattern multiple times will return that many
     * distinct Folder objects. <p>
     *
     * This method can be invoked on a closed Folder.
     *
     * @param pattern	the match pattern
     * @return		array of matching Folder objects. An empty
     *			array is returned if no matching Folders exist.
     * @see 		#listSubscribed
     * @exception 	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception 	MessagingException
     */
    public abstract Folder[] list(String pattern) throws MessagingException;

    /**
     * Returns a list of subscribed Folders belonging to this Folder's
     * namespace that match the specified pattern. If the folder does
     * not support subscription, this method should resolve to
     * <code>list</code>.
     * (The default implementation provided here, does just this).
     * The pattern can contain wildcards as for <code>list</code>. <p>
     *
     * Note that, at a given level of the folder hierarchy, a particular
     * folder may not be subscribed, but folders underneath that folder
     * in the folder hierarchy may be subscribed.  In order to allow
     * walking the folder hierarchy, such unsubscribed folders may be
     * returned, indicating that a folder lower in the hierarchy is
     * subscribed.  The <code>isSubscribed</code> method on a folder will
     * tell whether any particular folder is actually subscribed. <p>
     *
     * Folder objects are not cached by the Store, so invoking this
     * method on the same pattern multiple times will return that many
     * distinct Folder objects. <p>
     *
     * This method can be invoked on a closed Folder.
     *
     * @param pattern	the match pattern
     * @return		array of matching subscribed Folder objects. An
     *			empty array is returned if no matching
     *			subscribed folders exist.
     * @see 		#list
     * @exception 	FolderNotFoundException if this folder does
     *			not exist.
     * @exception 	MessagingException
     */
    public Folder[] listSubscribed(String pattern) throws MessagingException {
	return list(pattern);
    }

    /**
     * Convenience method that returns the list of folders under this
     * Folder. This method just calls the <code>list(String pattern)</code>
     * method with <code>"%"</code> as the match pattern. This method can
     * be invoked on a closed Folder.
     *
     * @return		array of Folder objects under this Folder. An
     *			empty array is returned if no subfolders exist.
     * @see		#list
     * @exception 	FolderNotFoundException if this folder does
     *			not exist.
     * @exception 	MessagingException
     */

    public Folder[] list() throws MessagingException {
	return list("%");
    }

    /**
     * Convenience method that returns the list of subscribed folders 
     * under this Folder. This method just calls the
     * <code>listSubscribed(String pattern)</code> method with <code>"%"</code>
     * as the match pattern. This method can be invoked on a closed Folder.
     *
     * @return		array of subscribed Folder objects under this 
     *			Folder. An empty array is returned if no subscribed 
     *			subfolders exist.