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 or Folder, 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
getFolder(folder_name) on the same
folder_name multiple times will return distinct Folder
objects. Likewise for
list() and
listSubscribed().
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.
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.
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 MessageChanged events on this Folder.
addMessageCountListener
public void addMessageCountListener(MessageCountListener l)
Add a listener for MessageCount events on this Folder.
appendMessages
public void appendMessages(Message msgs)
throws MessagingException Append given Messages to this folder.
This method can be invoked on a closed Folder.
An appropriate MessageCountEvent is delivered to any
MessageCountListener registered on this folder when the messages arrive
in the folder.
Folder implementations must not abort this operation if a Message in the
given message array turns out to be an expunged Message.
msgs - array of Messages to be appended
MessagingException - if the append failed.
close
public void close(boolean expunge)
throws MessagingException Close this Folder.
This method is valid only on open Folders.
A CLOSED ConnectionEvent is delivered to any ConnectionListeners
registered on this Folder. Note that the folder is closed even if
this method terminates abnormally by throwing a MessagingException.
expunge - expunges all deleted messages if this flag is true
copyMessages
public void copyMessages(Message msgs,
Folder folder)
throws MessagingException Copy the specified Messages from this Folder into another Folder.
This operation appends these Messages to the destination Folder.
The destination Folder does not have to be opened.
An appropriate MessageCountEvent is delivered to any
MessageCountListener registered on the destination folder when the
messages arrive in the folder.
Note that the specified Message objects must belong to this folder.
Folder implementations might be able to optimize this method by doing
server-side copies.
This implementation just invokes
appendMessages() on the
destination folder to append the given Messages.
Specific folder implementations that support server-side copies should
do so, if the destination folder's Store is the same as this folder's
Store. Also, an implementation must not abort the operation if a
Message in the array turns out to be an expunged Message.
folder - the folder to copy the messages to
create
public boolean create(int type)
throws MessagingException Create this folder on 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 type of this folder.
delete
public boolean delete(boolean recurse)
throws MessagingException Delete this Folder.
This method will succeed only on a closed Folder.
The
recurse flag controls whether the deletion affects
subfolders or not. If true, all subfolders are deleted, then this
folder itself is deleted. If false, the behaviour is dependent on
the folder type and is elaborated below:
- The folder can contain only messages:
(
type==HOLDS_MESSAGES).
All messages within the folder are removed. The folder itself is then
removed. An appropriate FolderEvent is generated by the Store and this
folder.
- The folder can contain only subfolders:
(
type==HOLDS_FOLDERS).
If this folder is empty(does not contain any subfolders at all), it is
removed. An appropriate FolderEvent is generated by the Store and this
folder.
If this folder contains any subfolders, the delete fails and returns
false.
- The folder can contain subfolders as well as messages:
If the folder is empty(no messages or subfolders), it is removed. If
the folder contains no subfolders, but only messages, then all messages
are removed. The folder itself is then removed. In both the above
cases, an appropriate FolderEvent is generated by the Store and this
folder.
If the folder contains subfolders there are 3 possible choices an
implementation is free to do:
- The operation fails, irrespective of whether this folder contains
messages or not. Some implementations might elect to go with this
simple approach. The
delete() method returns false.
- Any messages within the folder are removed. Subfolders are not
removed. The folder itself is not removed or affected in any
manner. The
delete() method returns true.
And the exists() method on this folder will return true
indicating that this folder still exists.
An appropriate FolderEvent is generated by the Store and this folder.
- Any messages within the folder are removed. Subfolders are not
removed. The folder itself changes its type from
HOLDS_FOLDERS |
HOLDS_MESSAGES to HOLDS_FOLDERS. Thus new messages
cannot be added to this folder, but new subfolders can be created
underneath. The delete() method returns true indicating
success. The exists() method on this folder will return
true indicating that this folder still exists.
An appropriate FolderEvent is generated by the Store and this folder.
- true if the Folder is deleted successfully
exists
public boolean exists()
throws MessagingException Indicates if this folder physically exists on the Store.
This method can be invoked on a closed Folder.
expunge
public Message[] expunge()
throws MessagingException Expunge(permanently remove) messages marked DELETED.
Returns an array containing the expunged message objects.
The getMessageNumber method on each of these message objects returns
that Message's original(that is, prior to the expunge) sequence number.
A MessageCountEvent containing the expunged messages is delivered
to any MessageCountListeners registered on the folder.
Expunge causes the renumbering of Message objects subsequent to the
expunged messages. Clients that use message numbers as references to
messages should be aware of this and should be prepared to deal with the
situation(probably by flushing out existing message number caches and
reloading them). Because of this complexity, it is better for clients to
use Message objects as references to messages, rather than message
numbers. Any expunged Messages objects still have to be pruned, but other
Messages in that folder are not affected by the expunge.
After a message is 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 Prefetch the items specified in the FetchProfile for the given Messages.
Clients use this method to indicate that the specified items are needed
en-masse for the given message range. Implementations are expected to
retrieve these items for the given message range in a efficient manner.
Note that this method is just a hint to the implementation to prefetch
the desired items.
An example is a client filling its header-view window with the Subject,
From and X-mailer headers for all messages in the folder.
Message[] msgs = folder.getMessages();
FetchProfile fp = new FetchProfile();
fp.add(FetchProfile.Item.ENVELOPE);
fp.add("X-mailer");
folder.fetch(msgs, fp);
for (int i = 0; i <32folder.getMessageCount(); i++) {
display(msg[i].getFrom());
display(msg[i].getSubject());
display(msg[i].getHeader("X-mailer"));
}
The implementation provided here just returns without doing anything
useful. Providers wanting to provide a real implementation for this
method should override the method.
msgs - fetch items for these messagesfp - the FetchProfile
getDeletedMessageCount
public int getDeletedMessageCount()
throws MessagingException Get the number of deleted messages in this folder.
This method can be invoked on a closed folder. However, note that for
some folder implementations, getting the deleted message count can be
an expensive operation involving actually opening the folder. In such
cases, a provider can choose not to support this functionality in the
closed state, in which case this method must return -1.
Clients invoking this method on a closed folder must be aware that this
is a potentially expensive operation. Clients must also be prepared to
handle a return value of -1 in this case.
This implementation returns -1 if this folder is closed. Otherwise,
this implementation gets each Message in the folder using
getMessage(int) and checks whether its
DELETED flag is set. The total number of messages that
have this flag is returned.
- JavaMail 1.3
getFolder
public Folder getFolder(String name)
throws MessagingException Return the Folder object corresponding to the given name.
Note that this folder does not physically have to exist in the Store.
The
exists() method on a Folder indicates whether it
really exists on 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.
Folder objects are not cached by the Store, so invoking this method on
the same name multiple times will return that many distinct Folder
objects.
This method can be invoked on a closed Folder.
name - name of the Folder
getFullName
public String getFullName()
Returns the full name of this Folder.
If the folder resides under the root hierarchy of this 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 Message getMessage(int msgnum)
throws MessagingException Get the Message object corresponding to the given message number.
A Message object's message number is the relative position of
this Message in itsFolder. Messages are numbered starting at 1
through the total number of message in the folder.
Note that the message number for a particular Message can change
during a session if other messages in the Folder are deleted and
the Folder is expunged.
Message objects are light-weight references to the actual message that
get filled up on demand. Hence Folder implementations are expected to
provide light-weight Message objects.
Unlike Folder objects, repeated calls to getMessage with the same
message number will return the same Message object, as long as no
messages in this folder have been expunged.
Since message numbers can change within a session if the folder is
expunged, clients are advised not to use message numbers as references
to messages. Use Message objects instead.
msgnum - the message number
getMessageCount
public int getMessageCount()
throws MessagingException Get total number of messages in this Folder.
This method can be invoked on a closed folder.
However, note that for some folder implementations, getting the
total message count can be an expensive operation involving actually
opening the folder. In such cases, a provider can choose not to
support this functionality in the closed state, in which case this
method must return -1.
Clients invoking this method on a closed folder must be aware that
this is a potentially expensive operation.
Clients must also be prepared to handle a return value of -1 in
this case.
getMessages
public Message[] getMessages()
throws MessagingException Get all Message objects from this Folder.
Returns an empty array if the folder is empty.
Clients can use Message objects(instead of sequence numbers)
as references to the messages within a folder; this method supplies
the Message objects to the client.
Folder implementations are expected to provide light-weight Message
objects, which get filled on demand.
This implementation invokes
getMessageCount() to get
the current message count and then uses
getMessage()
to get Message objects from 1 till the message count.
getMessages
public Message[] getMessages(int start,
int end)
throws MessagingException Get the Message objects for message numbers ranging from
start through
end, both start and end
inclusive. Note that message numbers start at 1, not 0.
Message objects are light-weight references to the actual message
that get filled up on demand. Hence Folder implementations are expected
to provide light-weight Message objects.
This implementation uses
getMessage(index) to obtain the
required Message objects. Note that the returned array must contain
(end-start+1) Message objects.
start - the number of the first messageend - the number of the last message
getMessages
public Message[] getMessages(msgnums[] )
throws MessagingException Get the Message objects for message numbers specified in the array.
Message objects are light-weight references to the actual message
that get filled up on demand. Hence Folder implementations are expected
to provide light-weight Message objects.
This implementation uses
getMessage(index) to obtain the
required Message objects. Note that the returned array must contain
msgnums.length Message objects.
getMode
public int getMode()
Return the open mode of this folder.
Returns Folder.READ_ONLY, Folder.READ_WRITE,
or -1 if the open mode is not known(usually only
because an older Folder provider has not been updated to use this new
method).
getName
public String getName()
Returns the name of this Folder.
This method can be invoked on a closed Folder.
getNewMessageCount
public int getNewMessageCount()
throws MessagingException Get the number of new messages in this Folder.
This method can be invoked on a closed folder.
However, note that for some folder implementations, getting the
new message count can be an expensive operation involving actually
opening the folder. In such cases, a provider can choose not to
support this functionality in the closed state, in which case this
method must return -1.
Clients invoking this method on a closed folder must be aware that
this is a potentially expensive operation.
Clients must also be prepared to handle a return value of -1 in
this case.
This implementation returns -1 if this folder is closed.
Else this implementation gets each Message in the folder using
getMessage(int) and checks whether its RECENT flag is
set. The total number of messages that have this flag set is returned.
getParent
public Folder getParent()
throws MessagingException Returns the parent folder of this folder.
This method can be invoked on a closed Folder.
If this folder is the top of a folder hierarchy, this method returns
null.
Note that since Folder objects are not cached, invoking this method
returns a new distinct Folder object.
getPermanentFlags
public Flags getPermanentFlags()
Get the permanent flags supported by this Folder.
Returns a Flags object that contains all the flags supported.
The special flag
Flags.USER indicates that this Folder
supports arbitrary user-defined flags.
The supported permanent flags for a folder may not be available
until the folder is opened.
getSeparator
public char getSeparator()
throws MessagingException Return the delimiter character that separates this Folder's pathname
from the names of immediate subfolders.
This method can be invoked on a closed Folder.
getStore
public Store getStore()
Returns the Store that owns this Folder object.
This method can be invoked on a closed Folder.
getType
public int getType()
throws MessagingException Returns the type of this Folder, that is, 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 representing this folder.
The returned URLName does not include the password
used to access the store.
getUnreadMessageCount
public int getUnreadMessageCount()
throws MessagingException Get the total number of unread messages in this Folder.
This method can be invoked on a closed folder.
However, note that for some folder implementations, getting the
unread message count can be an expensive operation involving actually
opening the folder. In such cases, a provider can choose not to
support this functionality in the closed state, in which case this
method must return -1.
Clients invoking this method on a closed folder must be aware that
this is a potentially expensive operation.
Clients must also be prepared to handle a return value of -1 in
this case.
This implementation returns -1 if this folder is closed.
Else this implementation gets each Message in the folder using
getMessage(int) and checks whether its SEEN flag is
set. The total number of messages that have this flag set is returned.
hasNewMessages
public boolean hasNewMessages()
throws MessagingException Returns true if this Folder has new messages since the last time
this indication was reset.
When this indication is set or reset depends on the Folder
implementation(and in the case of IMAP, depends on the server).
This method can be used to implement a lightweight "check for new mail"
operation on a Folder without opening it.(For example, a thread that
monitors a mailbox and flags when it has new mail.) This method should
indicate whether any messages in the Folder have the RECENT flag set.
Note that this is not an incremental check for new mail, i.e., it
cannot be used to determine whether any new messages have arrived since
the last time this method was invoked. To implement incremental checks,
the Folder needs to be opened.
This method can be invoked on a closed Folder that can contain Messages.
isOpen
public boolean isOpen()
Indicates whether this Folder is in the 'open' state.
isSubscribed
public boolean isSubscribed()
Returns true if this Folder is subscribed.
This method can be invoked on a closed Folder.
The default implementation provided here just returns true.
list
public Folder[] list()
throws MessagingException Convenience method that returns the list of folders under this Folder.
This method just calls the list(String pattern) method
with "%" as the match pattern.
This method can be invoked on a closed Folder.
list
public Folder[] list(String pattern)
throws MessagingException Returns a list of Folders belonging to this Folder's namespace
that match the specified pattern.
Patterns may contain the wildcard characters "%",
which matches any character except hierarchy delimiters, and "*",
which matches any character.
As an example, given the folder hierarchy:
Personal/
Finance/
Stocks
Bonus
StockOptions
Jokes
list("*") on "Personal" will return the whole hierarchy.
list("%") on "Personal" will return "Finance" and "Jokes".
list("Jokes") on "Personal" will return "Jokes".
list("Stock*") on "Finance" will return "Stocks" and "StockOptions".
Folder objects are not cached by the Store, so invoking this method
on the same pattern multiple times will return that many distinct
Folder objects.
This method can be invoked on a closed Folder.
pattern - the match pattern
listSubscribed
public Folder[] listSubscribed()
throws MessagingException Convenience method that returns the list of subscribed folders
under this Folder.
This method just calls the listSubscribed(String pattern)
method with "%" as the match pattern.
This method can be invoked on a closed Folder.
listSubscribed
public Folder[] listSubscribed(String pattern)
throws MessagingException Returns a list of subscribed Folders belonging to
this Folder's namespace that match the specified pattern.
If the folder does not support subscription, this method should
resolve to
list.
(The default implementation provided here, does just this).
The pattern can contain wildcards as for list.
Folder objects are not cached by the Store, so invoking this method
on the same pattern multiple times will return that many distinct
Folder objects.
This method can be invoked on a closed Folder.
pattern - the match pattern
notifyConnectionListeners
protected void notifyConnectionListeners(int type)
Notify all ConnectionListeners.
Folder implementations are expected to use this method
to broadcast connection events.
notifyFolderListeners
protected void notifyFolderListeners(int type)
Notify all FolderListeners registered on this Folder and this folder's
Store. Folder implementations are expected to use this method to
broadcast Folder events.
notifyFolderRenamedListeners
protected void notifyFolderRenamedListeners(Folder folder)
Notify all FolderListeners registered on this Folder and this folder's
Store about the renaming of this folder. Folder implementations are
expected to use this method to broadcast Folder events indicating the
renaming of folders.
notifyMessageAddedListeners
protected void notifyMessageAddedListeners(Message msgs)
Notify all MessageCountListeners about the addition of messages
into this folder. Folder implementations are expected to use this
method to broadcast MessageCount events for indicating arrival of
new messages.
notifyMessageChangedListeners
protected void notifyMessageChangedListeners(int type,
Message msg) Notify all MessageChangedListeners. Folder implementations are expected
to use this method to broadcast MessageChanged events.
notifyMessageRemovedListeners
protected void notifyMessageRemovedListeners(boolean removed,
Message msgs) Notify all MessageCountListeners about the removal of messages from this
Folder. Folder implementations are expected to use this method to
broadcast MessageCount events indicating removal of messages.
open
public void open(int mode)
throws MessagingException Open this Folder.
This method is valid only on Folders that can contain Messages and
that are closed.
If this folder is opened successfully, an OPENED ConnectionEvent is
delivered to any ConnectionListeners registered on this Folder.
The effect of opening multiple connections to the same folder on a
specific Store is implementation dependent. Some implementations allow
multiple readers, but only one writer. Others allow multiple writers
as well as readers.
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 MessageChanged listener.
removeMessageCountListener
public void removeMessageCountListener(MessageCountListener l)
Remove a MessageCount listener.
renameTo
public boolean renameTo(Folder folder)
throws MessagingException Rename this Folder.
This method will succeed only on a closed Folder.
If the rename is successful, a RENAMED FolderEvent is delivered to
FolderListeners registered on this folder and its containing Store.
folder - a folder representing the new name for this Folder
- true if the Folder is renamed successfully
search
public Message[] search(SearchTerm term)
throws MessagingException Search this Folder for messages matching the specified search criterion.
Returns an array containing the matching messages.
Returns an empty array if no matches were found.
This implementation invokes
search(term, getMessages()),
to apply the search over all the messages in this folder.
Providers that can implement server-side searching might want to
override this method to provide a more efficient implementation.
term - the search criterion
search
public Message[] search(SearchTerm term,
Message msgs)
throws MessagingException Search the given array of messages for those that match the specified
search criterion.
Returns an array containing the matching messages.
Returns an empty array if no matches were found.
Note that the specified Message objects must belong to this folder.
This implementation iterates through the given array of messages, and
applies the search criterion on each message by calling its
match() method with the given term. The messages that
succeed in the match are returned.
Providers that can implement server-side searching might want to override
this method to provide a more efficient implementation. If the search term
is too complex or contains user-defined terms that cannot be executed on
the server, providers may elect to either throw a SearchException or
degenerate to client-side searching by calling
super.search() to invoke this implementation.
term - the search criterionmsgs - 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 messages numbered from
start
through
end, both start and end inclusive.
Note that message numbers start at 1, not 0.
This will result in appropriate MessageChangedEvents being delivered
to any MessageChangedListener registered on this Message's containing
folder.
Certain Folder implementations can optimize the operation of setting
Flags for a group of messages, so clients might want to use this method,
rather than invoking
Message.setFlags for each Message.
The default implementation uses
getMessage(int) to get
each Message object and then invokes
setFlags on that
object to set the flags. Specific Folder implementations that can
optimize this case should do so. Also, an implementation must not abort
the operation if a message number refers to an expunged message.
start - the number of the first messageend - the number of the last messageflag - Flags object containing the flags to be setvalue - set the flags to this boolean value
setFlags
public void setFlags(Message msgs,
Flags flag,
boolean value)
throws MessagingException Set the specified flags on the messages specified in the array.
This will result in appropriate MessageChangedEvents being delivered
to any MessageChangedListener registered on this Message's containing
folder.
Note that the specified Message objects must belong to this folder.
Certain Folder implementations can optimize the operation of setting
Flags for a group of messages, so clients might want to use this
method, rather than invoking
Message.setFlags for each
Message.
This implementation degenerates to invoking
setFlags()
on each Message object. Specific Folder implementations that can
optimize this case should do so. Also, an implementation must not
abort the operation if a Message in the array turns out to be an
expunged Message.
flag - Flags object containing the flags to be setvalue - set the flags to this boolean value
setFlags
public void setFlags(msgnums[] ,
Flags flag,
boolean value)
throws MessagingException Set the specified flags on the messages whose message numbers
are in the array.
This will result in appropriate MessageChangedEvents being delivered
to any MessageChangedListener registered on this Message's containing
folder.
Certain Folder implementations can optimize the operation of setting
Flags for a group of messages, so clients might want to use this method,
rather than invoking
Message.setFlags for each Message.
The default implementation uses
getMessage(int) to get
each Message object and then invokes
setFlags on that
object to set the flags. Specific Folder implementations that can
optimize this case should do so. Also, an implementation must not abort
the operation if a message number refers to an expunged message.
flag - Flags object containing the flags to be setvalue - set the flags to this boolean value
setSubscribed
public void setSubscribed(boolean flag)
throws MessagingException Subscribe or unsubscribe this Folder.
Not all Stores support subscription.
This method can be invoked on a closed Folder.
The implementation provided here just throws the
MethodNotSupportedException.
toString
public String toString()
override the default toString(),
it will return the String from Folder.getFullName() or if that is null,
it will use the default toString() behavior.