## com.sun.mail.imap
Class IMAPFolder

    java.lang.Object
      javax.mail.Folder
          com.sun.mail.imap.IMAPFolder

All Implemented Interfaces:
  com.sun.mail.iap.ResponseHandler, UIDFolder

    public class IMAPFolder

extends Folder
implements UIDFolder, com.sun.mail.iap.ResponseHandler

This class implements an IMAP folder.

A closed IMAPFolder object shares a protocol connection with its IMAPStore object. When the folder is opened, it gets its own protocol connection.

Applications that need to make use of IMAP-specific features may cast a `Folder` object to an `IMAPFolder` object and use the methods on this class. The `getQuota` and `setQuota` methods support the IMAP QUOTA extension. Refer to RFC 2087 for more information.

The `getACL`, `addACL`, `removeACL`, `addRights`, `removeRights`, `listRights`, and `myRights` methods support the IMAP ACL extension. Refer to RFC 2086 for more information.

The `doCommand` method and `IMAPFolder.ProtocolCommand` interface support use of arbitrary IMAP protocol commands.

See the com.sun.mail.imap package documentation for further information on the IMAP protocol provider.

WARNING: The APIs unique to this class should be considered EXPERIMENTAL. They may be changed in the future in ways that are incompatible with applications using the current APIs.

Nested Class Summary
`static class` `IMAPFolder.FetchProfileItem` A fetch profile item for fetching headers.
`static interface` `IMAPFolder.ProtocolCommand` A simple interface for user-defined IMAP protocol commands.

Field Summary
`protected String[]` `attributes`
`protected Flags` `availableFlags`
`protected boolean` `exists`
`protected String` `fullName`
`protected boolean` `isNamespace`
`protected com.sun.mail.imap.MessageCache` `messageCache`
`protected Object` `messageCacheLock`
`protected String` `name`
`protected Flags` `permanentFlags`
`protected com.sun.mail.imap.protocol.IMAPProtocol` `protocol`
`protected char` `separator`
`protected int` `type`
`protected Hashtable` `uidTable`
`protected static char` `UNKNOWN_SEPARATOR`

Fields inherited from class javax.mail.Folder
`HOLDS_FOLDERS, HOLDS_MESSAGES, mode, READ_ONLY, READ_WRITE, store`

Fields inherited from interface javax.mail.UIDFolder
`LASTUID`

Constructor Summary
`protected` `IMAPFolder(com.sun.mail.imap.protocol.ListInfo li, IMAPStore store)` Constructor used to create an existing folder.
`protected` `IMAPFolder(String fullName, char separator, IMAPStore store)` Constructor used to create a possibly non-existent folder.
`protected` `IMAPFolder(String fullName, char separator, IMAPStore store, boolean isNamespace)` Constructor used to create a possibly non-existent folder.

