Package javax.mail

Class Folder

  • Direct Known Subclasses:
    IMAPFolder, MaildirFolder, MboxFolder, NNTPFolder, NNTPRootFolder, POP3Folder

    public abstract class Folder
    extends java.lang.Object
    A folder is a hierarchical messaging container in a store. Folders may contain Messages, other Folders or both, depending on the implementation.

    Folder names are implementation dependent; the hierarchy components in a folder's full name are separated by the folder's ancestors' hierarchy delimiter characters.

    The special (case-insensitive) folder name INBOX is reserved to mean the primary folder for the authenticated user in the store. Not all stores support INBOX folders, and not all users will have an INBOX folder.

    Unless documented otherwise, a folder must be opened in order to invoke a method on it.

    Version:
    1.4
    Author:
    Chris Burdess
    • Field Detail

      • HOLDS_MESSAGES

        public static final int HOLDS_MESSAGES
        This folder can contain messages.
        See Also:
        Constant Field Values
      • HOLDS_FOLDERS

        public static final int HOLDS_FOLDERS
        This folder can contain other folders.
        See Also:
        Constant Field Values
      • READ_WRITE

        public static final int READ_WRITE
        This folder can be modified.
        See Also:
        Constant Field Values
      • store

        protected Store store
        The parent store.
      • mode

        protected int mode
        The folder mode: Folder.READ_ONLY, Folder.READ_WRITE, or -1 if not known.
    • Constructor Detail

      • Folder

        protected Folder​(Store store)
        Constructor.
        Parameters:
        store - the parent store
    • Method Detail

      • getName

        public abstract java.lang.String getName()
        Returns the name of this folder.

        This method can be invoked on a closed folder.

      • getFullName

        public abstract java.lang.String getFullName()
        Returns the full name of this folder. If the folder resides under the root hierarchy of its store, the returned name is relative to the root. Otherwise an absolute name, starting with the hierarchy delimiter, is returned.

        This method can be invoked on a closed folder.

      • getURLName

        public URLName getURLName()
                           throws MessagingException
        Return a URLName that can be used as a handle to access this folder. This will not include the password used to authenticate to the store.

        This method can be invoked on a closed folder.

        Throws:
        MessagingException
      • getStore

        public Store getStore()
        Returns the parent store. This method can be invoked on a closed folder.
      • getParent

        public abstract Folder getParent()
                                  throws MessagingException
        Returns the parent folder of this folder, or null if this folder is the root of a folder hierarchy.

        This method can be invoked on a closed folder.

        Throws:
        MessagingException
      • exists

        public abstract boolean exists()
                                throws MessagingException
        Indicates whether this folder exists in the Store.

        This method can be invoked on a closed folder.

        Throws:
        MessagingException
      • list

        public abstract Folder[] list​(java.lang.String pattern)
                               throws MessagingException
        Returns a list of subfolders matching the specified pattern. Patterns may contain the wildcard characters "%", which matches any character except hierarchy delimiters, and "*", which matches any character.

        This method can be invoked on a closed folder.

        Parameters:
        pattern - the match pattern
        Throws:
        MessagingException
      • listSubscribed

        public Folder[] listSubscribed​(java.lang.String pattern)
                                throws MessagingException
        Returns a list of subscribed subfolders matching the specified pattern. If the folder does not support subscription, returns the same as the list method. The pattern can contain wildcards.

        This method can be invoked on a closed folder.

        Parameters:
        pattern - the match pattern
        Throws:
        MessagingException
      • getSeparator

        public abstract char getSeparator()
                                   throws MessagingException
        Return the hierarchy delimiter character for this folder. This separates the full name of this folder from the names of subfolders.

        This method can be invoked on a closed folder.

        Throws:
        MessagingException
      • getType

        public abstract int getType()
                             throws MessagingException
        Returns the type of this Folder, i.e. 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.

        Throws:
        MessagingException
      • create

        public abstract boolean create​(int type)
                                throws MessagingException
        Create this folder in the store. When this folder is created, any folders in its path that do not exist are also created.

        If the creation is successful, a CREATED FolderEvent is delivered to any FolderListeners registered on this Folder and this Store.

        Parameters:
        type - the desired type of the folder
        Throws:
        MessagingException
      • isSubscribed

        public boolean isSubscribed()
        Indicates whether this folder is subscribed.

        This method can be invoked on a closed folder.

      • setSubscribed

        public void setSubscribed​(boolean flag)
                           throws MessagingException
        Subscribe to or unsubscribe from this folder. Not all Stores support subscription.

        This method can be invoked on a closed folder.

        Throws:
        MessagingException
      • hasNewMessages

        public abstract boolean hasNewMessages()
                                        throws MessagingException
        Indicates whether this folder has new messages.

        This method can be invoked on a closed folder that can contain messages.

        Throws:
        MessagingException
      • getFolder

        public abstract Folder getFolder​(java.lang.String name)
                                  throws MessagingException
        Return a folder corresponding to the given name. Note that the folder does not have to exist in the store.

        In some stores, name can be an absolute path if it starts with the hierarchy delimiter. Otherwise, it is interpreted relative to this folder.

        This method can be invoked on a closed folder.

        Parameters:
        name - the name of the folder
        Throws:
        MessagingException
      • delete

        public abstract boolean delete​(boolean recurse)
                                throws MessagingException
        Deletes this folder. This method can only be invoked on a closed folder.
        Parameters:
        recurse - delete any subfolders
        Returns:
        true if the folder is deleted successfully, false otherwise
        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is not closed
        MessagingException
      • renameTo

        public abstract boolean renameTo​(Folder folder)
                                  throws MessagingException
        Renames this folder. This method can only be invoked on a closed folder.
        Parameters:
        folder - a folder representing the new name for this folder
        Returns:
        true if the folder is renamed successfully, false otherwise
        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is not closed
        MessagingException
      • open

        public abstract void open​(int mode)
                           throws MessagingException
        Opens this folder. This method can only be invoked on a closed folder that can contain messages.
        Parameters:
        mode - open the Folder READ_ONLY or READ_WRITE
        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is not closed
        MessagingException
      • close

        public abstract void close​(boolean expunge)
                            throws MessagingException
        Closes this folder. This method can only be invoked on an open folder.
        Parameters:
        expunge - if true, expunge all deleted messages
        Throws:
        MessagingException
      • isOpen

        public abstract boolean isOpen()
        Indicates whether this folder is open.
      • getMode

        public int getMode()
        Return the mode this folder is open in. Returns Folder.READ_ONLY, Folder.READ_WRITE, or -1 if the open mode is not known.
        Throws:
        java.lang.IllegalStateException - if this folder is not open
      • getPermanentFlags

        public abstract Flags getPermanentFlags()
        Returns the permanent flags supported by this folder.
      • getMessageCount

        public abstract int getMessageCount()
                                     throws MessagingException
        Returns the number of messages in this folder.

        This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

        Throws:
        MessagingException
      • getNewMessageCount

        public int getNewMessageCount()
                               throws MessagingException
        Returns the number of new messages in this folder.

        This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

        Throws:
        MessagingException
      • getUnreadMessageCount

        public int getUnreadMessageCount()
                                  throws MessagingException
        Returns the number of unread messages in this folder.

        This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

        Throws:
        MessagingException
      • getDeletedMessageCount

        public int getDeletedMessageCount()
                                   throws MessagingException
        Returns the number of deleted messages in this folder.

        This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

        Throws:
        FolderNotFoundException - if this folder does not exist
        MessagingException
        Since:
        JavaMail 1.3
      • getMessage

        public abstract Message getMessage​(int msgnum)
                                    throws MessagingException
        Returns the message with the given number. The message number is the relative position of a message in its folder, starting at 1.

        Note that message numbers can change within a session if the folder is expunged, therefore the use of message numbers as references to messages is inadvisable.

        Parameters:
        msgnum - the message number
        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is closed
        java.lang.IndexOutOfBoundsException - if the message number is out of range
        MessagingException
      • getMessages

        public Message[] getMessages​(int start,
                                     int end)
                              throws MessagingException
        Returns the messages in the given range (inclusive).
        Parameters:
        start - the number of the first message
        end - the number of the last message
        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is closed
        java.lang.IndexOutOfBoundsException - if the start or end message numbers are out of range.
        MessagingException
      • getMessages

        public Message[] getMessages​(int[] msgnums)
                              throws MessagingException
        Returns the messages for the specified message numbers.
        Parameters:
        msgnums - the array of message numbers
        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is closed
        java.lang.IndexOutOfBoundsException - if any message number in the given array is out of range
        MessagingException
      • appendMessages

        public abstract void appendMessages​(Message[] msgs)
                                     throws MessagingException
        Appends the specified messages to this folder.

        This method can be invoked on a closed folder.

        Parameters:
        msgs - array of messages to be appended
        Throws:
        FolderNotFoundException - if this folder does not exist
        MessagingException - if the append operation failed
      • fetch

        public void fetch​(Message[] msgs,
                          FetchProfile fp)
                   throws MessagingException
        Fetches the items specified in the given fetch profile for the specified messages.
        Parameters:
        msgs - the messages to fetch the items for
        fp - the fetch profile
        Throws:
        MessagingException
      • setFlags

        public void setFlags​(Message[] msgs,
                             Flags flag,
                             boolean value)
                      throws MessagingException
        Sets the specified flags on each specified message.
        Parameters:
        msgnums - the messages
        flag - the flags to be set
        value - set the flags to this value
        Throws:
        java.lang.IllegalStateException - if this folder is closed or READ_ONLY
        MessagingException
      • setFlags

        public void setFlags​(int start,
                             int end,
                             Flags flag,
                             boolean value)
                      throws MessagingException
        Set the specified flags on the given range of messages (inclusive).
        Parameters:
        start - the number of the first message
        end - the number of the last message
        flag - the flags to be set
        value - set the flags to this value
        Throws:
        java.lang.IllegalStateException - if this folder is closed or READ_ONLY
        java.lang.IndexOutOfBoundsException - if the start or end message numbers are out of range
        MessagingException
      • setFlags

        public void setFlags​(int[] msgnums,
                             Flags flag,
                             boolean value)
                      throws MessagingException
        Sets the specified flags on each of the specified messages.
        Parameters:
        msgnums - the message numbers
        flag - the flags to be set
        value - set the flags to this value
        Throws:
        java.lang.IllegalStateException - if this folder is closed or READ_ONLY
        java.lang.IndexOutOfBoundsException - if any message number in the given array is out of range
        MessagingException
      • copyMessages

        public void copyMessages​(Message[] msgs,
                                 Folder folder)
                          throws MessagingException
        Copies the specified messages into another folder.

        The destination folder does not have to be open.

        Parameters:
        msgs - the messages
        folder - the folder to copy the messages to
        Throws:
        MessagingException
      • expunge

        public abstract Message[] expunge()
                                   throws MessagingException
        Expunges (permanently removing) all the messages marked DELETED. Returns an array containing the expunged messages.

        Expunge causes the renumbering of any messages with numbers higher than the message number of the lowest-numbered expunged message.

        After a message has been expunged, only the isExpunged and getMessageNumber methods are still valid on the corresponding Message object; other methods may throw MessageRemovedException.

        Throws:
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is closed
        MessagingException
      • search

        public Message[] search​(SearchTerm term)
                         throws MessagingException
        Searches this folder for messages matching the specified search term. Returns the matching messages.
        Parameters:
        term - the search term
        Throws:
        SearchException - if there was a problem with the search
        FolderNotFoundException - if this folder does not exist
        java.lang.IllegalStateException - if this folder is closed
        MessagingException
      • search

        public Message[] search​(SearchTerm term,
                                Message[] msgs)
                         throws MessagingException
        Searches the given messages for those matching the specified search term. Returns the matching messages.
        Parameters:
        term - the search term
        msgs - the messages to be searched
        Throws:
        SearchException - if there was a problem with the search
        java.lang.IllegalStateException - if this folder is closed
        MessagingException
      • addConnectionListener

        public void addConnectionListener​(ConnectionListener l)
        Add a listener for connection events on this folder.
      • removeConnectionListener

        public void removeConnectionListener​(ConnectionListener l)
        Remove a connection event listener.
      • notifyConnectionListeners

        protected void notifyConnectionListeners​(int type)
        Notify all connection listeners.
      • addFolderListener

        public void addFolderListener​(FolderListener l)
        Add a listener for folder events on this folder.
      • removeFolderListener

        public void removeFolderListener​(FolderListener l)
        Remove a folder event listener.
      • notifyFolderListeners

        protected void notifyFolderListeners​(int type)
        Notify all folder listeners registered on this Folder and this folder's store.
      • notifyFolderRenamedListeners

        protected void notifyFolderRenamedListeners​(Folder folder)
        Notify all folder listeners registered on this folder and this folder's store about the renaming of this folder.
      • addMessageCountListener

        public void addMessageCountListener​(MessageCountListener l)
        Add a listener for message count events on this folder.
      • removeMessageCountListener

        public void removeMessageCountListener​(MessageCountListener l)
        Remove a message count event listener.
      • notifyMessageAddedListeners

        protected void notifyMessageAddedListeners​(Message[] msgs)
        Notify all message count listeners about the addition of messages into this folder.
      • notifyMessageRemovedListeners

        protected void notifyMessageRemovedListeners​(boolean removed,
                                                     Message[] msgs)
        Notify all message count listeners about the removal of messages from this folder.
      • addMessageChangedListener

        public void addMessageChangedListener​(MessageChangedListener l)
        Add a listener for message changed events on this folder.
      • removeMessageChangedListener

        public void removeMessageChangedListener​(MessageChangedListener l)
        Remove a message changed event listener.
      • notifyMessageChangedListeners

        protected void notifyMessageChangedListeners​(int type,
                                                     Message msg)
        Notify all message changed event listeners.
      • toString

        public java.lang.String toString()
        Returns the value of Folder.getFullName(), or, if that is null, returns the default toString().
        Overrides:
        toString in class java.lang.Object