javax.mail

Class Folder

public abstract class Folder extends Object

A folder is a hierarchical messaging container in a store. Folders may contain Messages, other Folders or both, depending on the implementation.

Folder names are implementation dependent; the hierarchy components in a folder's full name are separated by the folder's ancestors' hierarchy delimiter characters.

The special (case-insensitive) folder name INBOX is reserved to mean the primary folder for the authenticated user in the store. Not all stores support INBOX folders, and not all users will have an INBOX folder.

Unless documented otherwise, a folder must be opened in order to invoke a method on it.

Version: 1.4

Author: Chris Burdess

Field Summary
static intHOLDS_FOLDERS
This folder can contain other folders.
static intHOLDS_MESSAGES
This folder can contain messages.
protected intmode
The folder mode: Folder.READ_ONLY, Folder.READ_WRITE, or -1 if not known.
static intREAD_ONLY
This folder is read only.
static intREAD_WRITE
This folder can be modified.
protected Storestore
The parent store.
Constructor Summary
protected Folder(Store store)
Constructor.
Method Summary
voidaddConnectionListener(ConnectionListener l)
Add a listener for connection events on this folder.
voidaddFolderListener(FolderListener l)
Add a listener for folder events on this folder.
voidaddMessageChangedListener(MessageChangedListener l)
Add a listener for message changed events on this folder.
voidaddMessageCountListener(MessageCountListener l)
Add a listener for message count events on this folder.
abstract voidappendMessages(Message[] msgs)
Appends the specified messages to this folder.
abstract voidclose(boolean expunge)
Closes this folder.
voidcopyMessages(Message[] msgs, Folder folder)
Copies the specified messages into another folder.
abstract booleancreate(int type)
Create this folder in the store.
abstract booleandelete(boolean recurse)
Deletes this folder.
abstract booleanexists()
Indicates whether this folder exists in the Store.
abstract Message[]expunge()
Expunges (permanently removing) all the messages marked DELETED.
voidfetch(Message[] msgs, FetchProfile fp)
Fetches the items specified in the given fetch profile for the specified messages.
intgetDeletedMessageCount()
Returns the number of deleted messages in this folder.
abstract FoldergetFolder(String name)
Return a folder corresponding to the given name.
abstract StringgetFullName()
Returns the full name of this folder.
abstract MessagegetMessage(int msgnum)
Returns the message with the given number.
abstract intgetMessageCount()
Returns the number of messages in this folder.
Message[]getMessages(int start, int end)
Returns the messages in the given range (inclusive).
Message[]getMessages(int[] msgnums)
Returns the messages for the specified message numbers.
Message[]getMessages()
Returns all messages in this folder.
intgetMode()
Return the mode this folder is open in.
abstract StringgetName()
Returns the name of this folder.
intgetNewMessageCount()
Returns the number of new messages in this folder.
abstract FoldergetParent()
Returns the parent folder of this folder, or null if this folder is the root of a folder hierarchy.
abstract FlagsgetPermanentFlags()
Returns the permanent flags supported by this folder.
abstract chargetSeparator()
Return the hierarchy delimiter character for this folder.
StoregetStore()
Returns the parent store.
abstract intgetType()
Returns the type of this Folder, i.e. whether this folder can hold messages or subfolders or both.
intgetUnreadMessageCount()
Returns the number of unread messages in this folder.
URLNamegetURLName()
Return a URLName that can be used as a handle to access this folder.
abstract booleanhasNewMessages()
Indicates whether this folder has new messages.
abstract booleanisOpen()
Indicates whether this folder is open.
booleanisSubscribed()
Indicates whether this folder is subscribed.
abstract Folder[]list(String pattern)
Returns a list of subfolders matching the specified pattern.
Folder[]list()
Returns the list of subfolders of this folder.
Folder[]listSubscribed(String pattern)
Returns a list of subscribed subfolders matching the specified pattern.
Folder[]listSubscribed()
Returns the list of subscribed subfolders of this folder.
protected voidnotifyConnectionListeners(int type)
Notify all connection listeners.
protected voidnotifyFolderListeners(int type)
Notify all folder listeners registered on this Folder and this folder's store.
protected voidnotifyFolderRenamedListeners(Folder folder)
Notify all folder listeners registered on this folder and this folder's store about the renaming of this folder.
protected voidnotifyMessageAddedListeners(Message[] msgs)
Notify all message count listeners about the addition of messages into this folder.
protected voidnotifyMessageChangedListeners(int type, Message msg)
Notify all message changed event listeners.
protected voidnotifyMessageRemovedListeners(boolean removed, Message[] msgs)
Notify all message count listeners about the removal of messages from this folder.
abstract voidopen(int mode)
Opens this folder.
voidremoveConnectionListener(ConnectionListener l)
Remove a connection event listener.
voidremoveFolderListener(FolderListener l)
Remove a folder event listener.
voidremoveMessageChangedListener(MessageChangedListener l)
Remove a message changed event listener.
voidremoveMessageCountListener(MessageCountListener l)
Remove a message count event listener.
abstract booleanrenameTo(Folder folder)
Renames this folder.
Message[]search(SearchTerm term)
Searches this folder for messages matching the specified search term.
Message[]search(SearchTerm term, Message[] msgs)
Searches the given messages for those matching the specified search term.
voidsetFlags(Message[] msgs, Flags flag, boolean value)
Sets the specified flags on each specified message.
voidsetFlags(int start, int end, Flags flag, boolean value)
Set the specified flags on the given range of messages (inclusive).
voidsetFlags(int[] msgnums, Flags flag, boolean value)
Sets the specified flags on each of the specified messages.
voidsetSubscribed(boolean flag)
Subscribe to or unsubscribe from this folder.
StringtoString()
Returns the value of Folder.getFullName(), or, if that is null, returns the default toString().