Method Summary
`void` `addACL(ACL acl)` Add an access control list entry to the access control list for this folder.
`void` `addMessageCountListener(MessageCountListener l)` Add a listener for MessageCount events on this Folder.
`Message[]` `addMessages(Message[] msgs)` Append the given messages into this folder.
`void` `addRights(ACL acl)` Add the rights specified in the ACL to the entry for the identifier specified in the ACL.
`void` `appendMessages(Message[] msgs)` Append the given messages into this folder.
`com.sun.mail.imap.AppendUID[]` `appendUIDMessages(Message[] msgs)` Append the given messages into this folder.
`void` `close(boolean expunge)` Close this folder.
`void` `copyMessages(Message[] msgs, Folder folder)` Copy the specified messages from this folder, to the specified destination.
`boolean` `create(int type)` Create this folder, with the specified type.
`boolean` `delete(boolean recurse)` Delete this folder.
`Object` `doCommand(IMAPFolder.ProtocolCommand cmd)` Execute a user-supplied IMAP command.
`Object` `doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd)`
`Object` `doOptionalCommand(String err, IMAPFolder.ProtocolCommand cmd)`
`protected Object` `doProtocolCommand(IMAPFolder.ProtocolCommand cmd)`
`boolean` `exists()` Check whether this folder really exists on the server.
`Message[]` `expunge()` Expunge all messages marked as DELETED.
`Message[]` `expunge(Message[] msgs)` Expunge the indicated messages, which must have been marked as DELETED.
`void` `fetch(Message[] msgs, FetchProfile fp)` Prefetch attributes, based on the given FetchProfile.
`void` `forceClose()` Close this folder without waiting for the server.
`ACL[]` `getACL()` Get the access control list entries for this folder.
`String[]` `getAttributes()` Get the attributes that the IMAP server returns with the LIST response.
`int` `getDeletedMessageCount()` Get the deleted message count.
`Folder` `getFolder(String name)` Get the named subfolder.
`String` `getFullName()` Get the fullname of this folder.
`Message` `getMessage(int msgnum)` Get the specified message.
`Message` `getMessageByUID(long uid)` Get the Message corresponding to the given UID.
`int` `getMessageCount()` Get the total message count.
`Message[]` `getMessagesByUID(long[] uids)` Get the Messages specified by the given array.
`Message[]` `getMessagesByUID(long start, long end)` Get the Messages specified by the given range.
`String` `getName()` Get the name of this folder.
`int` `getNewMessageCount()` Get the new message count.
`Folder` `getParent()` Get this folder's parent.
`Flags` `getPermanentFlags()` Return the permanent flags supported by the server.
`Quota[]` `getQuota()` Get the quotas for the quotaroot associated with this folder.
`char` `getSeparator()` Get the separator character.
`protected com.sun.mail.imap.protocol.IMAPProtocol` `getStoreProtocol()` Get this folder's Store's protocol connection.
`int` `getType()` Get the type of this folder.
`long` `getUID(Message message)` Get the UID for the specified message.
`long` `getUIDNext()` Returns the predicted UID that will be assigned to the next message that is appended to this folder.
`long` `getUIDValidity()` Returns the UIDValidity for this folder.
`int` `getUnreadMessageCount()` Get the unread message count.
`void` `handleResponse(com.sun.mail.iap.Response r)` The response handler.
`boolean` `hasNewMessages()` Check whether this folder has new messages.
`void` `idle()` Use the IMAP IDLE command (see RFC 2177), if supported by the server, to enter idle mode so that the server can send unsolicited notifications of new messages arriving, etc.
`void` `idle(boolean once)` Like `idle()`, but if `once` is true, abort the IDLE command after the first notification, to allow the caller to process any notification synchronously.
`boolean` `isOpen()` Check whether this connection is really open.
`boolean` `isSubscribed()` Check whether this folder is subscribed.
`Folder[]` `list(String pattern)` List all subfolders matching the specified pattern.
`Rights[]` `listRights(String name)` Get all the rights that may be allowed to the given identifier.
`Folder[]` `listSubscribed(String pattern)` List all subscribed subfolders matching the specified pattern.
`Rights` `myRights()` Get the rights allowed to the currently authenticated user.
`void` `open(int mode)` Open this folder in the given mode.
`protected void` `releaseStoreProtocol(com.sun.mail.imap.protocol.IMAPProtocol p)` Release the store protocol object.
`void` `removeACL(String name)` Remove any access control list entry for the given identifier from the access control list for this folder.
`void` `removeRights(ACL acl)` Remove the rights specified in the ACL from the entry for the identifier specified in the ACL.
`boolean` `renameTo(Folder f)` Rename this folder.
`Message[]` `search(SearchTerm term)` Search whole folder for messages matching the given term.
`Message[]` `search(SearchTerm term, Message[] msgs)` Search the folder for messages matching the given term.
`void` `setFlags(Message[] msgs, Flags flag, boolean value)` Set the specified flags for the given array of messages.
`void` `setQuota(Quota quota)` Set the quotas for the quotaroot specified in the quota argument.
`void` `setSubscribed(boolean subscribe)` Subscribe/Unsubscribe this folder.

Methods inherited from class javax.mail.Folder

