javax.mail

Class Folder

public abstract class Folder extends Object

An abstract representation of a folder in a mail system; subclasses would implement Folders for each supported protocol.

Depending on protocol and implementation, folders may contain other folders, messages, or both as indicated by the HOLDS_FOLDERS and HOLDS_MESSAGES flags. If the immplementation supports hierarchical folders, the format of folder names is implementation dependent; however, components of the name are separated by the delimiter character returned by getSeparator.

The case-insensitive folder name "INBOX" is reserved to refer to the primary folder for the current user on the current server; not all stores will provide an INBOX and it may not be available at all times.

Field Summary
static intHOLDS_FOLDERS
Flag that indicates that a folder can contain other folders.
static intHOLDS_MESSAGES
Flag that indicates that a folder can contain messages.
protected intmode
The current mode of this folder.
static intREAD_ONLY
Flag indicating that this folder cannot be modified.
static intREAD_WRITE
Flag indictaing that this folder can be modified.
protected Storestore
The store that this folder is part of.
Constructor Summary
protected Folder(Store store)
Constructor that initializes the Store.
Method Summary
voidaddConnectionListener(ConnectionListener listener)
voidaddFolderListener(FolderListener listener)
voidaddMessageChangedListener(MessageChangedListener listener)
voidaddMessageCountListener(MessageCountListener listener)
abstract voidappendMessages(Message[] messages)
Append the supplied messages to this folder.
abstract voidclose(boolean expunge)
Close this folder; it must already be open.
voidcopyMessages(Message[] messages, Folder folder)
Copy the specified messages to another folder.
abstract booleancreate(int type)
Create a new folder capable of containing subfoldera and/or messages as determined by the type parameter.
abstract booleandelete(boolean recurse)
Delete this folder and possibly any subfolders.
abstract booleanexists()
Check to see if this folder physically exists in the store.
abstract Message[]expunge()
Permanently delete all supplied messages that have the DELETED flag set from the Store.
voidfetch(Message[] messages, FetchProfile profile)
Hint to the store to prefetch information on the supplied messaged.
protected voidfinalize()
Unregisters all listeners.
intgetDeletedMessageCount()
Return the numbew of messages in this folder that have the Flag.DELETED flag set.
abstract FoldergetFolder(String name)
Get the Folder determined by the supplied name; if the name is relative then it is interpreted relative to this folder.
abstract StringgetFullName()
Return the full absolute name of this folder.
abstract MessagegetMessage(int index)
Retrieve the message with the specified index in this Folder; messages indices start at 1 not zero.
abstract intgetMessageCount()
Return the number of messages this folder contains.
Message[]getMessages(int start, int end)
Retrieve messages with index between start and end inclusive
Message[]getMessages(int[] ids)
Retrieve messages with the specified indices.
Message[]getMessages()
Retrieve all messages.
intgetMode()
Return the mode of this folder ass passed to Folder, or -1 if the folder is closed.
abstract StringgetName()
Return the name of this folder.
intgetNewMessageCount()
Return the numbew of messages in this folder that have the Flag.RECENT flag set.
abstract FoldergetParent()
Return the parent for this folder; if the folder is at the root of a heirarchy this returns null.
abstract FlagsgetPermanentFlags()
Get the flags supported by this folder.
abstract chargetSeparator()
Return the character used by this folder's Store to separate path components.
StoregetStore()
Return the store that this folder is part of.
abstract intgetType()
Return the type of this folder, indicating whether it can contain subfolders, messages, or both.
intgetUnreadMessageCount()
Return the numbew of messages in this folder that do not have the Flag.SEEN flag set.
URLNamegetURLName()
Return the URLName for this folder, which includes the location of the store.
abstract booleanhasNewMessages()
Check to see if this Folder conatins messages with the Flag.RECENT flag set.
abstract booleanisOpen()
Indicates that the folder has been opened.
booleanisSubscribed()
Determine if the user is subscribed to this Folder.
abstract Folder[]list(String pattern)
Return a list of folders from this Folder's namespace that match the supplied pattern.
Folder[]list()
Convenience method that invokes list with the pattern "%".
Folder[]listSubscribed(String pattern)
Return a list of folders to which the user is subscribed and which match the supplied pattern.
Folder[]listSubscribed()
Convenience method that invokes listSubscribed with the pattern "%".
protected voidnotifyConnectionListeners(int type)
protected voidnotifyFolderListeners(int type)
protected voidnotifyFolderRenamedListeners(Folder newFolder)
protected voidnotifyMessageAddedListeners(Message[] messages)
protected voidnotifyMessageChangedListeners(int type, Message message)
protected voidnotifyMessageRemovedListeners(boolean removed, Message[] messages)
abstract voidopen(int mode)
Open this folder; the folder must be able to contain messages and must currently be closed.
voidremoveConnectionListener(ConnectionListener listener)
voidremoveFolderListener(FolderListener listener)
voidremoveMessageChangedListener(MessageChangedListener listener)
voidremoveMessageCountListener(MessageCountListener listener)
abstract booleanrenameTo(Folder newName)
Rename this folder; the folder must be closed.
Message[]search(SearchTerm term)
Search this folder for messages matching the supplied search criteria.
Message[]search(SearchTerm term, Message[] messages)
Search the supplied messages for those that match the supplied criteria; messages must belong to this folder.
voidsetFlags(Message[] messages, Flags flags, boolean value)
Set flags on the messages to the supplied value; all messages must belong to this folder.
voidsetFlags(int start, int end, Flags flags, boolean value)
Set flags on a range of messages to the supplied value.
voidsetFlags(int[] ids, Flags flags, boolean value)
Set flags on a set of messages to the supplied value.
voidsetSubscribed(boolean subscribed)
Set the user's subscription to this folder.
StringtoString()
Returns the full name of this folder; if null, returns the value from the superclass.