Field Detail

HOLDS_FOLDERS

public static final int HOLDS_FOLDERS
This folder can contain other folders.

HOLDS_MESSAGES

public static final int HOLDS_MESSAGES
This folder can contain messages.

mode

protected int mode
The folder mode: Folder.READ_ONLY, Folder.READ_WRITE, or -1 if not known.

READ_ONLY

public static final int READ_ONLY
This folder is read only.

READ_WRITE

public static final int READ_WRITE
This folder can be modified.

store

protected Store store
The parent store.

Constructor Detail

Folder

protected Folder(Store store)
Constructor.

Parameters: store the parent store

Method Detail

addConnectionListener

public void addConnectionListener(ConnectionListener l)
Add a listener for connection events on this folder.

addFolderListener

public void addFolderListener(FolderListener l)
Add a listener for folder events on this folder.

addMessageChangedListener

public void addMessageChangedListener(MessageChangedListener l)
Add a listener for message changed events on this folder.

addMessageCountListener

public void addMessageCountListener(MessageCountListener l)
Add a listener for message count events on this folder.

appendMessages

public abstract void appendMessages(Message[] msgs)
Appends the specified messages to this folder.

This method can be invoked on a closed folder.

Parameters: msgs array of messages to be appended

Throws: FolderNotFoundException if this folder does not exist MessagingException if the append operation failed

close

public abstract void close(boolean expunge)
Closes this folder. This method can only be invoked on an open folder.

Parameters: expunge if true, expunge all deleted messages

copyMessages

public void copyMessages(Message[] msgs, Folder folder)
Copies the specified messages into another folder.

The destination folder does not have to be open.

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

create

public abstract boolean create(int type)
Create this folder in the store. When this folder is created, any folders in its path that do not exist are also created.

If the creation is successful, a CREATED FolderEvent is delivered to any FolderListeners registered on this Folder and this Store.

Parameters: type the desired type of the folder

delete

public abstract boolean delete(boolean recurse)
Deletes this folder. This method can only be invoked on a closed folder.

Parameters: recurse delete any subfolders

Returns: true if the folder is deleted successfully, false otherwise

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is not closed

exists

public abstract boolean exists()
Indicates whether this folder exists in the Store.

This method can be invoked on a closed folder.

expunge

public abstract Message[] expunge()
Expunges (permanently removing) all the messages marked DELETED. Returns an array containing the expunged messages.

Expunge causes the renumbering of any messages with numbers higher than the message number of the lowest-numbered expunged message.

