|
Java EE 5 SDK | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.mail.Folder
public abstract class Folder
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, 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.
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.
Field Summary | |
---|---|
static int |
HOLDS_FOLDERS
This folder can contain other folders |
static int |
HOLDS_MESSAGES
This folder can contain messages |
protected int |
mode
The 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. |
Constructor Summary | |
---|---|
protected |
Folder(Store store)
Constructor that takes a Store object. |
Method Summary | |
---|---|
void |
addConnectionListener(ConnectionListener l)
Add a listener for Connection events on this Folder. |
void |
addFolderListener(FolderListener l)
Add a listener for Folder events on this Folder. |
void |
addMessageChangedListener(MessageChangedListener l)
Add a listener for 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. |
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. |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
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
Constructor Detail |
---|
protected Folder(Store store)
store
- the Store that holds this folderMethod Detail |
---|
public 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
URLName
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
public 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 pattern
FolderNotFoundException
- if this folder does
not exist.
MessagingException
listSubscribed(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 pattern
FolderNotFoundException
- if this folder does
not exist.
MessagingException
list(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
list(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
listSubscribed(java.lang.String)
public abstract char getSeparator() throws MessagingException
FolderNotFoundException
- if the implementation
requires the folder to exist, but it does not
MessagingException
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
HOLDS_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 unsubscribe
FolderNotFoundException
- if this folder does
not exist.
MethodNotSupportedException
- if this store
does not support subscription
MessagingException
public 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
public 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 Folder
MessagingException
public 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:
FolderNotFoundException
- if this folder does
not exist
IllegalStateException
- if this folder is not in
the closed state.
MessagingException
FolderEvent
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 Folder
FolderNotFoundException
- if this folder does
not exist
IllegalStateException
- if this folder is not in
the closed state.
MessagingException
FolderEvent
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_WRITE
FolderNotFoundException
- if this folder does
not exist.
IllegalStateException
- if this folder is not in
the closed state.
MessagingException
READ_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 true
IllegalStateException
- if this folder is not opened
MessagingException
ConnectionEvent
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.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
public 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
public 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
public 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
public 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 number
FolderNotFoundException
- if this folder does
not exist.
IllegalStateException
- if this folder is not opened
IndexOutOfBoundsException
- if the message number
is out of range.
MessagingException
getMessageCount()
,
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 message
FolderNotFoundException
- 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
fetch(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 numbers
FolderNotFoundException
- 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
fetch(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
fetch(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 appended
FolderNotFoundException
- 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 FetchProfile
IllegalStateException
- if this folder is not opened
MessagingException.
MessagingException
public 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 value
IllegalStateException
- if this folder is not opened
or if it has been opened READ_ONLY.
MessagingException
Message.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 value
IllegalStateException
- 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
Message.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 value
IllegalStateException
- 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
Message.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 to
FolderNotFoundException
- if the destination
folder does not exist.
IllegalStateException
- if this folder is not opened.
MessagingException
appendMessages(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
exist
IllegalStateException
- if this folder is not opened.
MessagingException
Message.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 criterion
SearchException
- 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
SearchTerm
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 searched
SearchException
- if the search
term is too complex for the implementation to handle.
IllegalStateException
- if this folder is not opened
MessagingException
SearchTerm
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.
protected 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.
public 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.
protected void finalize() throws Throwable
finalize
in class Object
Throwable
public String toString()
toString
in class Object
|
Java EE 5 SDK | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.