javax.mail

Class Folder


public abstract class Folder
extends java.lang.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 int
HOLDS_FOLDERS
Flag that indicates that a folder can contain other folders.
static int
HOLDS_MESSAGES
Flag that indicates that a folder can contain messages.
static int
READ_ONLY
Flag indicating that this folder cannot be modified.
static int
READ_WRITE
Flag indictaing that this folder can be modified.
protected int
mode
The current mode of this folder.
protected Store
store
The store that this folder is part of.

Constructor Summary

Folder(Store store)
Constructor that initializes the Store.

Method Summary

void
addConnectionListener(ConnectionListener listener)
void
addFolderListener(FolderListener listener)
void
addMessageChangedListener(MessageChangedListener listener)
void
addMessageCountListener(MessageCountListener listener)
abstract void
appendMessages(Message[] messages)
Append the supplied messages to this folder.
abstract void
close(boolean expunge)
Close this folder; it must already be open.
void
copyMessages(Message[] messages, Folder folder)
Copy the specified messages to another folder.
abstract boolean
create(int type)
Create a new folder capable of containing subfoldera and/or messages as determined by the type parameter.
abstract boolean
delete(boolean recurse)
Delete this folder and possibly any subfolders.
abstract boolean
exists()
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.
void
fetch(Message[] messages, FetchProfile profile)
Hint to the store to prefetch information on the supplied messaged.
protected void
finalize()
Unregisters all listeners.
int
getDeletedMessageCount()
Return the numbew of messages in this folder that have the Flag.DELETED flag set.
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.
abstract String
getFullName()
Return the full absolute name of this folder.
abstract Message
getMessage(int index)
Retrieve the message with the specified index in this Folder; messages indices start at 1 not zero.
abstract int
getMessageCount()
Return the number of messages this folder contains.
Message[]
getMessages()
Retrieve all messages.
Message[]
getMessages(ids[] )
Retrieve messages with the specified indices.
Message[]
getMessages(int start, int end)
Retrieve messages with index between start and end inclusive
int
getMode()
Return the mode of this folder ass passed to open(int), or -1 if the folder is closed.
abstract String
getName()
Return the name of this folder.
int
getNewMessageCount()
Return the numbew of messages in this folder that have the Flag.RECENT flag set.
abstract Folder
getParent()
Return the parent for this folder; if the folder is at the root of a heirarchy this returns null.
abstract Flags
getPermanentFlags()
Get the flags supported by this folder.
abstract char
getSeparator()
Return the character used by this folder's Store to separate path components.
Store
getStore()
Return the store that this folder is part of.
abstract int
getType()
Return the type of this folder, indicating whether it can contain subfolders, messages, or both.
URLName
getURLName()
Return the URLName for this folder, which includes the location of the store.
int
getUnreadMessageCount()
Return the numbew of messages in this folder that do not have the Flag.SEEN flag set.
abstract boolean
hasNewMessages()
Check to see if this Folder conatins messages with the Flag.RECENT flag set.
abstract boolean
isOpen()
Indicates that the folder has been opened.
boolean
isSubscribed()
Determine if the user is subscribed to this Folder.
Folder[]
list()
Convenience method that invokes list(String) with the pattern "%".
abstract Folder[]
list(String pattern)
Return a list of folders from this Folder's namespace that match the supplied pattern.
Folder[]
listSubscribed()
Convenience method that invokes listSubscribed(String) with the pattern "%".
Folder[]
listSubscribed(String pattern)
Return a list of folders to which the user is subscribed and which match the supplied pattern.
protected void
notifyConnectionListeners(int type)
protected void
notifyFolderListeners(int type)
protected void
notifyFolderRenamedListeners(Folder newFolder)
protected void
notifyMessageAddedListeners(Message[] messages)
protected void
notifyMessageChangedListeners(int type, Message message)
protected void
notifyMessageRemovedListeners(boolean removed, Message[] messages)
abstract void
open(int mode)
Open this folder; the folder must be able to contain messages and must currently be closed.
void
removeConnectionListener(ConnectionListener listener)
void
removeFolderListener(FolderListener listener)
void
removeMessageChangedListener(MessageChangedListener listener)
void
removeMessageCountListener(MessageCountListener listener)
abstract boolean
renameTo(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.
void
setFlags(ids[] , Flags flags, boolean value)
Set flags on a set of messages to the supplied value.
void
setFlags(int start, int end, Flags flags, boolean value)
Set flags on a range of messages to the supplied value.
void
setFlags(Message[] messages, Flags flags, boolean value)
Set flags on the messages to the supplied value; all messages must belong to this folder.
void
setSubscribed(boolean subscribed)
Set the user's subscription to this folder.
String
toString()
Returns the full name of this folder; if null, returns the value from the superclass.

Field Details

HOLDS_FOLDERS

public static final int HOLDS_FOLDERS
Flag that indicates that a folder can contain other folders.
Field Value:
2

HOLDS_MESSAGES

public static final int HOLDS_MESSAGES
Flag that indicates that a folder can contain messages.
Field Value:
1

READ_ONLY

public static final int READ_ONLY
Flag indicating that this folder cannot be modified.
Field Value:
1

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?
Field Value:
2

mode

protected int mode

store

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

Constructor Details

Folder

protected Folder(Store store)
Constructor that initializes the Store.
Parameters:
store - the store that this folder is part of

Method Details

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)
            throws MessagingException