`addConnectionListener, addFolderListener, addMessageChangedListener, finalize, getMessages, getMessages, getMessages, getMode, getStore, getURLName, list, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, notifyMessageAddedListeners, notifyMessageChangedListeners, notifyMessageRemovedListeners, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, setFlags, setFlags, toString`

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### fullName

    protected String fullName

### name

    protected String name

### type

    protected int type

### separator

    protected char separator

### availableFlags

    protected Flags availableFlags

### permanentFlags

    protected Flags permanentFlags

### exists

    protected boolean exists

### isNamespace

    protected boolean isNamespace

### attributes

    protected String[] attributes

### protocol

    protected com.sun.mail.imap.protocol.IMAPProtocol protocol

### messageCache

    protected com.sun.mail.imap.MessageCache messageCache

### messageCacheLock

    protected final Object messageCacheLock

### uidTable

    protected Hashtable uidTable

### UNKNOWN_SEPARATOR

    protected static final char UNKNOWN_SEPARATOR

See Also:
  Constant Field Values

Constructor Detail

### IMAPFolder

    protected IMAPFolder(String fullName,
                         char separator,
                         IMAPStore store)

  Constructor used to create a possibly non-existent folder.

  Parameters:
    `fullName` - fullname of this folder
    `separator` - the default separator character for this folder's namespace
    `store` - the Store

### IMAPFolder

    protected IMAPFolder(String fullName,
                         char separator,
                         IMAPStore store,
                         boolean isNamespace)

  Constructor used to create a possibly non-existent folder.

  Parameters:
    `fullName` - fullname of this folder
    `separator` - the default separator character for this folder's namespace
    `store` - the Store

### IMAPFolder

    protected IMAPFolder(com.sun.mail.imap.protocol.ListInfo li,
                         IMAPStore store)

  Constructor used to create an existing folder.

Method Detail

### getName

    public String getName()

  Get the name of this folder.

  Specified by:
    `getName` in class `Folder`
  Returns:
    name of the Folder

### getFullName

    public String getFullName()

  Get the fullname of this folder.

  Specified by:
    `getFullName` in class `Folder`
  Returns:
    full name of the Folder

### getParent

    public Folder getParent()
                     throws MessagingException

  Get this folder's parent.

  Specified by:
    `getParent` in class `Folder`
  Returns:
    Parent folder
  Throws:
    `MessagingException`

### exists

    public boolean exists()
                   throws MessagingException

  Check whether this folder really exists on the server.

  Specified by:
    `exists` in class `Folder`
  Returns:
    true if the folder exists, otherwise false
  Throws:
    `MessagingException` - typically if the connection to the server is lost.
  See Also:
    `Folder.create(int)`

### list

    public Folder[] list(String pattern)
                  throws MessagingException

  List all subfolders matching the specified pattern.

  Specified by:
    `list` in class `Folder`
  Parameters:
    `pattern` - the match pattern
  Returns:
    array of matching Folder objects. An empty array is returned if no matching Folders exist.
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`
  See Also:
    `Folder.listSubscribed(java.lang.String)`

### listSubscribed

    public Folder[] listSubscribed(String pattern)
                            throws MessagingException

  List all subscribed subfolders matching the specified pattern.

  Overrides:
    `listSubscribed` in class `Folder`
  Parameters:
    `pattern` - the match pattern
  Returns:
    array of matching subscribed Folder objects. An empty array is returned if no matching subscribed folders exist.
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`
  See Also:
    `Folder.list(java.lang.String)`

### getSeparator

    public char getSeparator()
                      throws MessagingException

  Get the separator character.

  Specified by:
    `getSeparator` in class `Folder`
  Returns:
    Hierarchy separator character
  Throws:
    `FolderNotFoundException` - if the implementation requires the folder to exist, but it does not
    `MessagingException`

