javax.mail
Class Folder

java.lang.Object
  extended by javax.mail.Folder
Direct Known Subclasses:
IMAPFolder, MaildirFolder, MboxFolder, NNTPFolder, NNTPRootFolder, POP3Folder

public abstract class Folder
extends java.lang.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 int HOLDS_FOLDERS
          This folder can contain other folders.
static int HOLDS_MESSAGES
          This folder can contain messages.
protected  int mode
          The folder mode: Folder.READ_ONLY, Folder.READ_WRITE, or -1 if not known.
static int READ_ONLY
          This folder is read only.
static int READ_WRITE
          This folder can be modified.
protected  Store store
          The parent store.
 
Constructor Summary
protected Folder(Store store)
          Constructor.
 
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 message changed events on this folder.
 void addMessageCountListener(MessageCountListener l)
          Add a listener for message count events on this folder.
abstract  void appendMessages(Message[] msgs)
          Appends the specified messages to this folder.
abstract  void close(boolean expunge)
          Closes this folder.
 void copyMessages(Message[] msgs, Folder folder)
          Copies the specified messages into another folder.
abstract  boolean create(int type)
          Create this folder in the store.
abstract  boolean delete(boolean recurse)
          Deletes this folder.
abstract  boolean exists()
          Indicates whether this folder exists in the Store.
abstract  Message[] expunge()
          Expunges (permanently removing) all the messages marked DELETED.
 void fetch(Message[] msgs, FetchProfile fp)
          Fetches the items specified in the given fetch profile for the specified messages.
 int getDeletedMessageCount()
          Returns the number of deleted messages in this folder.
abstract  Folder getFolder(java.lang.String name)
          Return a folder corresponding to the given name.
abstract  java.lang.String getFullName()
          Returns the full name of this folder.
abstract  Message getMessage(int msgnum)
          Returns the message with the given number.
abstract  int getMessageCount()
          Returns the number of messages in this folder.
 Message[] getMessages()
          Returns all messages in this folder.
 Message[] getMessages(int[] msgnums)
          Returns the messages for the specified message numbers.
 Message[] getMessages(int start, int end)
          Returns the messages in the given range (inclusive).
 int getMode()
          Return the mode this folder is open in.
abstract  java.lang.String getName()
          Returns the name of this folder.
 int getNewMessageCount()
          Returns the number of new messages in this folder.
abstract  Folder getParent()
          Returns the parent folder of this folder, or null if this folder is the root of a folder hierarchy.
abstract  Flags getPermanentFlags()
          Returns the permanent flags supported by this folder.
abstract  char getSeparator()
          Return the hierarchy delimiter character for this folder.
 Store getStore()
          Returns the parent store.
abstract  int getType()
          Returns the type of this Folder, i.e.
 int getUnreadMessageCount()
          Returns the number of unread messages in this folder.
 URLName getURLName()
          Return a URLName that can be used as a handle to access this folder.
abstract  boolean hasNewMessages()
          Indicates whether this folder has new messages.
abstract  boolean isOpen()
          Indicates whether this folder is open.
 boolean isSubscribed()
          Indicates whether this folder is subscribed.
 Folder[] list()
          Returns the list of subfolders of this folder.
abstract  Folder[] list(java.lang.String pattern)
          Returns a list of subfolders matching the specified pattern.
 Folder[] listSubscribed()
          Returns the list of subscribed subfolders of this folder.
 Folder[] listSubscribed(java.lang.String pattern)
          Returns a list of subscribed subfolders matching the specified pattern.
protected  void notifyConnectionListeners(int type)
          Notify all connection listeners.
protected  void notifyFolderListeners(int type)
          Notify all folder listeners registered on this Folder and this folder's store.
protected  void notifyFolderRenamedListeners(Folder folder)
          Notify all folder listeners registered on this folder and this folder's store about the renaming of this folder.
protected  void notifyMessageAddedListeners(Message[] msgs)
          Notify all message count listeners about the addition of messages into this folder.
protected  void notifyMessageChangedListeners(int type, Message msg)
          Notify all message changed event listeners.
protected  void notifyMessageRemovedListeners(boolean removed, Message[] msgs)
          Notify all message count listeners about the removal of messages from this folder.
abstract  void open(int mode)
          Opens 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 message changed event listener.
 void removeMessageCountListener(MessageCountListener l)
          Remove a message count event listener.
