Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Inner 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.

Inner classes inherited from class javax.mail.UIDFolder
`UIDFolder.FetchProfileItem`

Field Summary
`protected Flags` | `availableFlags`
`protected boolean` | `exists`
`protected java.lang.String` | `fullName`
`protected java.util.Vector` | `messageCache`
`protected java.lang.Object` | `messageCacheLock`
`protected java.lang.String` | `name`
`protected Flags` | `permanentFlags`
`protected com.sun.mail.imap.protocol.IMAPProtocol` | `protocol`
`protected char` | `separator`
`protected int` | `type`
`protected java.util.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(java.lang.String fullName, char separator, IMAPStore store)` 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` | `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.
`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.
`java.lang.Object` | `doCommand(IMAPFolder.ProtocolCommand cmd)` Execute a user-supplied IMAP command.
`java.lang.Object` | `doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd)`
`java.lang.Object` | `doOptionalCommand(java.lang.String err, IMAPFolder.ProtocolCommand cmd)`
`protected java.lang.Object` | `doProtocolCommand(IMAPFolder.ProtocolCommand cmd)`
`boolean` | `exists()` Check whether this folder really exists on the server.
`Message[]` | `expunge()` Expunge.
`void` | `fetch(Message[] msgs, FetchProfile fp)` Prefetch attributes, based on the given FetchProfile.
`ACL[]` | `getACL()` Get the access control list entries for this folder.
`int` | `getDeletedMessageCount()` Get the deleted message count.
`Folder` | `getFolder(java.lang.String name)` Get the named subfolder.
`java.lang.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.
`java.lang.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.
`com.sun.mail.imap.protocol.IMAPProtocol` | `getProtocol()` Return the IMAPProtocol object for this folder.
`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` | `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.
`boolean` | `isOpen()` Check whether this connection is really open.
`boolean` | `isSubscribed()` Check whether this folder is subscribed.
`Folder[]` | `list(java.lang.String pattern)` List all subfolders matching the specified pattern.
`Rights[]` | `listRights(java.lang.String name)` Get all the rights that may be allowed to the given identifier.
`Folder[]` | `listSubscribed(java.lang.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(java.lang.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, addMessageCountListener, 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 java.lang.String fullName

### name

    protected java.lang.String name

### type

    protected int type

### separator

    protected char separator

### availableFlags

    protected Flags availableFlags

### permanentFlags

    protected Flags permanentFlags

### exists

    protected boolean exists

### protocol

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

### messageCache

    protected java.util.Vector messageCache

### messageCacheLock

    protected java.lang.Object messageCacheLock

### uidTable

    protected java.util.Hashtable uidTable

### UNKNOWN_SEPARATOR

    protected static final char UNKNOWN_SEPARATOR

Constructor Detail

### IMAPFolder

    protected IMAPFolder(java.lang.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(com.sun.mail.imap.protocol.ListInfo li,
                         IMAPStore store)

  Constructor used to create an existing folder.

Method Detail

### getName

    public java.lang.String getName()

  Get the name of this folder.
  Overrides:
    `getName` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    name of the Folder

### getFullName

    public java.lang.String getFullName()

  Get the fullname of this folder.
  Overrides:
    `getFullName` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    full name of the Folder

### getParent

    public Folder getParent()
                     throws MessagingException

  Get this folder's parent.
  Overrides:
    `getParent` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    Parent folder

### exists

    public boolean exists()
                   throws MessagingException

  Check whether this folder really exists on the server.
  Overrides:
    `exists` in class `Folder`
  Following copied from class: `javax.mail.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(java.lang.String pattern)
                  throws MessagingException

  List all subfolders matching the specified pattern.
  Overrides:
    `list` in class `Folder`
  Following copied from class: `javax.mail.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(java.lang.String pattern)
                            throws MessagingException

  List all subscribed subfolders matching the specified pattern.
  Overrides:
    `listSubscribed` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `pattern` - the match pattern
  Returns:
    array of matching subscribed Folder objects. An empty array is returned of 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.
  Overrides:
    `getSeparator` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    Hierarchy separator character
  Throws:
    `FolderNotFoundException` - if this folder does not exist

### getType

    public int getType()
                throws MessagingException

  Get the type of this folder.
  Overrides:
    `getType` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    integer with appropriate bits set
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
  See Also:
    `Folder.HOLDS_FOLDERS`, `Folder.HOLDS_MESSAGES`

### isSubscribed

    public boolean isSubscribed()

  Check whether this folder is subscribed.

  Overrides:
    `isSubscribed` in class `Folder`
  Following copied from class: `javax.mail.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`
  Following copied from class: `javax.mail.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.
  Overrides:
    `create` in class `Folder`
  Following copied from class: `javax.mail.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.
  Overrides:
    `hasNewMessages` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    true if the Store has new Messages
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException` -

### getFolder

    public Folder getFolder(java.lang.String name)
                     throws MessagingException

  Get the named subfolder.

  Overrides:
    `getFolder` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `name` - name of the Folder
  Returns:
    Folder object
  Throws:
    `MessagingException` -

### delete

    public boolean delete(boolean recurse)
                   throws MessagingException

  Delete this folder.
  Overrides:
    `delete` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    true if the Folder is deleted successfully
  Throws:
    `FolderNotFoundException` - if this folder does not exist
    `IllegalStateException` - if this folder is not in the closed state.
    `MessagingException` -
  See Also:
    `FolderEvent`