### getType

    public int getType()
                throws MessagingException

  Get the type of this folder.

  Specified by:
    `getType` in class `Folder`
  Returns:
    integer with appropriate bits set
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`
  See Also:
    `Folder.HOLDS_FOLDERS`, `Folder.HOLDS_MESSAGES`

### isSubscribed

    public boolean isSubscribed()

  Check whether this folder is subscribed.

  Overrides:
    `isSubscribed` in class `Folder`
  Returns:
    true if this Folder is subscribed

### setSubscribed

    public void setSubscribed(boolean subscribe)
                       throws MessagingException

  Subscribe/Unsubscribe this folder.

  Overrides:
    `setSubscribed` in class `Folder`
  Parameters:
    `subscribe` - true to subscribe, false to unsubscribe
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MethodNotSupportedException` - if this store does not support subscription
    `MessagingException`

### create

    public boolean create(int type)
                   throws MessagingException

  Create this folder, with the specified type.

  Specified by:
    `create` in class `Folder`
  Parameters:
    `type` - The type of this folder.
  Returns:
    true if the creation succeeds, else false.
  Throws:
    `MessagingException`
  See Also:
    `Folder.HOLDS_FOLDERS`, `Folder.HOLDS_MESSAGES`, `FolderEvent`

### hasNewMessages

    public boolean hasNewMessages()
                           throws MessagingException

  Check whether this folder has new messages.

  Specified by:
    `hasNewMessages` in class `Folder`
  Returns:
    true if the Store has new Messages
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`

### getFolder

    public Folder getFolder(String name)
                     throws MessagingException

  Get the named subfolder.

  Specified by:
    `getFolder` in class `Folder`
  Parameters:
    `name` - name of the Folder
  Returns:
    Folder object
  Throws:
    `MessagingException`

### delete

    public boolean delete(boolean recurse)
                   throws MessagingException

  Delete this folder.

  Specified by:
    `delete` in class `Folder`
  Returns:
    true if the Folder is deleted successfully
  Throws:
    `FolderNotFoundException` - if this folder does not exist
    `MessagingException`
  See Also:
    `FolderEvent`

### renameTo

    public boolean renameTo(Folder f)
                     throws MessagingException

  Rename this folder.

  Specified by:
    `renameTo` in class `Folder`
  Parameters:
    `f` - a folder representing the new name for this Folder
  Returns:
    true if the Folder is renamed successfully
  Throws:
    `FolderNotFoundException` - if this folder does not exist
    `MessagingException`
  See Also:
    `FolderEvent`

### open

    public void open(int mode)
              throws MessagingException

  Open this folder in the given mode.

  Specified by:
    `open` in class `Folder`
  Parameters:
    `mode` - open the Folder READ_ONLY or READ_WRITE
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`
  See Also:
    `Folder.READ_ONLY`, `Folder.READ_WRITE`, `Folder.getType()`, `ConnectionEvent`

### fetch

    public void fetch(Message[] msgs,
                      FetchProfile fp)
               throws MessagingException

  Prefetch attributes, based on the given FetchProfile.

  Overrides:
    `fetch` in class `Folder`
  Parameters:
    `msgs` - fetch items for these messages
    `fp` - the FetchProfile
  Throws:
    `MessagingException`

### setFlags

    public void setFlags(Message[] msgs,
                         Flags flag,
                         boolean value)
                  throws MessagingException

  Set the specified flags for the given array of messages.

  Overrides:
    `setFlags` in class `Folder`
  Parameters:
    `msgs` - the array of message objects
    `flag` - Flags object containing the flags to be set
    `value` - set the flags to this boolean value
  Throws:
    `MessagingException`
  See Also:
    `Message.setFlags(javax.mail.Flags, boolean)`, `MessageChangedEvent`

### close

    public void close(boolean expunge)
               throws MessagingException

  Close this folder.

  Specified by:
    `close` in class `Folder`
  Parameters:
    `expunge` - expunges all deleted messages if this flag is true
  Throws:
    `MessagingException`
  See Also:
    `ConnectionEvent`

### forceClose

    public void forceClose()
                    throws MessagingException

  Close this folder without waiting for the server.

  Throws:
    `MessagingException`

### isOpen

    public boolean isOpen()

  Check whether this connection is really open.

  Specified by:
    `isOpen` in class `Folder`
  Returns:
    true if this Folder is in the 'open' state.

