folder.java

java Email you can use it to send email to others

     * @see		#listSubscribed
     * @exception 	FolderNotFoundException if this folder does
     *			not exist.
     * @exception 	MessagingException
     */
    public Folder[] listSubscribed() throws MessagingException {
	return listSubscribed("%");
    }

    /**
     * Return the delimiter character that separates this Folder's pathname
     * from the names of immediate subfolders. This method can be invoked 
     * on a closed Folder.
     *
     * @exception 	FolderNotFoundException if the implementation
     *			requires the folder to exist, but it does not
     * @return          Hierarchy separator character
     */
    public abstract char getSeparator() throws MessagingException;

    /**
     * This folder can contain messages
     */
    public final static int HOLDS_MESSAGES = 0x01;

    /**
     * This folder can contain other folders
     */
    public final static int HOLDS_FOLDERS  = 0x02;

    /**
     * Returns the type of this Folder, that is, whether this folder can hold
     * messages or subfolders or both. The returned value is an integer
     * bitfield with the appropriate bits set. This method can be invoked
     * on a closed folder.
     * 
     * @return 		integer with appropriate bits set
     * @exception 	FolderNotFoundException if this folder does 
     *			not exist.
     * @see 		#HOLDS_FOLDERS 
     * @see		#HOLDS_MESSAGES
     */
    public abstract int getType() throws MessagingException; 

    /**
     * Create this folder on the Store. When this folder is created, any
     * folders in its path that do not exist are also created. <p>
     *
     * If the creation is successful, a CREATED FolderEvent is delivered
     * to any FolderListeners registered on this Folder and this Store.
     *
     * @param  type	The type of this folder. 
     *
     * @return		true if the creation succeeds, else false.
     * @exception 	MessagingException  
     * @see 		#HOLDS_FOLDERS
     * @see		#HOLDS_MESSAGES
     * @see		javax.mail.event.FolderEvent
     */
    public abstract boolean create(int type) throws MessagingException;

    /**
     * Returns true if this Folder is subscribed. <p>
     *
     * This method can be invoked on a closed Folder. <p>
     *
     * The default implementation provided here just returns true.
     *
     * @return		true if this Folder is subscribed
     */
    public boolean isSubscribed() {
	return true;
    }

    /**
     * Subscribe or unsubscribe this Folder. Not all Stores support
     * subscription. <p>
     *
     * This method can be invoked on a closed Folder. <p>
     *
     * The implementation provided here just throws the
     * MethodNotSupportedException.
     *
     * @param subscribe	true to subscribe, false to unsubscribe
     * @exception 	FolderNotFoundException if this folder does
     *			not exist.
     * @exception 	MethodNotSupportedException if this store
     *			does not support subscription
     * @exception 	MessagingException
     */
    public void setSubscribed(boolean subscribe) 
			throws MessagingException {
	throw new MethodNotSupportedException();
    }

    /**
     * Returns true if this Folder has new messages since the last time
     * this indication was reset.  When this indication is set or reset
     * depends on the Folder implementation (and in the case of IMAP,
     * depends on the server).  This method can be used to implement
     * a lightweight "check for new mail" operation on a Folder without
     * opening it.  (For example, a thread that monitors a mailbox and
     * flags when it has new mail.)  This method should indicate whether
     * any messages in the Folder have the <code>RECENT</code> flag set. <p>
     *
     * Note that this is not an incremental check for new mail, i.e.,
     * it cannot be used to determine whether any new messages have
     * arrived since the last time this method was invoked. To
     * implement incremental checks, the Folder needs to be opened. <p>
     *
     * This method can be invoked on a closed Folder that can contain
     * Messages.
     *
     * @return		true if the Store has new Messages
     * @exception	FolderNotFoundException if this folder does
     *			not exist.
     * @exception 	MessagingException
     */
    public abstract boolean hasNewMessages() throws MessagingException;

    /**
     * Return the Folder object corresponding to the given name. Note that
     * this folder does not physically have to exist in the Store. The
     * <code>exists()</code> method on a Folder indicates whether it really
     * exists on the Store. <p>
     *
     * In some Stores, name can be an absolute path if it starts with the
     * hierarchy delimiter.  Otherwise, it is interpreted relative to
     * this Folder. <p>
     *
     * Folder objects are not cached by the Store, so invoking this
     * method on the same name multiple times will return that many
     * distinct Folder objects. <p>
     *
     * This method can be invoked on a closed Folder.
     *
     * @param name 	name of the Folder
     * @return		Folder object
     * @exception 	MessagingException
     */
    public abstract Folder getFolder(String name)
				throws MessagingException;

    /**
     * Delete this Folder. This method will succeed only on a closed
     * Folder. <p>
     *
     * The <code>recurse</code> flag controls whether the deletion affects
     * subfolders or not. If true, all subfolders are deleted, then this
     * folder itself is deleted. If false, the behaviour is dependent on
     * the folder type and is elaborated below: <p>
     *
     * <ul>
     * <li>
     * The folder can contain only messages: (type == HOLDS_MESSAGES).
     * <br>
     * All messages within the folder are removed. The folder 
     * itself is then removed. An appropriate FolderEvent is generated by 
     * the Store and this folder. <p>
     *
     * <li>
     * The folder can contain only subfolders: (type == HOLDS_FOLDERS).
     * <br>
     * If this folder is empty (does not contain any 
     * subfolders at all), it is removed. An appropriate FolderEvent is 
     * generated by the Store and this folder.<br>
     * If this folder contains any subfolders, the delete fails 
     * and returns false. <p>
     *
     * <li>
     * The folder can contain subfolders as well as messages: <br>
     * If the folder is empty (no messages or subfolders), it
     * is removed. If the folder contains no subfolders, but only messages,
     * then all messages are removed. The folder itself is then removed.
     * In both the above cases, an appropriate FolderEvent is
     * generated by the Store and this folder. <p>
     *
     * If the folder contains subfolders there are 3 possible
     * choices an implementation is free to do: <p>
     * 
     *  <ol>
     *   <li> The operation fails, irrespective of whether this folder
     * contains messages or not. Some implementations might elect to go
     * with this simple approach. The delete() method returns false.
     *
     *   <li> Any messages within the folder are removed. Subfolders
     * are not removed. The folder itself is not removed or affected
     * in any manner. The delete() method returns true. And the 
     * exists() method on this folder will return true indicating that
     * this folder still exists. <br>
     * An appropriate FolderEvent is generated by the Store and this folder.
     *
     *   <li> Any messages within the folder are removed. Subfolders are
     * not removed. The folder itself changes its type from 
     * HOLDS_FOLDERS | HOLDS_MESSAGES to HOLDS_FOLDERS. Thus new 
     * messages cannot be added to this folder, but new subfolders can
     * be created underneath. The delete() method returns true indicating
     * success. The exists() method on this folder will return true
     * indicating that this folder still exists. <br>
     * An appropriate FolderEvent is generated by the Store and this folder.
     * </ol>
     * </ul>
     *
     * @return		true if the Folder is deleted successfully
     * @exception	FolderNotFoundException if this folder does 
     *			not exist
     * @exception	IllegalStateException if this folder is not in 
     *			the closed state.
     * @exception       MessagingException
     * @see		javax.mail.event.FolderEvent
     */
    public abstract boolean delete(boolean recurse) 
				throws MessagingException;

    /**
     * Rename this Folder. This method will succeed only on a closed
     * Folder. <p>
     *
     * If the rename is successful, a RENAMED FolderEvent is delivered
     * to FolderListeners registered on this folder and its containing
     * Store.
     *
     * @param f		a folder representing the new name for this Folder
     * @return		true if the Folder is renamed successfully
     * @exception	FolderNotFoundException if this folder does 
     *			not exist
     * @exception	IllegalStateException if this folder is not in 
     *			the closed state.
     * @exception       MessagingException
     * @see		javax.mail.event.FolderEvent
     */
    public abstract boolean renameTo(Folder f) throws MessagingException;

    /**
     * The Folder is read only.  The state and contents of this
     * folder cannot be modified.
     */
    public static final int READ_ONLY 	= 1;

    /**
     * The state and contents of this folder can be modified.
     */
    public static final int READ_WRITE 	= 2;

    /**
     * Open this Folder. This method is valid only on Folders that
     * can contain Messages and that are closed. <p>
     *
     * If this folder is opened successfully, an OPENED ConnectionEvent
     * is delivered to any ConnectionListeners registered on this 
     * Folder. <p>
     *
     * The effect of opening multiple connections to the same folder
     * on a specifc Store is implementation dependent. Some implementations
     * allow multiple readers, but only one writer. Others allow
     * multiple writers as well as readers.
     *
     * @param mode	open the Folder READ_ONLY or READ_WRITE
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception	IllegalStateException if this folder is not in 
     *			the closed state.
     * @exception       MessagingException
     * @see 		#READ_ONLY
     * @see 		#READ_WRITE
     * @see 		#getType()
     * @see 		javax.mail.event.ConnectionEvent
     */
    public abstract void open(int mode) throws MessagingException;

    /**
     * Close this Folder. This method is valid only on open Folders. <p>
     *
     * A CLOSED ConnectionEvent is delivered to any ConnectionListeners
     * registered on this Folder. Note that the folder is closed even
     * if this method terminates abnormally by throwing a
     * MessagingException.
     *
     * @param expunge	expunges all deleted messages if this flag is true
     * @exception	IllegalStateException if this folder is not opened
     * @exception       MessagingException
     * @see 		javax.mail.event.ConnectionEvent
     */
    public abstract void close(boolean expunge) throws MessagingException;

    /**
     * Indicates whether this Folder is in the 'open' state.
     * @return  true if this Folder is in the 'open' state.
     */
    public abstract boolean isOpen();

    /**
     * Return the open mode of this folder.  Returns
     * <code>Folder.READ_ONLY</code>, <code>Folder.READ_WRITE</code>,
     * or -1 if the open mode is not known (usually only because an older
     * <code>Folder</code> provider has not been updated to use this new
     * method).
     *
     * @exception	IllegalStateException if this folder is not opened
     * @return	        the open mode of this folder
     * @since		JavaMail 1.1
     */
    public int getMode() {
	if (!isOpen())
	    throw new IllegalStateException("Folder not open");
	return mode;
    }
 
    /**
     * Get the permanent flags supported by this Folder. Returns a Flags
     * object that contains all the flags supported. <p>
     *
     * The special flag <code>Flags.USER </code> indicates that this Folder
     * supports arbitrary user-defined flags. <p>
     *
     * The supported permanent flags for a folder may not be available
     * until the folder is opened.
     * 
     * @return 		permanent flags, or null if not known
     */
    public abstract Flags getPermanentFlags();

    /**
     * Get total number of messages in this Folder. <p>
     *
     * This method can be invoked on a closed folder. However, note
     * that for some folder implementations, getting the total message
     * count can be an expensive operation involving actually opening 
     * the folder. In such cases, a provider can choose not to support 
     * this functionality in the closed state, in which case this method
     * must return -1. <p>
     *