Append the supplied messages to this folder. A MessageCountEvent is sent to all listeners registered with this folder when all messages have been appended. If the array contains a previously expunged message, it must be re-appended to the Store and implementations must not abort this operation.
Parameters:
messages - the messages to append
Throws:
MessagingException - if there was a problem accessing the store

close

public abstract void close(boolean expunge)
            throws MessagingException
Close this folder; it must already be open. A ConnectionEvent.CLOSED event is sent to all listeners registered with this folder.
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)
            throws MessagingException
Copy the specified messages to another folder. The default implementation simply appends the supplied messages to the target folder using appendMessages(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)
            throws MessagingException
Create a new folder capable of containing subfoldera and/or messages as determined by the type parameter. Any hierarchy defined by the folder name will be recursively created. If the folder was sucessfully created, a CREATED FolderEvent is sent to all FolderListeners registered with this Folder or with the Store.
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)
            throws MessagingException
Delete this folder and possibly any subfolders. This operation can only be performed on a closed folder. If recurse is true, then all subfolders are deleted first, then any messages in this folder are removed and it is finally deleted; FolderEvent.DELETED events are sent as appropriate. If recurse is false, then the behaviour depends on the folder type and store implementation as followd:
  • If the folder can only conrain messages, then all messages are removed and then the folder is deleted; a FolderEvent.DELETED event is sent.
  • If the folder can onlu contain subfolders, then if it is empty it will be deleted and a FolderEvent.DELETED event is sent; if the folder is not empty then the delete fails and this method returns false.
  • If the folder can contain both subfolders and messages, then if the folder does not contain any subfolders, any messages are deleted, the folder itself is deleted and a FolderEvent.DELETED event is sent; if the folder does contain subfolders then the implementation may choose from the following three behaviors:
    1. it may return false indicting the operation failed
    2. it may remove all messages within the folder, send a FolderEvent.DELETED event, and then return true to indicate the delete was performed. Note this does not delete the folder itself and the exists() operation for this folder will return true
    3. it may remove all messages within the folder as per the previous option; in addition it may change the type of the Folder to only HOLDS_FOLDERS indictaing that messages may no longer be added
    FolderEvents are sent to all listeners registered with this folder or with the Store.
    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()
                throws MessagingException
    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()
                throws MessagingException
    Permanently delete all supplied messages that have the DELETED flag set from the Store. The original message indices of all messages actually deleted are returned and a MessageCountEvent event is sent to all listeners with this folder. The expunge may cause the indices of all messaged that remain in the folder to change.
    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)
                throws MessagingException
    Hint to the store to prefetch information on the supplied messaged. Subclasses should override this method to provide an efficient implementation; the default implementation in this class simply returns.
    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()
                throws Throwable
    Unregisters all listeners.

    getDeletedMessageCount

    public int getDeletedMessageCount()
                throws MessagingException
    Return the numbew of messages in this folder that have the Flag.DELETED flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation.
    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)
                throws MessagingException
    Get the Folder determined by the supplied name; if the name is relative then it is interpreted relative to this folder. This does not check that the named folder actually exists.
    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)
                throws MessagingException
    Retrieve the message with the specified index in this Folder; messages indices start at 1 not zero. Clients should note that the index for a specific message may change if the folder is expunged; Message objects should be used as references instead.
    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()
                throws MessagingException
    Return the number of messages this folder contains. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder.
    Returns:
    the number of messages, or -1 if unknown
    Throws:
    MessagingException - if there was a problem accessing the store

    getMessages

    public Message[] getMessages()
                throws MessagingException
    Retrieve all messages.
    Returns:
    all messages in this folder
    Throws:
    MessagingException - if there was a problem accessing the store

    getMessages

    public Message[] getMessages(ids[] )
                throws MessagingException
    Retrieve messages with the specified indices.
    Parameters:
    Returns:
    the specified messages
    Throws:
    MessagingException - if there was a problem accessing the store

    getMessages

    public Message[] getMessages(int start,
                                 int end)
                throws MessagingException
    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

    getMode

    public int getMode()
    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()
                throws MessagingException
    Return the numbew of messages in this folder that have the Flag.RECENT flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation.
    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()
                throws MessagingException
    Return the parent for this folder; if the folder is at the root of a heirarchy this returns null. This can be invoked when the folder is closed.
    Returns:
    this folder's parent

    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()
                throws MessagingException
    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()
                throws MessagingException
    Return the type of this folder, indicating whether it can contain subfolders, messages, or both. The value returned is a bitmask with the appropriate bits set.
    Returns:
    the type of this folder
    Throws:
    MessagingException - if there was a problem accessing the store

    getURLName

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

    getUnreadMessageCount

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

    hasNewMessages

    public abstract boolean hasNewMessages()
                throws MessagingException
    Check to see if this Folder conatins messages with the Flag.RECENT flag set. This can be used when the folder is closed to perform a light-weight check for new mail; to perform an incremental check for new mail the folder must be opened.
    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 Folder[] list()
                throws MessagingException
    Convenience method that invokes list(String) with the pattern "%".
    Returns:
    a, possibly empty, array of subfolders
    Throws:
    MessagingException - if there was a problem accessing the store

    list

    public abstract Folder[] list(String pattern)
                throws MessagingException
    Return a list of folders from this Folder's namespace that match the supplied pattern. Patterns may contain the following wildcards:
    • '%' which matches any characater except hierarchy delimiters
    • '*' which matches any character including hierarchy delimiters
    This can be invoked when the folder is closed.
    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

    listSubscribed

    public Folder[] listSubscribed()
                throws MessagingException
    Convenience method that invokes listSubscribed(String) with the pattern "%".
    Returns:
    a, possibly empty, array of subscribed subfolders
    Throws:
    MessagingException - if there was a problem accessing the store

    listSubscribed

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

    notifyConnectionListeners

    protected void notifyConnectionListeners(int type)

    notifyFolderListeners

    protected void notifyFolderListeners(int type)

    notifyFolderRenamedListeners

    protected void notifyFolderRenamedListeners(Folder newFolder)

    notifyMessageAddedListeners

    protected void notifyMessageAddedListeners(Message[] messages)

    notifyMessageChangedListeners

    protected void notifyMessageChangedListeners(int type,
                                                 Message message)

    notifyMessageRemovedListeners

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

    open

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

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

    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)
                throws MessagingException
    Rename this folder; the folder must be closed. If the rename is successfull, a FolderEvent.RENAMED event is sent to all listeners registered with this folder or with the store.
    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)
                throws MessagingException
    Search this folder for messages matching the supplied search criteria. The default implementation simply invoke search(term, getMessages()) applying the search over all messages in the folder; subclasses may provide a more efficient mechanism.
    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)
                throws MessagingException
    Search the supplied messages for those that match the supplied criteria; messages must belong to this folder. The default implementation iterates through the messages, returning those whose Message.match(SearchTerm) method returns true; subclasses may provide a more efficient implementation.
    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(ids[] ,
                         Flags flags,
                         boolean value)
                throws MessagingException
    Set flags on a set of messages to the supplied value. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply gets each message and then calls Message.setFlags(Flags,boolean).
    Parameters:
    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 start,
                         int end,
                         Flags flags,
                         boolean value)
                throws MessagingException
    Set flags on a range of messages to the supplied value. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply gets each message and then calls Message.setFlags(Flags,boolean).
    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(Message[] messages,
                         Flags flags,
                         boolean value)
                throws MessagingException
    Set flags on the messages to the supplied value; all messages must belong to this folder. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply calls Message.setFlags(Flags,boolean) for each supplied messages.
    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

    setSubscribed

    public void setSubscribed(boolean subscribed)
                throws MessagingException
    Set the user's subscription to this folder. Not all Stores support subscription; the default implementation in this class always throws a MethodNotSupportedException
    Parameters:
    subscribed - whether to subscribe to this Folder
    Throws:
    MessagingException - if there was a problem accessing the store

    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