abstract  boolean renameTo(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.
 void setFlags(int[] msgnums, Flags flag, boolean value)
          Sets the specified flags on each of the specified messages.
 void setFlags(int start, int end, Flags flag, boolean value)
          Set the specified flags on the given range of messages (inclusive).
 void setFlags(Message[] msgs, Flags flag, boolean value)
          Sets the specified flags on each specified message.
 void setSubscribed(boolean flag)
          Subscribe to or unsubscribe from this folder.
 java.lang.String toString()
          Returns the value of Folder.getFullName(), or, if that is null, returns the default toString().
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

HOLDS_MESSAGES

public static final int HOLDS_MESSAGES
This folder can contain messages.

See Also:
Constant Field Values

HOLDS_FOLDERS

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

See Also:
Constant Field Values

READ_ONLY

public static final int READ_ONLY
This folder is read only.

See Also:
Constant Field Values

READ_WRITE

public static final int READ_WRITE
This folder can be modified.

See Also:
Constant Field Values

store

protected Store store
The parent store.


mode

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

Constructor Detail

Folder

protected Folder(Store store)
Constructor.

Parameters:
store - the parent store
Method Detail

getName

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

This method can be invoked on a closed folder.


getFullName

public abstract java.lang.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.


getURLName

public URLName getURLName()
                   throws MessagingException
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.

Throws:
MessagingException

getStore

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


getParent

public abstract Folder getParent()
                          throws MessagingException
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.

Throws:
MessagingException

exists

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

This method can be invoked on a closed folder.

Throws:
MessagingException

list

public abstract Folder[] list(java.lang.String pattern)
                       throws MessagingException
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
Throws:
MessagingException

listSubscribed

public Folder[] listSubscribed(java.lang.String pattern)
                        throws MessagingException
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
Throws:
MessagingException

list

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

This method can be invoked on a closed folder.

Throws:
MessagingException

listSubscribed

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

This method can be invoked on a closed folder.

Throws:
MessagingException

getSeparator

public abstract char getSeparator()
                           throws MessagingException
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.

Throws:
MessagingException

getType

public abstract int getType()
                     throws MessagingException
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.

Throws:
MessagingException

create

public abstract boolean create(int type)
                        throws MessagingException
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
Throws:
MessagingException

isSubscribed

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

This method can be invoked on a closed folder.


setSubscribed

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

This method can be invoked on a closed folder.

Throws:
MessagingException

hasNewMessages

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

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

Throws:
MessagingException

getFolder

public abstract Folder getFolder(java.lang.String name)
                          throws MessagingException
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
Throws:
MessagingException

delete

public abstract boolean delete(boolean recurse)
                        throws MessagingException
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
java.lang.IllegalStateException - if this folder is not closed
MessagingException

renameTo

public abstract boolean renameTo(Folder folder)
                          throws MessagingException
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
java.lang.IllegalStateException - if this folder is not closed
MessagingException

open

public abstract void open(int mode)
                   throws MessagingException
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
java.lang.IllegalStateException - if this folder is not closed
MessagingException

close

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

Parameters:
expunge - if true, expunge all deleted messages
Throws:
MessagingException

isOpen

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


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:
java.lang.IllegalStateException - if this folder is not open

getPermanentFlags

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


getMessageCount

public abstract int getMessageCount()
                             throws MessagingException
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.

Throws:
MessagingException

getNewMessageCount

public int getNewMessageCount()
                       throws MessagingException
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.

Throws:
MessagingException

getUnreadMessageCount

public int getUnreadMessageCount()
                          throws MessagingException
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.

Throws:
MessagingException

getDeletedMessageCount

public int getDeletedMessageCount()
                           throws MessagingException
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
MessagingException
Since:
JavaMail 1.3

getMessage

public abstract Message getMessage(int msgnum)
                            throws MessagingException
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
java.lang.IllegalStateException - if this folder is closed
java.lang.IndexOutOfBoundsException - if the message number is out of range
MessagingException

getMessages

public Message[] getMessages(int start,
                             int end)
                      throws MessagingException
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
java.lang.IllegalStateException - if this folder is closed
java.lang.IndexOutOfBoundsException - if the start or end message numbers are out of range.
MessagingException

getMessages

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

Parameters:
msgnums - the array of message numbers
Throws:
FolderNotFoundException - if this folder does not exist
java.lang.IllegalStateException - if this folder is closed
java.lang.IndexOutOfBoundsException - if any message number in the given array is out of range
MessagingException

getMessages

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

Throws:
FolderNotFoundException - if this folder does not exist
java.lang.IllegalStateException - if this folder is closed
MessagingException

appendMessages

public abstract void appendMessages(Message[] msgs)
                             throws MessagingException
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

fetch

public void fetch(Message[] msgs,
                  FetchProfile fp)
           throws MessagingException
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
Throws:
MessagingException

setFlags

public void setFlags(Message[] msgs,
                     Flags flag,
                     boolean value)
              throws MessagingException
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:
java.lang.IllegalStateException - if this folder is closed or READ_ONLY
MessagingException

setFlags

public void setFlags(int start,
                     int end,
                     Flags flag,
                     boolean value)
              throws MessagingException
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:
java.lang.IllegalStateException - if this folder is closed or READ_ONLY
java.lang.IndexOutOfBoundsException - if the start or end message numbers are out of range
MessagingException

setFlags

public void setFlags(int[] msgnums,
                     Flags flag,
                     boolean value)
              throws MessagingException
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:
java.lang.IllegalStateException - if this folder is closed or READ_ONLY
java.lang.IndexOutOfBoundsException - if any message number in the given array is out of range
MessagingException

copyMessages

public void copyMessages(Message[] msgs,
                         Folder folder)
                  throws MessagingException
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
Throws:
MessagingException

expunge

public abstract Message[] expunge()
                           throws MessagingException
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
java.lang.IllegalStateException - if this folder is closed
MessagingException

search

public Message[] search(SearchTerm term)
                 throws MessagingException
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
java.lang.IllegalStateException - if this folder is closed
MessagingException

search

public Message[] search(SearchTerm term,
                        Message[] msgs)
                 throws MessagingException
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
java.lang.IllegalStateException - if this folder is closed
MessagingException

addConnectionListener

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


removeConnectionListener

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


notifyConnectionListeners

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


addFolderListener

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


removeFolderListener

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


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.


addMessageCountListener

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


removeMessageCountListener

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


notifyMessageAddedListeners

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


notifyMessageRemovedListeners

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


addMessageChangedListener

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


removeMessageChangedListener

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


notifyMessageChangedListeners

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


toString

public java.lang.String toString()
Returns the value of Folder.getFullName(), or, if that is null, returns the default toString().

Overrides:
toString in class java.lang.Object


© Copyright 2003, 2004 The Free Software Foundation, All rights reserved