### getPermanentFlags

    public Flags getPermanentFlags()

  Return the permanent flags supported by the server.

  Specified by:
    `getPermanentFlags` in class `Folder`
  Returns:
    permanent flags, or null if not known

### getMessageCount

    public int getMessageCount()
                        throws MessagingException

  Get the total message count.

  Specified by:
    `getMessageCount` in class `Folder`
  Returns:
    total number of messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`

### getNewMessageCount

    public int getNewMessageCount()
                           throws MessagingException

  Get the new message count.

  Overrides:
    `getNewMessageCount` in class `Folder`
  Returns:
    number of new messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`

### getUnreadMessageCount

    public int getUnreadMessageCount()
                              throws MessagingException

  Get the unread message count.

  Overrides:
    `getUnreadMessageCount` in class `Folder`
  Returns:
    total number of unread messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`

### getDeletedMessageCount

    public int getDeletedMessageCount()
                               throws MessagingException

  Get the deleted message count.

  Overrides:
    `getDeletedMessageCount` in class `Folder`
  Returns:
    number of deleted messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`

### getMessage

    public Message getMessage(int msgnum)
                       throws MessagingException

  Get the specified message.

  Specified by:
    `getMessage` in class `Folder`
  Parameters:
    `msgnum` - the message number
  Returns:
    the Message object
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`
  See Also:
    `Folder.getMessageCount()`, `Folder.fetch(javax.mail.Message[], javax.mail.FetchProfile)`

### appendMessages

    public void appendMessages(Message[] msgs)
                        throws MessagingException

  Append the given messages into this folder.

  Specified by:
    `appendMessages` in class `Folder`
  Parameters:
    `msgs` - array of Messages to be appended
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException` - if the append failed.

### appendUIDMessages

    public com.sun.mail.imap.AppendUID[] appendUIDMessages(Message[] msgs)
                                                    throws MessagingException

  Append the given messages into this folder. Return array of AppendUID objects containing UIDs of these messages in the destination folder. Each element of the returned array corresponds to an element of the `msgs` array. A null element means the server didn't return UID information for the appended message.

  Depends on the APPENDUID response code defined by the UIDPLUS extension - RFC 2359.

  Throws:
    `MessagingException`
  Since:
    JavaMail 1.4

### addMessages

    public Message[] addMessages(Message[] msgs)
                          throws MessagingException

  Append the given messages into this folder. Return array of Message objects representing the messages in the destination folder. Note that the folder must be open. Each element of the returned array corresponds to an element of the `msgs` array. A null element means the server didn't return UID information for the appended message.

  Depends on the APPENDUID response code defined by the UIDPLUS extension - RFC 2359.

  Throws:
    `MessagingException`
  Since:
    JavaMail 1.4

### copyMessages

    public void copyMessages(Message[] msgs,
                             Folder folder)
                      throws MessagingException

  Copy the specified messages from this folder, to the specified destination.

  Overrides:
    `copyMessages` in class `Folder`
  Parameters:
    `msgs` - the array of message objects
    `folder` - the folder to copy the messages to
  Throws:
    `FolderNotFoundException` - if the destination folder does not exist.
    `MessagingException`
  See Also:
    `Folder.appendMessages(javax.mail.Message[])`

### expunge

    public Message[] expunge()
                      throws MessagingException

  Expunge all messages marked as DELETED.

  Specified by:
    `expunge` in class `Folder`
  Returns:
    array of expunged Message objects
  Throws:
    `FolderNotFoundException` - if this folder does not exist
    `MessagingException`
  See Also:
    `Message.isExpunged()`, `MessageCountEvent`

### expunge

    public Message[] expunge(Message[] msgs)
                      throws MessagingException

  Expunge the indicated messages, which must have been marked as DELETED.

  Throws:
    `MessagingException`

