Folder (GNU JavaMail API documentation)

java.lang.Object
- javax.mail.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.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`HOLDS_FOLDERS` This folder can contain other folders.
`static int`	`HOLDS_MESSAGES` This folder can contain messages.
`protected int`	`mode` The folder mode: Folder.READ_ONLY, Folder.READ_WRITE, or -1 if not known.
`static int`	`READ_ONLY` This folder is read only.
`static int`	`READ_WRITE` This folder can be modified.
`protected Store`	`store` The parent store.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Folder(Store store)
Constructor.

Constructors
Modifier	Constructor and Description
`protected`	`Folder(Store store)` Constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addConnectionListener(ConnectionListener l)` Add a listener for connection events on this folder.
`void`	`addFolderListener(FolderListener l)` Add a listener for folder events on this folder.
`void`	`addMessageChangedListener(MessageChangedListener l)` Add a listener for message changed events on this folder.
`void`	`addMessageCountListener(MessageCountListener l)` Add a listener for message count events on this folder.
`abstract void`	`appendMessages(Message[] msgs)` Appends the specified messages to this folder.
`abstract void`	`close(boolean expunge)` Closes this folder.
`void`	`copyMessages(Message[] msgs, Folder folder)` Copies the specified messages into another folder.
`abstract boolean`	`create(int type)` Create this folder in the store.
`abstract boolean`	`delete(boolean recurse)` Deletes this folder.
`abstract boolean`	`exists()` Indicates whether this folder exists in the Store.
`abstract Message[]`	`expunge()` Expunges (permanently removing) all the messages marked DELETED.
`void`	`fetch(Message[] msgs, FetchProfile fp)` Fetches the items specified in the given fetch profile for the specified messages.
`int`	`getDeletedMessageCount()` Returns the number of deleted messages in this folder.
`abstract Folder`	`getFolder(java.lang.String name)` Return a folder corresponding to the given name.
`abstract java.lang.String`	`getFullName()` Returns the full name of this folder.
`abstract Message`	`getMessage(int msgnum)` Returns the message with the given number.
`abstract int`	`getMessageCount()` Returns the number of messages in this folder.
`Message[]`	`getMessages()` Returns all messages in this folder.
`Message[]`	`getMessages(int[] msgnums)` Returns the messages for the specified message numbers.
`Message[]`	`getMessages(int start, int end)` Returns the messages in the given range (inclusive).
`int`	`getMode()` Return the mode this folder is open in.
`abstract java.lang.String`	`getName()` Returns the name of this folder.
`int`	`getNewMessageCount()` Returns the number of new messages in this folder.
`abstract Folder`	`getParent()` Returns the parent folder of this folder, or `null` if this folder is the root of a folder hierarchy.
`abstract Flags`	`getPermanentFlags()` Returns the permanent flags supported by this folder.
`abstract char`	`getSeparator()` Return the hierarchy delimiter character for this folder.
`Store`	`getStore()` Returns the parent store.
`abstract int`	`getType()` Returns the type of this Folder, i.e.
`int`	`getUnreadMessageCount()` Returns the number of unread messages in this folder.
`URLName`	`getURLName()` Return a URLName that can be used as a handle to access this folder.
`abstract boolean`	`hasNewMessages()` Indicates whether this folder has new messages.
`abstract boolean`	`isOpen()` Indicates whether this folder is open.
`boolean`	`isSubscribed()` Indicates whether this folder is subscribed.
`Folder[]`	`list()` Returns the list of subfolders of this folder.
`abstract Folder[]`	`list(java.lang.String pattern)` Returns a list of subfolders matching the specified pattern.
`Folder[]`	`listSubscribed()` Returns the list of subscribed subfolders of this folder.
`Folder[]`	`listSubscribed(java.lang.String pattern)` Returns a list of subscribed subfolders matching the specified pattern.
`protected void`	`notifyConnectionListeners(int type)` Notify all connection listeners.
`protected void`	`notifyFolderListeners(int type)` Notify all folder listeners registered on this Folder and this folder's store.
`protected void`	`notifyFolderRenamedListeners(Folder folder)` Notify all folder listeners registered on this folder and this folder's store about the renaming of this folder.
`protected void`	`notifyMessageAddedListeners(Message[] msgs)` Notify all message count listeners about the addition of messages into this folder.
`protected void`	`notifyMessageChangedListeners(int type, Message msg)` Notify all message changed event listeners.
`protected void`	`notifyMessageRemovedListeners(boolean removed, Message[] msgs)` Notify all message count listeners about the removal of messages from this folder.
`abstract void`	`open(int mode)` Opens this folder.
`void`	`removeConnectionListener(ConnectionListener l)` Remove a connection event listener.
`void`	`removeFolderListener(FolderListener l)` Remove a folder event listener.
`void`	`removeMessageChangedListener(MessageChangedListener l)` Remove a message changed event listener.
`void`	`removeMessageCountListener(MessageCountListener l)` Remove a message count event listener.
`abstract boolean`	`renameTo(Folder folder)` Renames this folder.
`Message[]`	`search(SearchTerm term)` Searches this folder for messages matching the specified search term.
`Message[]`	`search(SearchTerm term, Message[] msgs)` Searches the given messages for those matching the specified search term.
`void`	`setFlags(int[] msgnums, Flags flag, boolean value)` Sets the specified flags on each of the specified messages.
`void`	`setFlags(int start, int end, Flags flag, boolean value)` Set the specified flags on the given range of messages (inclusive).
`void`	`setFlags(Message[] msgs, Flags flag, boolean value)` Sets the specified flags on each specified message.
`void`	`setSubscribed(boolean flag)` Subscribe to or unsubscribe from this folder.
`java.lang.String`	`toString()` Returns the value of Folder.getFullName(), or, if that is null, returns the default toString().

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 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_ONLY
```
public static final int READ_ONLY
```
    This folder is read only.
    
    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
  - list
```
public Folder[] list()
              throws MessagingException
```
    Returns the list of subfolders of this folder.
    This method can be invoked on a closed folder.
    
    Throws:
    
    MessagingException
  - listSubscribed
```
public Folder[] listSubscribed()
                        throws MessagingException
```
    Returns the list of subscribed subfolders of this folder.
    This method can be invoked on a closed folder.
    
    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
  - getMessages
```
public Message[] getMessages()
                      throws MessagingException
```
    Returns all messages in this folder.
    
    Throws:
    
    FolderNotFoundException - if this folder does not exist
    
    java.lang.IllegalStateException - if this folder is closed
    
    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

Class Folder

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

HOLDS_MESSAGES

HOLDS_FOLDERS

READ_ONLY

READ_WRITE

store

mode

Constructor Detail

Folder

Method Detail

getName

getFullName

getURLName

getStore

getParent

exists

list

listSubscribed

list

listSubscribed

getSeparator

getType

create

isSubscribed

setSubscribed

hasNewMessages

getFolder

delete

renameTo

open

close

isOpen

getMode

getPermanentFlags

getMessageCount

getNewMessageCount

getUnreadMessageCount

getDeletedMessageCount

getMessage

getMessages

getMessages

getMessages

appendMessages

fetch

setFlags

setFlags

setFlags

copyMessages

expunge

search

search

addConnectionListener

removeConnectionListener

notifyConnectionListeners

addFolderListener

removeFolderListener

notifyFolderListeners

notifyFolderRenamedListeners

addMessageCountListener

removeMessageCountListener

notifyMessageAddedListeners

notifyMessageRemovedListeners

addMessageChangedListener

removeMessageChangedListener

notifyMessageChangedListeners

toString