public abstract class Folder extends Object implements AutoCloseable
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 this 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.
Modifier and Type | Field and Description |
---|---|
static int |
HOLDS_FOLDERS
This folder can contain other folders
|
static int |
HOLDS_MESSAGES
This folder can contain messages
|
protected int |
mode
The open mode of this folder.
|
static int |
READ_ONLY
The Folder is read only.
|
static int |
READ_WRITE
The state and contents of this folder can be modified.
|
protected Store |
store
The parent store.
|
Modifier | Constructor and Description |
---|---|
protected |
Folder(Store store)
Constructor that takes a Store object.
|
Modifier and Type | Method and Description |
---|---|
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 MessageChanged events on this Folder.
|
void |
addMessageCountListener(MessageCountListener l)
Add a listener for MessageCount events on this Folder.
|
abstract void |
appendMessages(Message[] msgs)
Append given Messages to this folder.
|
void |
close()
Close this Folder and expunge deleted messages.
|
abstract void |
close(boolean expunge)
Close this Folder.
|
void |
copyMessages(Message[] msgs,
Folder folder)
Copy the specified Messages from this Folder into another
Folder.
|
abstract boolean |
create(int type)
Create this folder on the Store.
|
abstract boolean |
delete(boolean recurse)
Delete this Folder.
|
abstract boolean |
exists()
Tests if this folder physically exists on the Store.
|
abstract Message[] |
expunge()
Expunge (permanently remove) messages marked DELETED.
|
void |
fetch(Message[] msgs,
FetchProfile fp)
Prefetch the items specified in the FetchProfile for the
given Messages.
|
protected void |
finalize() |
int |
getDeletedMessageCount()
Get the number of deleted messages in this Folder.
|
abstract Folder |
getFolder(String name)
Return the Folder object corresponding to the given name.
|
abstract String |
getFullName()
Returns the full name of this Folder.
|
abstract Message |
getMessage(int msgnum)
Get the Message object corresponding to the given message
number.
|
abstract int |
getMessageCount()
Get total number of messages in this Folder.
|
Message[] |
getMessages()
Get all Message objects from this Folder.
|
Message[] |
getMessages(int[] msgnums)
Get the Message objects for message numbers specified in
the array.
|
Message[] |
getMessages(int start,
int end)
Get the Message objects for message numbers ranging from start
through end, both start and end inclusive.
|
int |
getMode()
Return the open mode of this folder.
|
abstract String |
getName()
Returns the name of this Folder.
|
int |
getNewMessageCount()
Get the number of new messages in this Folder.
|
abstract Folder |
getParent()
Returns the parent folder of this folder.
|
abstract Flags |
getPermanentFlags()
Get the permanent flags supported by this Folder.
|
abstract char |
getSeparator()
Return the delimiter character that separates this Folder's pathname
from the names of immediate subfolders.
|
Store |
getStore()
Returns the Store that owns this Folder object.
|
abstract int |
getType()
Returns the type of this Folder, that is, whether this folder can hold
messages or subfolders or both.
|
int |
getUnreadMessageCount()
Get the total number of unread messages in this Folder.
|
URLName |
getURLName()
Return a URLName representing this folder.
|
abstract boolean |
hasNewMessages()
Returns true if this Folder has new messages since the last time
this indication was reset.
|
abstract boolean |
isOpen()
Indicates whether this Folder is in the 'open' state.
|
boolean |
isSubscribed()
Returns true if this Folder is subscribed.
|
Folder[] |
list()
Convenience method that returns the list of folders under this
Folder.
|
abstract Folder[] |
list(String pattern)
Returns a list of Folders belonging to this Folder's namespace
that match the specified pattern.
|
Folder[] |
listSubscribed()
Convenience method that returns the list of subscribed folders
under this Folder.
|
Folder[] |
listSubscribed(String pattern)
Returns a list of subscribed Folders belonging to this Folder's
namespace that match the specified pattern.
|
protected void |
notifyConnectionListeners(int type)
Notify all ConnectionListeners.
|
protected void |
notifyFolderListeners(int type)
Notify all FolderListeners registered on this Folder and
this folder's Store.
|
protected void |
notifyFolderRenamedListeners(Folder folder)
Notify all FolderListeners registered on this Folder and
this folder's Store about the renaming of this folder.
|
protected void |
notifyMessageAddedListeners(Message[] msgs)
Notify all MessageCountListeners about the addition of messages
into this folder.
|
protected void |
notifyMessageChangedListeners(int type,
Message msg)
Notify all MessageChangedListeners.
|
protected void |
notifyMessageRemovedListeners(boolean removed,
Message[] msgs)
Notify all MessageCountListeners about the removal of messages
from this Folder.
|
abstract void |
open(int mode)
Open 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 MessageChanged listener.
|
void |
removeMessageCountListener(MessageCountListener l)
Remove a MessageCount listener.
|
abstract boolean |
renameTo(Folder f)
Rename this Folder.
|
Message[] |
search(SearchTerm term)
Search this Folder for messages matching the specified
search criterion.
|
Message[] |
search(SearchTerm term,
Message[] msgs)
Search the given array of messages for those that match the
specified search criterion.
|
void |
setFlags(int[] msgnums,
Flags flag,
boolean value)
Set the specified flags on the messages whose message numbers
are in the array.
|
void |
setFlags(int start,
int end,
Flags flag,
boolean value)
Set the specified flags on the messages numbered from start
through end, both start and end inclusive.
|
void |
setFlags(Message[] msgs,
Flags flag,
boolean value)
Set the specified flags on the messages specified in the array.
|
void |
setSubscribed(boolean subscribe)
Subscribe or unsubscribe this Folder.
|
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.
|
protected Store store
protected int mode
Folder.READ_ONLY
, Folder.READ_WRITE
,
or -1 if not known.public static final int HOLDS_MESSAGES
public static final int HOLDS_FOLDERS
public static final int READ_ONLY
public static final int READ_WRITE
protected Folder(Store store)
store
- the Store that holds this folderpublic abstract String getName()
This method can be invoked on a closed Folder.
public abstract String getFullName()
This method can be invoked on a closed Folder.
public URLName getURLName() throws MessagingException
MessagingException
- for failuresURLName
public Store getStore()
public abstract Folder getParent() throws MessagingException
Note that since Folder objects are not cached, invoking this method returns a new distinct Folder object.
MessagingException
- for failurespublic abstract boolean exists() throws MessagingException
MessagingException
- typically if the connection
to the server is lost.create(int)
public abstract Folder[] list(String pattern) throws MessagingException
"%"
, 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 patternFolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failureslistSubscribed(java.lang.String)
public Folder[] listSubscribed(String pattern) throws MessagingException
list
.
(The default implementation provided here, does just this).
The pattern can contain wildcards as for list
.
Note that, at a given level of the folder hierarchy, a particular
folder may not be subscribed, but folders underneath that folder
in the folder hierarchy may be subscribed. In order to allow
walking the folder hierarchy, such unsubscribed folders may be
returned, indicating that a folder lower in the hierarchy is
subscribed. The isSubscribed
method on a folder will
tell whether any particular folder is actually subscribed.
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 patternFolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failureslist(java.lang.String)
public Folder[] list() throws MessagingException
list(String pattern)
method with "%"
as the match pattern. This method can
be invoked on a closed Folder.FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failureslist(java.lang.String)
public Folder[] listSubscribed() throws MessagingException
listSubscribed(String pattern)
method with "%"
as the match pattern. This method can be invoked on a closed Folder.FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failureslistSubscribed(java.lang.String)
public abstract char getSeparator() throws MessagingException
FolderNotFoundException
- if the implementation
requires the folder to exist, but it does notMessagingException
public abstract int getType() throws MessagingException
FolderNotFoundException
- if this folder does
not exist.MessagingException
HOLDS_FOLDERS
,
HOLDS_MESSAGES
public abstract boolean create(int type) throws MessagingException
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.MessagingException
- for failuresHOLDS_FOLDERS
,
HOLDS_MESSAGES
,
FolderEvent
public boolean isSubscribed()
This method can be invoked on a closed Folder.
The default implementation provided here just returns true.
public void setSubscribed(boolean subscribe) throws MessagingException
This method can be invoked on a closed Folder.
The implementation provided here just throws the MethodNotSupportedException.
subscribe
- true to subscribe, false to unsubscribeFolderNotFoundException
- if this folder does
not exist.MethodNotSupportedException
- if this store
does not support subscriptionMessagingException
- for other failurespublic abstract boolean hasNewMessages() throws MessagingException
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.
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic abstract Folder getFolder(String name) throws MessagingException
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 FolderMessagingException
- for failurespublic abstract boolean delete(boolean recurse) throws MessagingException
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:
If the folder contains subfolders there are 3 possible choices an implementation is free to do:
recurse
- also delete subfolders?FolderNotFoundException
- if this folder does
not existIllegalStateException
- if this folder is not in
the closed state.MessagingException
- for other failuresFolderEvent
public abstract boolean renameTo(Folder f) throws MessagingException
If the rename is successful, a RENAMED FolderEvent is delivered to FolderListeners registered on this folder and its containing Store.
f
- a folder representing the new name for this FolderFolderNotFoundException
- if this folder does
not existIllegalStateException
- if this folder is not in
the closed state.MessagingException
- for other failuresFolderEvent
public abstract void open(int mode) throws MessagingException
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 specifc 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_WRITEFolderNotFoundException
- if this folder does
not exist.IllegalStateException
- if this folder is not in
the closed state.MessagingException
- for other failuresREAD_ONLY
,
READ_WRITE
,
getType()
,
ConnectionEvent
public abstract void close(boolean expunge) throws MessagingException
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 trueIllegalStateException
- if this folder is not openedMessagingException
- for other failuresConnectionEvent
public void close() throws MessagingException
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.
This method supports the AutoCloseable
interface.
This implementation calls close(true)
.
close
in interface AutoCloseable
IllegalStateException
- if this folder is not openedMessagingException
- for other failuresConnectionEvent
public abstract boolean isOpen()
public int getMode()
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).IllegalStateException
- if this folder is not openedpublic abstract Flags getPermanentFlags()
The special flag Flags.Flag.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.
public abstract int getMessageCount() throws MessagingException
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.
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic int getNewMessageCount() throws MessagingException
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.
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic int getUnreadMessageCount() throws MessagingException
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 do not have this flag set is returned.
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic int getDeletedMessageCount() throws MessagingException
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. Else
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 set is returned.
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic abstract Message getMessage(int msgnum) throws MessagingException
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 numberFolderNotFoundException
- if this folder does
not exist.IllegalStateException
- if this folder is not openedIndexOutOfBoundsException
- if the message number
is out of range.MessagingException
- for other failuresgetMessageCount()
,
fetch(javax.mail.Message[], javax.mail.FetchProfile)
public Message[] getMessages(int start, int end) throws MessagingException
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 messageFolderNotFoundException
- if this folder does
not exist.IllegalStateException
- if this folder is not opened.IndexOutOfBoundsException
- if the start or end
message numbers are out of range.MessagingException
- for other failuresfetch(javax.mail.Message[], javax.mail.FetchProfile)
public Message[] getMessages(int[] msgnums) throws MessagingException
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
msgnums
- the array of message numbersFolderNotFoundException
- if this folder does
not exist.IllegalStateException
- if this folder is not opened.IndexOutOfBoundsException
- if any message number
in the given array is out of range.MessagingException
- for other failuresfetch(javax.mail.Message[], javax.mail.FetchProfile)
public Message[] getMessages() throws MessagingException
This implementation invokes getMessageCount()
to get
the current message count and then uses getMessage()
to get Message objects from 1 till the message count.
FolderNotFoundException
- if this folder does
not exist.IllegalStateException
- if this folder is not opened.MessagingException
- for other failuresfetch(javax.mail.Message[], javax.mail.FetchProfile)
public abstract void appendMessages(Message[] msgs) throws MessagingException
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 appendedFolderNotFoundException
- if this folder does
not exist.MessagingException
- if the append failed.public void fetch(Message[] msgs, FetchProfile fp) throws MessagingException
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 < folder.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 this method.
msgs
- fetch items for these messagesfp
- the FetchProfileIllegalStateException
- if this folder is not openedMessagingException
- for other failurespublic void setFlags(Message[] msgs, Flags flag, boolean value) throws MessagingException
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.
msgs
- the array of message objectsflag
- Flags object containing the flags to be setvalue
- set the flags to this boolean valueIllegalStateException
- if this folder is not opened
or if it has been opened READ_ONLY.MessagingException
- for other failuresMessage.setFlags(javax.mail.Flags, boolean)
,
MessageChangedEvent
public void setFlags(int start, int end, Flags flag, boolean value) throws MessagingException
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 valueIllegalStateException
- if this folder is not opened
or if it has been opened READ_ONLY.IndexOutOfBoundsException
- if the start or end
message numbers are out of range.MessagingException
- for other failuresMessage.setFlags(javax.mail.Flags, boolean)
,
MessageChangedEvent
public void setFlags(int[] msgnums, Flags flag, boolean value) throws MessagingException
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.
msgnums
- the array of message numbersflag
- Flags object containing the flags to be setvalue
- set the flags to this boolean valueIllegalStateException
- if this folder is not opened
or if it has been opened READ_ONLY.IndexOutOfBoundsException
- if any message number
in the given array is out of range.MessagingException
- for other failuresMessage.setFlags(javax.mail.Flags, boolean)
,
MessageChangedEvent
public void copyMessages(Message[] msgs, Folder folder) throws MessagingException
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.
msgs
- the array of message objectsfolder
- the folder to copy the messages toFolderNotFoundException
- if the destination
folder does not exist.IllegalStateException
- if this folder is not opened.MessagingException
- for other failuresappendMessages(javax.mail.Message[])
public abstract Message[] expunge() throws MessagingException
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
FolderNotFoundException
- if this folder does not
existIllegalStateException
- if this folder is not opened.MessagingException
- for other failuresMessage.isExpunged()
,
MessageCountEvent
public Message[] search(SearchTerm term) throws MessagingException
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 criterionSearchException
- if the search
term is too complex for the implementation to handle.FolderNotFoundException
- if this folder does
not exist.IllegalStateException
- if this folder is not opened.MessagingException
- for other failuresSearchTerm
public Message[] search(SearchTerm term, Message[] msgs) throws MessagingException
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 searchedSearchException
- if the search
term is too complex for the implementation to handle.IllegalStateException
- if this folder is not openedMessagingException
- for other failuresSearchTerm
public void addConnectionListener(ConnectionListener l)
The implementation provided here adds this listener to an internal list of ConnectionListeners.
l
- the Listener for Connection eventsConnectionEvent
public void removeConnectionListener(ConnectionListener l)
The implementation provided here removes this listener from the internal list of ConnectionListeners.
l
- the listeneraddConnectionListener(javax.mail.event.ConnectionListener)
protected void notifyConnectionListeners(int type)
The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered ConnectionListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.
type
- the ConnectionEvent typeConnectionEvent
public void addFolderListener(FolderListener l)
The implementation provided here adds this listener to an internal list of FolderListeners.
l
- the Listener for Folder eventsFolderEvent
public void removeFolderListener(FolderListener l)
The implementation provided here removes this listener from the internal list of FolderListeners.
l
- the listeneraddFolderListener(javax.mail.event.FolderListener)
protected void notifyFolderListeners(int type)
The implementation provided here queues the event into
an internal event queue. An event dispatcher thread dequeues
events from the queue and dispatches them to the
FolderListeners registered on this folder. The implementation
also invokes notifyFolderListeners
on this folder's
Store to notify any FolderListeners registered on the store.
type
- type of FolderEventnotifyFolderRenamedListeners(javax.mail.Folder)
protected void notifyFolderRenamedListeners(Folder folder)
The implementation provided here queues the event into
an internal event queue. An event dispatcher thread dequeues
events from the queue and dispatches them to the
FolderListeners registered on this folder. The implementation
also invokes notifyFolderRenamedListeners
on this
folder's Store to notify any FolderListeners registered on the store.
folder
- Folder representing the new name.notifyFolderListeners(int)
public void addMessageCountListener(MessageCountListener l)
The implementation provided here adds this listener to an internal list of MessageCountListeners.
l
- the Listener for MessageCount eventsMessageCountEvent
public void removeMessageCountListener(MessageCountListener l)
The implementation provided here removes this listener from the internal list of MessageCountListeners.
l
- the listeneraddMessageCountListener(javax.mail.event.MessageCountListener)
protected void notifyMessageAddedListeners(Message[] msgs)
The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered MessageCountListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.
msgs
- the messages that were addedprotected void notifyMessageRemovedListeners(boolean removed, Message[] msgs)
The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to the registered MessageCountListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.
removed
- was the message removed by this client?msgs
- the messages that were removedpublic void addMessageChangedListener(MessageChangedListener l)
The implementation provided here adds this listener to an internal list of MessageChangedListeners.
l
- the Listener for MessageChanged eventsMessageChangedEvent
public void removeMessageChangedListener(MessageChangedListener l)
The implementation provided here removes this listener from the internal list of MessageChangedListeners.
l
- the listeneraddMessageChangedListener(javax.mail.event.MessageChangedListener)
protected void notifyMessageChangedListeners(int type, Message msg)
The provided implementation queues the event into an internal event queue. An event dispatcher thread dequeues events from the queue and dispatches them to registered MessageChangedListeners. Note that the event dispatching occurs in a separate thread, thus avoiding potential deadlock problems.
type
- the MessageChangedEvent typemsg
- the message that changedprotected void finalize() throws Throwable
Copyright © 2019 JBoss by Red Hat. All rights reserved.