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