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.
addConnectionListener
public void addConnectionListener(ConnectionListener l)
Add a listener for connection events on this folder.
addFolderListener
public void addFolderListener(FolderListener l)
Add a listener for folder events on this folder.
addMessageChangedListener
public void addMessageChangedListener(MessageChangedListener l)
Add a listener for message changed events on this folder.
addMessageCountListener
public void addMessageCountListener(MessageCountListener l)
Add a listener for message count events on this folder.
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.
msgs - array of messages to be appended
close
public abstract void close(boolean expunge)
throws MessagingException Closes this folder.
This method can only be invoked on an open folder.
expunge - if true, expunge all deleted messages
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.
msgs - the messagesfolder - the folder to copy the messages to
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.
type - the desired type of the folder
delete
public abstract boolean delete(boolean recurse)
throws MessagingException Deletes this folder.
This method can only be invoked on a closed folder.
recurse - delete any subfolders
- true if the folder is deleted successfully, false otherwise
exists
public abstract boolean exists()
throws MessagingException Indicates whether this folder exists in the Store.
This method can be invoked on a closed folder.
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.
fetch
public void fetch(Message[] msgs,
FetchProfile fp)
throws MessagingException Fetches the items specified in the given fetch profile for the specified
messages.
msgs - the messages to fetch the items forfp - the fetch profile
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.
getFolder
public abstract Folder getFolder(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.
name - the name of the folder
getFullName
public abstract 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.
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.
msgnum - the message number
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.
getMessages
public Message[] getMessages(int start,
int end)
throws MessagingException Returns the messages in the given range (inclusive).
start - the number of the first messageend - the number of the last message
getMessages
public Message[] getMessages(msgnums[] )
throws MessagingException Returns the messages for the specified message numbers.
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.
getName
public abstract String getName()
Returns the name of this folder.
This method can be invoked on a closed folder.
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.
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.
getPermanentFlags
public abstract Flags getPermanentFlags()
Returns the permanent flags supported by this folder.
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.
getStore
public Store getStore()
Returns the parent store.
This method can be invoked on a closed folder.
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.
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.
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.
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.
isOpen
public abstract boolean isOpen()
Indicates whether this folder is open.
isSubscribed
public boolean isSubscribed()
Indicates whether this folder is subscribed.
This method can be invoked on a closed folder.
list
public Folder[] list()
throws MessagingException Returns the list of subfolders of this folder.
This method can be invoked on a closed folder.
list
public abstract Folder[] list(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.
pattern - the match pattern
listSubscribed
public Folder[] listSubscribed()
throws MessagingException Returns the list of subscribed subfolders of this folder.
This method can be invoked on a closed folder.
listSubscribed
public Folder[] listSubscribed(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.
pattern - the match pattern
notifyConnectionListeners
protected void notifyConnectionListeners(int type)
Notify all connection listeners.
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.
notifyMessageAddedListeners
protected void notifyMessageAddedListeners(Message[] msgs)
Notify all message count listeners about the addition of messages
into this folder.
notifyMessageChangedListeners
protected void notifyMessageChangedListeners(int type,
Message msg) Notify all message changed event listeners.
notifyMessageRemovedListeners
protected void notifyMessageRemovedListeners(boolean removed,
Message[] msgs) Notify all message count listeners about the removal of messages from
this folder.
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.
mode - open the Folder READ_ONLY or READ_WRITE
removeConnectionListener
public void removeConnectionListener(ConnectionListener l)
Remove a connection event listener.
removeFolderListener
public void removeFolderListener(FolderListener l)
Remove a folder event listener.
removeMessageChangedListener
public void removeMessageChangedListener(MessageChangedListener l)
Remove a message changed event listener.
removeMessageCountListener
public void removeMessageCountListener(MessageCountListener l)
Remove a message count event listener.
renameTo
public abstract boolean renameTo(Folder folder)
throws MessagingException Renames this folder.
This method can only be invoked on a closed folder.
folder - a folder representing the new name for this folder
- true if the folder is renamed successfully, false otherwise
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.
term - the search termmsgs - the messages to be searched
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).
start - the number of the first messageend - the number of the last messageflag - the flags to be setvalue - set the flags to this value
setFlags
public void setFlags(int[] msgnums,
Flags flag,
boolean value)
throws MessagingException Sets the specified flags on each of the specified messages.
msgnums - the message numbersflag - the flags to be setvalue - set the flags to this value
setFlags
public void setFlags(Message[] msgs,
Flags flag,
boolean value)
throws MessagingException Sets the specified flags on each specified message.
flag - the flags to be setvalue - set the flags to this value
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.
toString
public String toString()
Returns the value of Folder.getFullName(), or, if that is null,
returns the default toString().