After a message has been expunged, only the isExpunged and getMessageNumber methods are still valid on the corresponding Message object; other methods may throw MessageRemovedException.

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed

fetch

public void fetch(Message[] msgs, FetchProfile fp)
Fetches the items specified in the given fetch profile for the specified messages.

Parameters: msgs the messages to fetch the items for fp the fetch profile

getDeletedMessageCount

public int getDeletedMessageCount()
Returns the number of deleted messages in this folder.

This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

Throws: FolderNotFoundException if this folder does not exist

Since: JavaMail 1.3

getFolder

public abstract Folder getFolder(String name)
Return a folder corresponding to the given name. Note that the folder does not have to exist in 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.

This method can be invoked on a closed folder.

Parameters: name the name of the folder

getFullName

public abstract String getFullName()
Returns the full name of this folder. If the folder resides under the root hierarchy of its store, the returned name is relative to the root. Otherwise an absolute name, starting with the hierarchy delimiter, is returned.

This method can be invoked on a closed folder.

getMessage

public abstract Message getMessage(int msgnum)
Returns the message with the given number. The message number is the relative position of a message in its folder, starting at 1.

Note that message numbers can change within a session if the folder is expunged, therefore the use of message numbers as references to messages is inadvisable.

Parameters: msgnum the message number

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed IndexOutOfBoundsException if the message number is out of range

getMessageCount

public abstract int getMessageCount()
Returns the number of messages in this folder.

This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

getMessages

public Message[] getMessages(int start, int end)
Returns the messages in the given range (inclusive).

Parameters: start the number of the first message end the number of the last message

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed IndexOutOfBoundsException if the start or end message numbers are out of range.

getMessages

public Message[] getMessages(int[] msgnums)
Returns the messages for the specified message numbers.

Parameters: msgnums the array of message numbers

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed IndexOutOfBoundsException if any message number in the given array is out of range

getMessages

public Message[] getMessages()
Returns all messages in this folder.

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed

getMode

public int getMode()
Return the mode this folder is open in. Returns Folder.READ_ONLY, Folder.READ_WRITE, or -1 if the open mode is not known.

Throws: IllegalStateException if this folder is not open

getName

public abstract String getName()
Returns the name of this folder.

This method can be invoked on a closed folder.

getNewMessageCount

public int getNewMessageCount()
Returns the number of new messages in this folder.

This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

getParent

public abstract Folder getParent()
Returns the parent folder of this folder, or null if this folder is the root of a folder hierarchy.

This method can be invoked on a closed folder.

getPermanentFlags

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

getSeparator

public abstract char getSeparator()
Return the hierarchy delimiter character for this folder. This separates the full name of this folder from the names of subfolders.

This method can be invoked on a closed folder.

getStore

public Store getStore()
Returns the parent store. This method can be invoked on a closed folder.

getType

public abstract int getType()
Returns the type of this Folder, i.e. whether this folder can hold messages or subfolders or both. The returned value is an integer bitfield with the appropriate bits set.

This method can be invoked on a closed folder.

getUnreadMessageCount

public int getUnreadMessageCount()
Returns the number of unread messages in this folder.

This method can be invoked on a closed folder; however, note that for some stores, getting the message count can be an expensive operation involving actually opening the folder. In such cases, a provider can choose to return -1 here when the folder is closed.

getURLName

public URLName getURLName()
Return a URLName that can be used as a handle to access this folder. This will not include the password used to authenticate to the store.

This method can be invoked on a closed folder.

hasNewMessages

public abstract boolean hasNewMessages()
Indicates whether this folder has new messages.

This method can be invoked on a closed folder that can contain messages.

isOpen

public abstract boolean isOpen()
Indicates whether this folder is open.

isSubscribed

public boolean isSubscribed()
Indicates whether this folder is subscribed.

This method can be invoked on a closed folder.

list

public abstract Folder[] list(String pattern)
Returns a list of subfolders matching the specified pattern. Patterns may contain the wildcard characters "%", which matches any character except hierarchy delimiters, and "*", which matches any character.

This method can be invoked on a closed folder.

Parameters: pattern the match pattern

