An abstract representation of a folder in a mail system; subclasses would
implement Folders for each supported protocol.
Depending on protocol and implementation, folders may contain other folders, messages,
or both as indicated by the
HOLDS_FOLDERS
and
HOLDS_MESSAGES
flags.
If the immplementation supports hierarchical folders, the format of folder names is
implementation dependent; however, components of the name are separated by the
delimiter character returned by
getSeparator()
.
The case-insensitive folder name "INBOX" is reserved to refer to the primary folder
for the current user on the current server; not all stores will provide an INBOX
and it may not be available at all times.
addFolderListener
public void addFolderListener(FolderListener listener)
appendMessages
public abstract void appendMessages(Message[] messages)
throws MessagingException
Append the supplied messages to this folder. A
MessageCountEvent
is sent
to all listeners registered with this folder when all messages have been appended.
If the array contains a previously expunged message, it must be re-appended to the Store
and implementations must not abort this operation.
messages
- the messages to append
close
public abstract void close(boolean expunge)
throws MessagingException
Close this folder; it must already be open.
A
ConnectionEvent.CLOSED
event is sent to all listeners registered
with this folder.
expunge
- whether to expunge all deleted messages
MessagingException
- if there was a problem accessing the store; the folder is still closed
copyMessages
public void copyMessages(Message[] messages,
Folder folder)
throws MessagingException
Copy the specified messages to another folder.
The default implementation simply appends the supplied messages to the
target folder using
appendMessages(Message[])
.
messages
- the messages to copyfolder
- the folder to copy to
create
public abstract boolean create(int type)
throws MessagingException
Create a new folder capable of containing subfoldera and/or messages as
determined by the type parameter. Any hierarchy defined by the folder
name will be recursively created.
If the folder was sucessfully created, a
CREATED FolderEvent
is sent to all FolderListeners registered with this Folder or with the Store.
type
- the type, indicating if this folder should contain subfolders, messages or both
- true if the folder was sucessfully created
delete
public abstract boolean delete(boolean recurse)
throws MessagingException
Delete this folder and possibly any subfolders. This operation can only be
performed on a closed folder.
If recurse is true, then all subfolders are deleted first, then any messages in
this folder are removed and it is finally deleted;
FolderEvent.DELETED
events are sent as appropriate.
If recurse is false, then the behaviour depends on the folder type and store
implementation as followd:
- If the folder can only conrain messages, then all messages are removed and
then the folder is deleted; a
FolderEvent.DELETED
event is sent. - If the folder can onlu contain subfolders, then if it is empty it will be
deleted and a
FolderEvent.DELETED
event is sent; if the folder is not
empty then the delete fails and this method returns false. - If the folder can contain both subfolders and messages, then if the folder
does not contain any subfolders, any messages are deleted, the folder itself
is deleted and a
FolderEvent.DELETED
event is sent; if the folder does
contain subfolders then the implementation may choose from the following three
behaviors:
- it may return false indicting the operation failed
- it may remove all messages within the folder, send a
FolderEvent.DELETED
event, and then return true to indicate the delete was performed. Note this does
not delete the folder itself and the exists()
operation for this folder
will return true - it may remove all messages within the folder as per the previous option; in
addition it may change the type of the Folder to only HOLDS_FOLDERS indictaing
that messages may no longer be added
FolderEvents are sent to all listeners registered with this folder or
with the Store.
recurse
- whether subfolders should be recursively deleted as well
- true if the delete operation succeeds
exists
public abstract boolean exists()
throws MessagingException
Check to see if this folder physically exists in the store.
This can be invoked when the folder is closed.
- true if the folder really exists
expunge
public abstract Message[] expunge()
throws MessagingException
Permanently delete all supplied messages that have the DELETED flag set from the Store.
The original message indices of all messages actually deleted are returned and a
MessageCountEvent
event is sent to all listeners with this folder. The expunge
may cause the indices of all messaged that remain in the folder to change.
- the original indices of messages that were actually deleted
fetch
public void fetch(Message[] messages,
FetchProfile profile)
throws MessagingException
Hint to the store to prefetch information on the supplied messaged.
Subclasses should override this method to provide an efficient implementation;
the default implementation in this class simply returns.
messages
- messages for which information should be fetchedprofile
- the information to fetch
finalize
protected void finalize()
throws Throwable
Unregisters all listeners.
getDeletedMessageCount
public int getDeletedMessageCount()
throws MessagingException
Return the numbew of messages in this folder that have the Flag.DELETED
flag set.
If this operation is invoked on a closed folder, the implementation
may choose to return -1 to avoid the expense of opening the folder.
The default implmentation of this method iterates over all messages
in the folder; subclasses should override if possible to provide a more
efficient implementation.
- the number of new messages, or -1 if unknown
getFolder
public abstract Folder getFolder(String name)
throws MessagingException
Get the Folder determined by the supplied name; if the name is relative
then it is interpreted relative to this folder. This does not check that
the named folder actually exists.
name
- the name of the folder to return
getFullName
public abstract String getFullName()
Return the full absolute name of this folder.
This can be invoked when the folder is closed.
- the full name of this folder
getMessage
public abstract Message getMessage(int index)
throws MessagingException
Retrieve the message with the specified index in this Folder;
messages indices start at 1 not zero.
Clients should note that the index for a specific message may change
if the folder is expunged;
Message
objects should be used as
references instead.
index
- the index of the message to fetch
getMessageCount
public abstract int getMessageCount()
throws MessagingException
Return the number of messages this folder contains.
If this operation is invoked on a closed folder, the implementation
may choose to return -1 to avoid the expense of opening the folder.
- the number of messages, or -1 if unknown
getMessages
public Message[] getMessages(int start,
int end)
throws MessagingException
Retrieve messages with index between start and end inclusive
start
- index of first messageend
- index of last message
- an array of messages from start to end inclusive
getMode
public int getMode()
Return the mode of this folder ass passed to
open(int)
, or -1 if
the folder is closed.
- the mode this folder was opened with
getName
public abstract String getName()
Return the name of this folder.
This can be invoked when the folder is closed.
getNewMessageCount
public int getNewMessageCount()
throws MessagingException
Return the numbew of messages in this folder that have the Flag.RECENT
flag set.
If this operation is invoked on a closed folder, the implementation
may choose to return -1 to avoid the expense of opening the folder.
The default implmentation of this method iterates over all messages
in the folder; subclasses should override if possible to provide a more
efficient implementation.
- the number of new messages, or -1 if unknown
getParent
public abstract Folder getParent()
throws MessagingException
Return the parent for this folder; if the folder is at the root of a heirarchy
this returns null.
This can be invoked when the folder is closed.
getPermanentFlags
public abstract Flags getPermanentFlags()
Get the flags supported by this folder.
- the flags supported by this folder, or null if unknown
getSeparator
public abstract char getSeparator()
throws MessagingException
Return the character used by this folder's Store to separate path components.
- the name separater character
getStore
public Store getStore()
Return the store that this folder is part of.
- the store this folder is part of
getType
public abstract int getType()
throws MessagingException
Return the type of this folder, indicating whether it can contain subfolders,
messages, or both. The value returned is a bitmask with the appropriate bits set.
getURLName
public URLName getURLName()
throws MessagingException
Return the URLName for this folder, which includes the location of the store.
- the URLName for this folder
getUnreadMessageCount
public int getUnreadMessageCount()
throws MessagingException
Return the numbew of messages in this folder that do not have the Flag.SEEN
flag set.
If this operation is invoked on a closed folder, the implementation
may choose to return -1 to avoid the expense of opening the folder.
The default implmentation of this method iterates over all messages
in the folder; subclasses should override if possible to provide a more
efficient implementation.
- the number of new messages, or -1 if unknown
hasNewMessages
public abstract boolean hasNewMessages()
throws MessagingException
Check to see if this Folder conatins messages with the Flag.RECENT
flag set.
This can be used when the folder is closed to perform a light-weight check for new mail;
to perform an incremental check for new mail the folder must be opened.
- true if the Store has recent messages
isOpen
public abstract boolean isOpen()
Indicates that the folder has been opened.
- true if the folder is open
isSubscribed
public boolean isSubscribed()
Determine if the user is subscribed to this Folder. The default implementation in
this class always returns true.
- true is the user is subscribed to this Folder
list
public abstract Folder[] list(String pattern)
throws MessagingException
Return a list of folders from this Folder's namespace that match the supplied pattern.
Patterns may contain the following wildcards:
- '%' which matches any characater except hierarchy delimiters
- '*' which matches any character including hierarchy delimiters
This can be invoked when the folder is closed.
pattern
- the pattern to search for
- a, possibly empty, array containing Folders that matched the pattern
listSubscribed
public Folder[] listSubscribed()
throws MessagingException
- a, possibly empty, array of subscribed subfolders
listSubscribed
public Folder[] listSubscribed(String pattern)
throws MessagingException
Return a list of folders to which the user is subscribed and which match the supplied pattern.
If the store does not support the concept of subscription then this should match against
all folders; the default implementation of this method achieves this by defaulting to the
list(String)
method.
pattern
- the pattern to search for
- a, possibly empty, array containing subscribed Folders that matched the pattern
notifyConnectionListeners
protected void notifyConnectionListeners(int type)
notifyFolderListeners
protected void notifyFolderListeners(int type)
notifyFolderRenamedListeners
protected void notifyFolderRenamedListeners(Folder newFolder)
notifyMessageAddedListeners
protected void notifyMessageAddedListeners(Message[] messages)
notifyMessageChangedListeners
protected void notifyMessageChangedListeners(int type,
Message message)
notifyMessageRemovedListeners
protected void notifyMessageRemovedListeners(boolean removed,
Message[] messages)
open
public abstract void open(int mode)
throws MessagingException
Open this folder; the folder must be able to contain messages and
must currently be closed. If the folder is opened successfully then
a
ConnectionEvent.OPENED
event is sent to listeners registered
with this Folder.
Whether the Store allows multiple connections or if it allows multiple
writers is implementation defined.
mode
- READ_ONLY or READ_WRITE
removeFolderListener
public void removeFolderListener(FolderListener listener)
renameTo
public abstract boolean renameTo(Folder newName)
throws MessagingException
Rename this folder; the folder must be closed.
If the rename is successfull, a
FolderEvent.RENAMED
event is sent to
all listeners registered with this folder or with the store.
newName
- the new name for this folder
- true if the rename succeeded
search
public Message[] search(SearchTerm term)
throws MessagingException
Search this folder for messages matching the supplied search criteria.
The default implementation simply invoke search(term, getMessages())
applying the search over all messages in the folder; subclasses may provide
a more efficient mechanism.
term
- the search criteria
- an array containing messages that match the criteria
search
public Message[] search(SearchTerm term,
Message[] messages)
throws MessagingException
Search the supplied messages for those that match the supplied criteria;
messages must belong to this folder.
The default implementation iterates through the messages, returning those
whose
Message.match(SearchTerm)
method returns true;
subclasses may provide a more efficient implementation.
term
- the search criteriamessages
- the messages to search
- an array containing messages that match the criteria
setFlags
public void setFlags(ids[] ,
Flags flags,
boolean value)
throws MessagingException
Set flags on a set of messages to the supplied value.
This method may be overridden by subclasses that can optimize the setting
of flags on multiple messages at once; the default implementation simply
gets each message and then calls
Message.setFlags(Flags,boolean)
.
flags
- the set of flags end modifyvalue
- the value the flags should be set end
setFlags
public void setFlags(int start,
int end,
Flags flags,
boolean value)
throws MessagingException
Set flags on a range of messages to the supplied value.
This method may be overridden by subclasses that can optimize the setting
of flags on multiple messages at once; the default implementation simply
gets each message and then calls
Message.setFlags(Flags,boolean)
.
start
- first message end setend
- last message end setflags
- the set of flags end modifyvalue
- the value the flags should be set end
setFlags
public void setFlags(Message[] messages,
Flags flags,
boolean value)
throws MessagingException
Set flags on the messages to the supplied value; all messages must belong to this folder.
This method may be overridden by subclasses that can optimize the setting
of flags on multiple messages at once; the default implementation simply calls
Message.setFlags(Flags,boolean)
for each supplied messages.
messages
- whose flags should be setflags
- the set of flags to modifyvalue
- the value the flags should be set to
setSubscribed
public void setSubscribed(boolean subscribed)
throws MessagingException
Set the user's subscription to this folder.
Not all Stores support subscription; the default implementation in this class
always throws a MethodNotSupportedException
subscribed
- whether to subscribe to this Folder
toString
public String toString()
Returns the full name of this folder; if null, returns the value from the superclass.
- a string form of this folder