Folder is an abstract class that represents a folder for mail messages. Subclasses implement protocol specific Folders.
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).
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.
The case-insensitive full folder name (that is, the full name relative to the default folder for a Store) INBOX 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 INBOX is reserved to refer to this folder, when it exists, in Stores that provide it.
A Folder object obtained from a Store need not actually exist in the backend store. The exists method tests whether the folder exists or not. The create method creates a Folder.
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 open, delete and renameTo, are valid in this state.
The only way to get a Folder is by invoking the getFolder method on Store, Folder, or Session, or by invoking the list or listSubscribed methods on Folder. Folder objects returned by the above methods are not cached by the Store. Thus, invoking the getFolder method with the same folder name multiple times will return distinct Folder objects. Likewise for the list and listSubscribed methods.
The Message objects within the Folder are cached by the Folder. Thus, invoking getMessage(msgno) on the same message number multiple times will return the same Message object, until an expunge is done on this Folder.
Message objects from a Folder are only valid while a Folder is open and should not be accessed after the Folder is closed, even if the Folder is subsequently reopened. Instead, new Message objects must be fetched from the Folder after the Folder is reopened.
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