list

public Folder[] list()
Returns the list of subfolders of this folder.

This method can be invoked on a closed folder.

listSubscribed

public Folder[] listSubscribed(String pattern)
Returns a list of subscribed subfolders matching the specified pattern. If the folder does not support subscription, returns the same as the list method. The pattern can contain wildcards.

This method can be invoked on a closed folder.

Parameters: pattern the match pattern

listSubscribed

public Folder[] listSubscribed()
Returns the list of subscribed subfolders of this folder.

This method can be invoked on a closed folder.

notifyConnectionListeners

protected void notifyConnectionListeners(int type)
Notify all connection listeners.

notifyFolderListeners

protected void notifyFolderListeners(int type)
Notify all folder listeners registered on this Folder and this folder's store.

notifyFolderRenamedListeners

protected void notifyFolderRenamedListeners(Folder folder)
Notify all folder listeners registered on this folder and this folder's store about the renaming of this folder.

notifyMessageAddedListeners

protected void notifyMessageAddedListeners(Message[] msgs)
Notify all message count listeners about the addition of messages into this folder.

notifyMessageChangedListeners

protected void notifyMessageChangedListeners(int type, Message msg)
Notify all message changed event listeners.

notifyMessageRemovedListeners

protected void notifyMessageRemovedListeners(boolean removed, Message[] msgs)
Notify all message count listeners about the removal of messages from this folder.

open

public abstract void open(int mode)
Opens this folder. This method can only be invoked on a closed folder that can contain messages.

Parameters: mode open the Folder READ_ONLY or READ_WRITE

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is not closed

removeConnectionListener

public void removeConnectionListener(ConnectionListener l)
Remove a connection event listener.

removeFolderListener

public void removeFolderListener(FolderListener l)
Remove a folder event listener.

removeMessageChangedListener

public void removeMessageChangedListener(MessageChangedListener l)
Remove a message changed event listener.

removeMessageCountListener

public void removeMessageCountListener(MessageCountListener l)
Remove a message count event listener.

renameTo

public abstract boolean renameTo(Folder folder)
Renames this folder. This method can only be invoked on a closed folder.

Parameters: folder a folder representing the new name for this folder

Returns: true if the folder is renamed successfully, false otherwise

Throws: FolderNotFoundException if this folder does not exist IllegalStateException if this folder is not closed

search

public Message[] search(SearchTerm term)
Searches this folder for messages matching the specified search term. Returns the matching messages.

Parameters: term the search term

Throws: SearchException if there was a problem with the search FolderNotFoundException if this folder does not exist IllegalStateException if this folder is closed

search

public Message[] search(SearchTerm term, Message[] msgs)
Searches the given messages for those matching the specified search term. Returns the matching messages.

Parameters: term the search term msgs the messages to be searched

Throws: SearchException if there was a problem with the search IllegalStateException if this folder is closed

setFlags

public void setFlags(Message[] msgs, Flags flag, boolean value)
Sets the specified flags on each specified message.

Parameters: msgnums the messages flag the flags to be set value set the flags to this value

Throws: IllegalStateException if this folder is closed or READ_ONLY

setFlags

public void setFlags(int start, int end, Flags flag, boolean value)
Set the specified flags on the given range of messages (inclusive).

Parameters: start the number of the first message end the number of the last message flag the flags to be set value set the flags to this value

Throws: IllegalStateException if this folder is closed or READ_ONLY IndexOutOfBoundsException if the start or end message numbers are out of range

setFlags

public void setFlags(int[] msgnums, Flags flag, boolean value)
Sets the specified flags on each of the specified messages.

Parameters: msgnums the message numbers flag the flags to be set value set the flags to this value

Throws: IllegalStateException if this folder is closed or READ_ONLY IndexOutOfBoundsException if any message number in the given array is out of range

setSubscribed

public void setSubscribed(boolean flag)
Subscribe to or unsubscribe from this folder. Not all Stores support subscription.

This method can be invoked on a closed folder.

toString

public String toString()
Returns the value of Folder.getFullName(), or, if that is null, returns the default toString().
© Copyright 2003, 2004 The Free Software Foundation, All rights reserved