### search

    public Message[] search(SearchTerm term)
                     throws MessagingException

  Search whole folder for messages matching the given term.

  Overrides:
    `search` in class `Folder`
  Parameters:
    `term` - the search criterion
  Returns:
    array of matching messages
  Throws:
    `SearchException` - if the search term is too complex for the implementation to handle.
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException`
  See Also:
    `SearchTerm`

### search

    public Message[] search(SearchTerm term,
                            Message[] msgs)
                     throws MessagingException

  Search the folder for messages matching the given term. Returns array of matching messages. Returns an empty array if no matching messages are found.

  Overrides:
    `search` in class `Folder`
  Parameters:
    `term` - the search criterion
    `msgs` - the messages to be searched
  Returns:
    array of matching messages
  Throws:
    `SearchException` - if the search term is too complex for the implementation to handle.
    `MessagingException`
  See Also:
    `SearchTerm`

### addMessageCountListener

    public void addMessageCountListener(MessageCountListener l)

  Description copied from class: `Folder`
  Add a listener for MessageCount events on this Folder.

  The implementation provided here adds this listener to an internal list of MessageCountListeners.

  Overrides:
    `addMessageCountListener` in class `Folder`
  Parameters:
    `l` - the Listener for MessageCount events
  See Also:
    `MessageCountEvent`

### getUIDValidity

    public long getUIDValidity()
                        throws MessagingException

  Returns the UIDValidity for this folder.

  Specified by:
    `getUIDValidity` in interface `UIDFolder`
  Returns:
    UIDValidity
  Throws:
    `MessagingException`

### getUIDNext

    public long getUIDNext()
                    throws MessagingException

  Returns the predicted UID that will be assigned to the next message that is appended to this folder. If the folder is closed, the STATUS command is used to retrieve this value. If the folder is open, the value returned from the SELECT or EXAMINE command is returned. Note that messages may have been appended to the folder while it was open and thus this value may be out of date.

  Servers implementing RFC2060 likely won't return this value when a folder is opened. Servers implementing RFC3501 should return this value when a folder is opened.

  Returns:
    the UIDNEXT value, or -1 if unknown
  Throws:
    `MessagingException`
  Since:
    JavaMail 1.3.3

### getMessageByUID

    public Message getMessageByUID(long uid)
                            throws MessagingException

  Get the Message corresponding to the given UID. If no such message exists, `null` is returned.

  Specified by:
    `getMessageByUID` in interface `UIDFolder`
  Parameters:
    `uid` - UID for the desired message
  Returns:
    the Message object. `null` is returned if no message corresponding to this UID is obtained.
  Throws:
    `MessagingException`

### getMessagesByUID

    public Message[] getMessagesByUID(long start,
                                      long end)
                               throws MessagingException

  Get the Messages specified by the given range.

  Returns Message objects for all valid messages in this range. Returns an empty array if no messages are found.

  Specified by:
    `getMessagesByUID` in interface `UIDFolder`
  Parameters:
    `start` - start UID
    `end` - end UID
  Returns:
    array of Message objects
  Throws:
    `MessagingException`
  See Also:
    `UIDFolder.LASTUID`

### getMessagesByUID

    public Message[] getMessagesByUID(long[] uids)
                               throws MessagingException

  Get the Messages specified by the given array.

  `uids.length()` elements are returned. If any UID in the array is invalid, a `null` entry is returned for that element.

  Specified by:
    `getMessagesByUID` in interface `UIDFolder`
  Parameters:
    `uids` - array of UIDs
  Returns:
    array of Message objects
  Throws:
    `MessagingException`

### getUID

    public long getUID(Message message)
                throws MessagingException

  Get the UID for the specified message.

  Specified by:
    `getUID` in interface `UIDFolder`
  Parameters:
    `message` - Message from this folder
  Returns:
    UID for this message
  Throws:
    `MessagingException`

### getQuota

    public Quota[] getQuota()
                     throws MessagingException

  Get the quotas for the quotaroot associated with this folder. Note that many folders may have the same quotaroot. Quotas are controlled on the basis of a quotaroot, not (necessarily) a folder. The relationship between folders and quotaroots depends on the IMAP server. Some servers might implement a single quotaroot for all folders owned by a user. Other servers might implement a separate quotaroot for each folder. A single folder can even have multiple quotaroots, perhaps controlling quotas for different resources.

  Returns:
    array of Quota objects for the quotaroots associated with this folder
  Throws:
    `MessagingException` - if the server doesn't support the QUOTA extension

### setQuota

    public void setQuota(Quota quota)
                  throws MessagingException

  Set the quotas for the quotaroot specified in the quota argument. Typically this will be one of the quotaroots associated with this folder, as obtained from the `getQuota` method, but it need not be.

  Parameters:
    `quota` - the quota to set
  Throws:
    `MessagingException` - if the server doesn't support the QUOTA extension

### getACL

    public ACL[] getACL()
                 throws MessagingException

  Get the access control list entries for this folder.

  Returns:
    array of access control list entries
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### addACL

    public void addACL(ACL acl)
                throws MessagingException

  Add an access control list entry to the access control list for this folder.

  Parameters:
    `acl` - the access control list entry to add
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### removeACL

    public void removeACL(String name)
                   throws MessagingException

  Remove any access control list entry for the given identifier from the access control list for this folder.

  Parameters:
    `name` - the identifier for which to remove all ACL entries
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### addRights

    public void addRights(ACL acl)
                   throws MessagingException

  Add the rights specified in the ACL to the entry for the identifier specified in the ACL. If an entry for the identifier doesn't already exist, add one.

  Parameters:
    `acl` - the identifer and rights to add
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### removeRights

    public void removeRights(ACL acl)
                      throws MessagingException

  Remove the rights specified in the ACL from the entry for the identifier specified in the ACL.

  Parameters:
    `acl` - the identifer and rights to remove
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### listRights

    public Rights[] listRights(String name)
                        throws MessagingException

  Get all the rights that may be allowed to the given identifier. Rights are grouped per RFC 2086 and each group is returned as an element of the array. The first element of the array is the set of rights that are always granted to the identifier. Later elements are rights that may be optionally granted to the identifier.

  Note that this method lists the rights that it is possible to assign to the given identifier, not the rights that are actually granted to the given identifier. For the latter, see the `getACL` method.

  Parameters:
    `name` - the identifier to list rights for
  Returns:
    array of Rights objects representing possible rights for the identifier
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### myRights

    public Rights myRights()
                    throws MessagingException

  Get the rights allowed to the currently authenticated user.

  Returns:
    the rights granted to the current user
  Throws:
    `MessagingException` - if the server doesn't support the ACL extension

### getAttributes

    public String[] getAttributes()
                           throws MessagingException

  Get the attributes that the IMAP server returns with the LIST response.

  Throws:
    `MessagingException`
  Since:
    JavaMail 1.3.3

### idle

    public void idle()
              throws MessagingException

  Use the IMAP IDLE command (see RFC 2177), if supported by the server, to enter idle mode so that the server can send unsolicited notifications of new messages arriving, etc. without the need for the client to constantly poll the server. Use an appropriate listener to be notified of new messages or other events. When another thread (e.g., the listener thread) needs to issue an IMAP comand for this folder, the idle mode will be terminated and this method will return. Typically the caller will invoke this method in a loop.

  The mail.imap.minidletime property enforces a minimum delay before returning from this method, to ensure that other threads have a chance to issue commands before the caller invokes this method again. The default delay is 10 milliseconds.

  Throws:
    `MessagingException` - if the server doesn't support the IDLE extension
    `IllegalStateException` - if the folder isn't open
  Since:
    JavaMail 1.4.1

### idle

    public void idle(boolean once)
              throws MessagingException

  Like `idle()`, but if `once` is true, abort the IDLE command after the first notification, to allow the caller to process any notification synchronously.

  Throws:
    `MessagingException` - if the server doesn't support the IDLE extension
    `IllegalStateException` - if the folder isn't open
  Since:
    JavaMail 1.4.3

### handleResponse

    public void handleResponse(com.sun.mail.iap.Response r)

  The response handler. This is the callback routine that is invoked by the protocol layer.

  Specified by:
    `handleResponse` in interface `com.sun.mail.iap.ResponseHandler`

### getStoreProtocol

    protected com.sun.mail.imap.protocol.IMAPProtocol getStoreProtocol()
                                                                throws com.sun.mail.iap.ProtocolException

  Get this folder's Store's protocol connection. When acquiring a store protocol object, it is important to use the following steps: IMAPProtocol p = null; try { p = getStoreProtocol(); // perform the command } catch (WhateverException ex) { // handle it } finally { releaseStoreProtocol(p); }

  Throws:
    `com.sun.mail.iap.ProtocolException`

### doCommand

    public Object doCommand(IMAPFolder.ProtocolCommand cmd)
                     throws MessagingException

  Execute a user-supplied IMAP command. The command is executed in the appropriate context with the necessary locks held and using the appropriate `IMAPProtocol` object.

  This method returns whatever the `ProtocolCommand` object's `doCommand` method returns. If the `doCommand` method throws a `ConnectionException` it is translated into a `StoreClosedException` or `FolderClosedException` as appropriate. If the `doCommand` method throws a `ProtocolException` it is translated into a `MessagingException`.

  The following example shows how to execute the IMAP NOOP command. Executing more complex IMAP commands requires intimate knowledge of the `com.sun.mail.iap` and `com.sun.mail.imap.protocol` packages, best acquired by reading the source code.

  >      import com.sun.mail.iap.*;
  >      import com.sun.mail.imap.*;
  >      import com.sun.mail.imap.protocol.*;

  >      ...

  >      IMAPFolder f = (IMAPFolder)folder;
  >      Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
  >             public Object doCommand(IMAPProtocol p)
  >                             throws ProtocolException {
  >                 p.simpleCommand("NOOP", null);
  >                 return null;
  >             }
  >      });

  Here's a more complex example showing how to use the proposed IMAP SORT extension:

       import com.sun.mail.iap.*;
       import com.sun.mail.imap.*;
       import com.sun.mail.imap.protocol.*;

       ...

       IMAPFolder f = (IMAPFolder)folder;
       Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
              public Object doCommand(IMAPProtocol p)
                              throws ProtocolException {
                  // Issue command
                  Argument args = new Argument();
                  Argument list = new Argument();
                  list.writeString("SUBJECT");
                  args.writeArgument(list);
                  args.writeString("UTF-8");
                  args.writeString("ALL");
                  Response[] r = p.command("SORT", args);
                  Response response = r[r.length-1];

                  // Grab response
                  Vector v = new Vector();
                  if (response.isOK()) { // command succesful
                      for (int i = 0, len = r.length; i < len; i++) {
                          if (!(r[i] instanceof IMAPResponse))
                              continue;

                          IMAPResponse ir = (IMAPResponse)r[i];
                          if (ir.keyEquals("SORT")) {
                              String num;
                              while ((num = ir.readAtomString()) != null)
                                  System.out.println(num);
                              r[i] = null;
                          }
                      }
                  }

                  // dispatch remaining untagged responses
                  p.notifyResponseHandlers(r);
                  p.handleResult(response);

                  return null;
              }
       });

  Throws:
    `MessagingException`

### doOptionalCommand

    public Object doOptionalCommand(String err,
                                    IMAPFolder.ProtocolCommand cmd)
                             throws MessagingException

  Throws:
    `MessagingException`

### doCommandIgnoreFailure

    public Object doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd)
                                  throws MessagingException

  Throws:
    `MessagingException`

### doProtocolCommand

    protected Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd)
                                throws com.sun.mail.iap.ProtocolException

  Throws:
    `com.sun.mail.iap.ProtocolException`

### releaseStoreProtocol

    protected void releaseStoreProtocol(com.sun.mail.imap.protocol.IMAPProtocol p)

  Release the store protocol object. If we borrowed a protocol object from the connection pool, give it back. If we used our own protocol object, nothing to do.

Copyright © 2009 Sun Microsystems, Inc.. All Rights Reserved.