Field Detail

HOLDS_FOLDERS

public static final int HOLDS_FOLDERS
Flag that indicates that a folder can contain other folders.

HOLDS_MESSAGES

public static final int HOLDS_MESSAGES
Flag that indicates that a folder can contain messages.

mode

protected int mode
The current mode of this folder. When open, this can be READ_ONLY or READ_WRITE; otherwise is set to -1.

READ_ONLY

public static final int READ_ONLY
Flag indicating that this folder cannot be modified.

READ_WRITE

public static final int READ_WRITE
Flag indictaing that this folder can be modified. Question: what does it mean if both are set?

store

protected Store store
The store that this folder is part of.

Constructor Detail

Folder

protected Folder(Store store)
Constructor that initializes the Store.

Parameters: store the store that this folder is part of

Method Detail

addConnectionListener

public void addConnectionListener(ConnectionListener listener)

addFolderListener

public void addFolderListener(FolderListener listener)

addMessageChangedListener

public void addMessageChangedListener(MessageChangedListener listener)

addMessageCountListener

public void addMessageCountListener(MessageCountListener listener)

appendMessages

public abstract void appendMessages(Message[] messages)
Append the supplied messages to this folder. A MessageCountEvent is sent to all listeners registered with this folder when all messages have been appended. If the array contains a previously expunged message, it must be re-appended to the Store and implementations must not abort this operation.

Parameters: messages the messages to append

Throws: MessagingException if there was a problem accessing the store

close

public abstract void close(boolean expunge)
Close this folder; it must already be open. A CLOSED event is sent to all listeners registered with this folder.

Parameters: expunge whether to expunge all deleted messages

Throws: MessagingException if there was a problem accessing the store; the folder is still closed

copyMessages

public void copyMessages(Message[] messages, Folder folder)
Copy the specified messages to another folder. The default implementation simply appends the supplied messages to the target folder using (Message[]).

Parameters: messages the messages to copy folder the folder to copy to

Throws: MessagingException if there was a problem accessing the store

create

public abstract boolean create(int type)
Create a new folder capable of containing subfoldera and/or messages as determined by the type parameter. Any hierarchy defined by the folder name will be recursively created. If the folder was sucessfully created, a CREATED FolderEvent is sent to all FolderListeners registered with this Folder or with the Store.

Parameters: type the type, indicating if this folder should contain subfolders, messages or both

Returns: true if the folder was sucessfully created

Throws: MessagingException if there was a problem accessing the store

delete

public abstract boolean delete(boolean recurse)
Delete this folder and possibly any subfolders. This operation can only be performed on a closed folder. If recurse is true, then all subfolders are deleted first, then any messages in this folder are removed and it is finally deleted; DELETED events are sent as appropriate. If recurse is false, then the behaviour depends on the folder type and store implementation as followd: FolderEvents are sent to all listeners registered with this folder or with the Store.

Parameters: recurse whether subfolders should be recursively deleted as well

Returns: true if the delete operation succeeds

Throws: MessagingException if there was a problem accessing the store

exists

public abstract boolean exists()
Check to see if this folder physically exists in the store. This can be invoked when the folder is closed.

Returns: true if the folder really exists

Throws: MessagingException if there was a problem accessing the store

expunge

public abstract Message[] expunge()
Permanently delete all supplied messages that have the DELETED flag set from the Store. The original message indices of all messages actually deleted are returned and a MessageCountEvent event is sent to all listeners with this folder. The expunge may cause the indices of all messaged that remain in the folder to change.

Returns: the original indices of messages that were actually deleted

Throws: MessagingException if there was a problem accessing the store

fetch

public void fetch(Message[] messages, FetchProfile profile)
Hint to the store to prefetch information on the supplied messaged. Subclasses should override this method to provide an efficient implementation; the default implementation in this class simply returns.

Parameters: messages messages for which information should be fetched profile the information to fetch

Throws: MessagingException if there was a problem accessing the store

See Also: FetchProfile

finalize

protected void finalize()
Unregisters all listeners.

getDeletedMessageCount

public int getDeletedMessageCount()
Return the numbew of messages in this folder that have the Flag.DELETED flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation.

Returns: the number of new messages, or -1 if unknown

Throws: MessagingException if there was a problem accessing the store

getFolder

public abstract Folder getFolder(String name)
Get the Folder determined by the supplied name; if the name is relative then it is interpreted relative to this folder. This does not check that the named folder actually exists.

Parameters: name the name of the folder to return

Returns: the named folder

Throws: MessagingException if there was a problem accessing the store

getFullName

public abstract String getFullName()
Return the full absolute name of this folder. This can be invoked when the folder is closed.

Returns: the full name of this folder

getMessage

public abstract Message getMessage(int index)
Retrieve the message with the specified index in this Folder; messages indices start at 1 not zero. Clients should note that the index for a specific message may change if the folder is expunged; Message objects should be used as references instead.

Parameters: index the index of the message to fetch

Returns: the message

Throws: MessagingException if there was a problem accessing the store

getMessageCount

public abstract int getMessageCount()
Return the number of messages this folder contains. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder.

Returns: the number of messages, or -1 if unknown

Throws: MessagingException if there was a problem accessing the store

getMessages

public Message[] getMessages(int start, int end)
Retrieve messages with index between start and end inclusive

Parameters: start index of first message end index of last message

Returns: an array of messages from start to end inclusive

Throws: MessagingException if there was a problem accessing the store

getMessages

public Message[] getMessages(int[] ids)
Retrieve messages with the specified indices.

Parameters: ids the indices of the messages to fetch

Returns: the specified messages

Throws: MessagingException if there was a problem accessing the store

getMessages

public Message[] getMessages()
Retrieve all messages.

Returns: all messages in this folder

Throws: MessagingException if there was a problem accessing the store

getMode

public int getMode()
Return the mode of this folder ass passed to Folder, or -1 if the folder is closed.

Returns: the mode this folder was opened with

getName

public abstract String getName()
Return the name of this folder. This can be invoked when the folder is closed.

Returns: this folder's name

getNewMessageCount

public int getNewMessageCount()
Return the numbew of messages in this folder that have the Flag.RECENT flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation.

Returns: the number of new messages, or -1 if unknown

Throws: MessagingException if there was a problem accessing the store

getParent

public abstract Folder getParent()
Return the parent for this folder; if the folder is at the root of a heirarchy this returns null. This can be invoked when the folder is closed.

Returns: this folder's parent

Throws: MessagingException

getPermanentFlags

public abstract Flags getPermanentFlags()
Get the flags supported by this folder.

Returns: the flags supported by this folder, or null if unknown

See Also: Flags

getSeparator

public abstract char getSeparator()
Return the character used by this folder's Store to separate path components.

Returns: the name separater character

Throws: MessagingException if there was a problem accessing the store

getStore

public Store getStore()
Return the store that this folder is part of.

Returns: the store this folder is part of

getType

public abstract int getType()
Return the type of this folder, indicating whether it can contain subfolders, messages, or both. The value returned is a bitmask with the appropriate bits set.

Returns: the type of this folder

Throws: MessagingException if there was a problem accessing the store

See Also: HOLDS_FOLDERS HOLDS_MESSAGES

getUnreadMessageCount

public int getUnreadMessageCount()
Return the numbew of messages in this folder that do not have the Flag.SEEN flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation.

Returns: the number of new messages, or -1 if unknown

Throws: MessagingException if there was a problem accessing the store

getURLName

public URLName getURLName()
Return the URLName for this folder, which includes the location of the store.

Returns: the URLName for this folder

Throws: MessagingException

hasNewMessages

public abstract boolean hasNewMessages()
Check to see if this Folder conatins messages with the Flag.RECENT flag set. This can be used when the folder is closed to perform a light-weight check for new mail; to perform an incremental check for new mail the folder must be opened.

Returns: true if the Store has recent messages

Throws: MessagingException if there was a problem accessing the store

isOpen

public abstract boolean isOpen()
Indicates that the folder has been opened.

Returns: true if the folder is open

isSubscribed

public boolean isSubscribed()
Determine if the user is subscribed to this Folder. The default implementation in this class always returns true.

Returns: true is the user is subscribed to this Folder

list