### renameTo

    public boolean renameTo(Folder f)
                     throws MessagingException

  Rename this folder.

  Overrides:
    `renameTo` in class `Folder`
  Following copied from class: `javax.mail.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
    `IllegalStateException` - if this folder is not in the closed state.
    `MessagingException` -
  See Also:
    `FolderEvent`

### open

    public void open(int mode)
              throws MessagingException

  Open this folder in the given mode.
  Overrides:
    `open` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `mode` - open the Folder READ_ONLY or READ_WRITE
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `IllegalStateException` - if this folder is not in the closed state.
    `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`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `msgs` - fetch items for these messages
    `fp` - the FetchProfile
  Throws:
    `IllegalStateException` - if this folder is not opened
    `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`
  Following copied from class: `javax.mail.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:
    `IllegalStateException` - if this folder is not opened or if it has been opened READ_ONLY.
    `MessagingException` -
  See Also:
    `Message.setFlags(javax.mail.Flags, boolean)`, `MessageChangedEvent`

### close

    public void close(boolean expunge)
               throws MessagingException

  Close this folder.
  Overrides:
    `close` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `expunge` - expunges all deleted messages if this flag is true
  Throws:
    `IllegalStateException` - if this folder is not opened
    `MessagingException` -
  See Also:
    `ConnectionEvent`

### isOpen

    public boolean isOpen()

  Check whether this connection is really open.
  Overrides:
    `isOpen` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    true if this Folder is in the 'open' state.

### getPermanentFlags

    public Flags getPermanentFlags()

  Return the permanent flags supported by the server.
  Overrides:
    `getPermanentFlags` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    permanent flags, or null if not known

### getMessageCount

    public int getMessageCount()
                        throws MessagingException

  Get the total message count.
  Overrides:
    `getMessageCount` in class `Folder`
  Following copied from class: `javax.mail.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`
  Following copied from class: `javax.mail.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`
  Following copied from class: `javax.mail.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`
  Following copied from class: `javax.mail.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.
  Overrides:
    `getMessage` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `msgnum` - the message number
  Returns:
    the Message object
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `IllegalStateException` - if this folder is not opened
    `IndexOutOfBoundsException` - if the message number is out of range.
    `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.
  Overrides:
    `appendMessages` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Parameters:
    `msgs` - array of Messages to be appended
  Throws:
    `FolderNotFoundException` - if this folder does not exist.
    `MessagingException` - if the append failed.

### 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`
  Following copied from class: `javax.mail.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.
    `IllegalStateException` - if this folder is not opened.
    `MessagingException` -
  See Also:
    `Folder.appendMessages(javax.mail.Message[])`

### expunge

    public Message[] expunge()
                      throws MessagingException

  Expunge.
  Overrides:
    `expunge` in class `Folder`
  Following copied from class: `javax.mail.Folder`
  Returns:
    array of expunged Message objects
  Throws:
    `FolderNotFoundException` - if this folder does not exist
    `IllegalStateException` - if this folder is not opened.
    `MessagingException` -
  See Also:
    `Message.isExpunged()`, `MessageCountEvent`

### search

    public Message[] search(SearchTerm term)
                     throws MessagingException

  Search whole folder for messages matching the given term.
  Overrides:
    `search` in class `Folder`
  Following copied from class: `javax.mail.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.
    `IllegalStateException` - if this folder is not opened.
    `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`
  Following copied from class: `javax.mail.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.
    `IllegalStateException` - if this folder is not opened
    `MessagingException` -
  See Also:
    `SearchTerm`

### getUIDValidity

    public long getUIDValidity()
                        throws MessagingException

  Returns the UIDValidity for this folder
  Specified by:
    `getUIDValidity` in interface `UIDFolder`
  Following copied from interface: `javax.mail.UIDFolder`
  Returns:
    UIDValidity

### 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`
  Following copied from interface: `javax.mail.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`
  Following copied from interface: `javax.mail.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`
  Following copied from interface: `javax.mail.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`
  Following copied from interface: `javax.mail.UIDFolder`
  Parameters:
    `message` - Message from this folder
  Returns:
    UID for this message
  Throws:
    `java.util.NoSuchElementException` - if the given Message is not in this Folder.

### 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(java.lang.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(java.lang.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

### 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); }

### getProtocol

    public com.sun.mail.imap.protocol.IMAPProtocol getProtocol()

  Return the IMAPProtocol object for this folder.

  NOTE: This method was intended to allow experimentation with simple extension commands that can use the low level Protocol object APIs to send commands and process responses.

  NOTE: Using this protocol object is completely UNSAFE because there's no way to aquire the required locks. See the `doCommand` method for a safe alternative.

  Returns:
    the IMAPProtocol object used when the folder is open
  See Also:
    `doCommand(com.sun.mail.imap.IMAPFolder.ProtocolCommand)`

### doCommand

    public java.lang.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;
      	}
       });

### doOptionalCommand

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

### doCommandIgnoreFailure

    public java.lang.Object doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd)
                                            throws MessagingException

### doProtocolCommand

    protected java.lang.Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd)
                                          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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD