javax.mail
public abstract class Folder extends Object
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
Field Summary | |
---|---|
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 | |
---|---|
protected | Folder(Store store)
Constructor. |
Method Summary | |
---|---|
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(String name)
Return a folder corresponding to the given name.
|
abstract 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(int start, int end)
Returns the messages in the given range (inclusive). |
Message[] | getMessages(int[] msgnums)
Returns the messages for the specified message numbers. |
Message[] | getMessages()
Returns all messages in this folder. |
int | getMode()
Return the mode this folder is open in.
|
abstract 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. whether this folder can hold
messages or subfolders or both.
|
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.
|
abstract Folder[] | list(String pattern)
Returns a list of subfolders matching the specified pattern.
|
Folder[] | list()
Returns the list of subfolders of this folder.
|
Folder[] | listSubscribed(String pattern)
Returns a list of subscribed subfolders matching the specified pattern.
|
Folder[] | listSubscribed()
Returns the list of subscribed subfolders of this folder.
|
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(Message[] msgs, Flags flag, boolean value)
Sets the specified flags on each specified message. |
void | setFlags(int start, int end, Flags flag, boolean value)
Set the specified flags on the given range of messages (inclusive). |
void | setFlags(int[] msgnums, Flags flag, boolean value)
Sets the specified flags on each of the specified messages. |
void | setSubscribed(boolean flag)
Subscribe to or unsubscribe from this folder.
|
String | toString()
Returns the value of Folder.getFullName(), or, if that is null,
returns the default toString(). |
Parameters: store the parent store
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
Parameters: expunge if true, expunge all deleted messages
The destination folder does not have to be open.
Parameters: msgs the messages folder the folder to copy the messages to
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
Parameters: recurse delete any subfolders
Returns: true if the folder is deleted successfully, false otherwise
Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is not closed
This method can be invoked on a closed folder.
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 IllegalStateException if this folder is closed
Parameters: msgs the messages to fetch the items for fp the fetch profile
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
Since: JavaMail 1.3
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
This method can be invoked on a closed folder.
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 IllegalStateException if this folder is closed IndexOutOfBoundsException if the message number is out of range
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.
Parameters: start the number of the first message end the number of the last message
Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed IndexOutOfBoundsException if the start or end message numbers are out of range.
Parameters: msgnums the array of message numbers
Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed IndexOutOfBoundsException if any message number in the given array is out of range
Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed
Folder.READ_ONLY
, Folder.READ_WRITE
,
or -1
if the open mode is not known.Throws: IllegalStateException if this folder is not open
This method can be invoked on a closed 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.
null
if this folder is the root of a folder hierarchy.
This method can be invoked on a closed folder.
This method can be invoked on a closed folder.
This method can be invoked on a closed 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.
This method can be invoked on a closed folder.
This method can be invoked on a closed folder that can contain messages.
This method can be invoked on a closed folder.
This method can be invoked on a closed folder.
Parameters: pattern the match pattern
This method can be invoked on a closed folder.
list
method.
The pattern can contain wildcards.
This method can be invoked on a closed folder.
Parameters: pattern the match pattern
This method can be invoked on a closed folder.
Parameters: mode open the Folder READ_ONLY or READ_WRITE
Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is not closed
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 IllegalStateException if this folder is not closed
Parameters: term the search term
Throws: SearchException if there was a problem with the search FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed
Parameters: term the search term msgs the messages to be searched
Throws: SearchException if there was a problem with the search IllegalStateException if this folder is closed
Parameters: msgnums the messages flag the flags to be set value set the flags to this value
Throws: IllegalStateException if this folder is closed or READ_ONLY
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: IllegalStateException if this folder is closed or READ_ONLY IndexOutOfBoundsException if the start or end message numbers are out of range
Parameters: msgnums the message numbers flag the flags to be set value set the flags to this value
Throws: IllegalStateException if this folder is closed or READ_ONLY IndexOutOfBoundsException if any message number in the given array is out of range
This method can be invoked on a closed folder.