public abstract Folder[] list(String pattern)
Return a list of folders from this Folder's namespace that match the supplied pattern. Patterns may contain the following wildcards: This can be invoked when the folder is closed.

Parameters: pattern the pattern to search for

Returns: a, possibly empty, array containing Folders that matched the pattern

Throws: MessagingException if there was a problem accessing the store

list

public Folder[] list()
Convenience method that invokes list with the pattern "%".

Returns: a, possibly empty, array of subfolders

Throws: MessagingException if there was a problem accessing the store

listSubscribed

public Folder[] listSubscribed(String pattern)
Return a list of folders to which the user is subscribed and which match the supplied pattern. If the store does not support the concept of subscription then this should match against all folders; the default implementation of this method achieves this by defaulting to the list method.

Parameters: pattern the pattern to search for

Returns: a, possibly empty, array containing subscribed Folders that matched the pattern

Throws: MessagingException if there was a problem accessing the store

listSubscribed

public Folder[] listSubscribed()
Convenience method that invokes listSubscribed with the pattern "%".

Returns: a, possibly empty, array of subscribed subfolders

Throws: MessagingException if there was a problem accessing the store

notifyConnectionListeners

protected void notifyConnectionListeners(int type)

notifyFolderListeners

protected void notifyFolderListeners(int type)

notifyFolderRenamedListeners

protected void notifyFolderRenamedListeners(Folder newFolder)

notifyMessageAddedListeners

protected void notifyMessageAddedListeners(Message[] messages)

notifyMessageChangedListeners

protected void notifyMessageChangedListeners(int type, Message message)

notifyMessageRemovedListeners

protected void notifyMessageRemovedListeners(boolean removed, Message[] messages)

open

public abstract void open(int mode)
Open this folder; the folder must be able to contain messages and must currently be closed. If the folder is opened successfully then a OPENED event is sent to listeners registered with this Folder.

Whether the Store allows multiple connections or if it allows multiple writers is implementation defined.

Parameters: mode READ_ONLY or READ_WRITE

Throws: MessagingException if there was a problem accessing the store

removeConnectionListener

public void removeConnectionListener(ConnectionListener listener)

removeFolderListener

public void removeFolderListener(FolderListener listener)

removeMessageChangedListener

public void removeMessageChangedListener(MessageChangedListener listener)

removeMessageCountListener

public void removeMessageCountListener(MessageCountListener listener)

renameTo

public abstract boolean renameTo(Folder newName)
Rename this folder; the folder must be closed. If the rename is successfull, a RENAMED event is sent to all listeners registered with this folder or with the store.

Parameters: newName the new name for this folder

Returns: true if the rename succeeded

Throws: MessagingException if there was a problem accessing the store

search

public Message[] search(SearchTerm term)
Search this folder for messages matching the supplied search criteria. The default implementation simply invoke search(term, getMessages()) applying the search over all messages in the folder; subclasses may provide a more efficient mechanism.

Parameters: term the search criteria

Returns: an array containing messages that match the criteria

Throws: MessagingException if there was a problem accessing the store

search

public Message[] search(SearchTerm term, Message[] messages)
Search the supplied messages for those that match the supplied criteria; messages must belong to this folder. The default implementation iterates through the messages, returning those whose match method returns true; subclasses may provide a more efficient implementation.

Parameters: term the search criteria messages the messages to search

Returns: an array containing messages that match the criteria

Throws: MessagingException if there was a problem accessing the store

setFlags

public void setFlags(Message[] messages, Flags flags, boolean value)
Set flags on the messages to the supplied value; all messages must belong to this folder. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply calls Message for each supplied messages.

Parameters: messages whose flags should be set flags the set of flags to modify value the value the flags should be set to

Throws: MessagingException if there was a problem accessing the store

setFlags

public void setFlags(int start, int end, Flags flags, boolean value)
Set flags on a range of messages to the supplied value. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply gets each message and then calls Message.

Parameters: start first message end set end last message end set flags the set of flags end modify value the value the flags should be set end

Throws: MessagingException if there was a problem accessing the store

setFlags

public void setFlags(int[] ids, Flags flags, boolean value)
Set flags on a set of messages to the supplied value. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply gets each message and then calls Message.

Parameters: ids the indexes of the messages to set flags the set of flags end modify value the value the flags should be set end

Throws: MessagingException if there was a problem accessing the store

setSubscribed

public void setSubscribed(boolean subscribed)
Set the user's subscription to this folder. Not all Stores support subscription; the default implementation in this class always throws a MethodNotSupportedException

Parameters: subscribed whether to subscribe to this Folder

Throws: MessagingException if there was a problem accessing the store MethodNotSupportedException if the Store does not support subscription

toString

public String toString()
Returns the full name of this folder; if null, returns the value from the superclass.

Returns: a string form of this folder