Package com.sun.mail.imap

# Class IMAPFolder

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

All Implemented Interfaces:
  `ResponseHandler`, `AutoCloseable`, `UIDFolder`

Direct Known Subclasses:
  `DefaultFolder`, `GmailFolder`

public class IMAPFolder extends Folder implements UIDFolder, 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 `getSortedMessages` methods support the IMAP SORT extension. Refer to RFC 5256 for more information.

The `open(int,ResyncData)` method and `ResyncData` class supports the IMAP CONDSTORE and QRESYNC extensions. Refer to RFC 4551 and RFC 5162 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.

Author:
  John Mani, Bill Shannon, Jim Glennon

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`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

Fields
Modifier and Type
Field
Description
`protected String[]`
`attributes`
`protected Flags`
`availableFlags`
`protected boolean`
`exists`
`protected String`
`fullName`
`protected boolean`
`isNamespace`
`protected MailLogger`
`logger`
`protected MessageCache`
`messageCache`
`protected final Object`
`messageCacheLock`
`protected String`
`name`
`protected Flags`
`permanentFlags`
`protected IMAPProtocol`
`protocol`
`protected char`
`separator`
`protected int`
`type`
`protected Hashtable<Long,IMAPMessage>`
`uidTable`
`protected static final 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, MAXUID`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`IMAPFolder(ListInfo li, IMAPStore store)`
Constructor used to create an existing folder.
`protected`
`IMAPFolder(String fullName, char separator, IMAPStore store, Boolean isNamespace)`
Constructor used to create a possibly non-existent folder.

## Method Summary

Modifier and Type
Method
Description
`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.
`AppendUID[]`
`appendUIDMessages(Message[] msgs)`
Append the given messages into this folder.
`protected void`
`checkClosed()`
`protected void`
`checkExists()`
`protected void`
`checkOpened()`
`protected void`
`checkRange(int msgno)`
`void`
`close(boolean expunge)`
Close this folder.
`void`
`copyMessages(Message[] msgs, Folder folder)`
Copy the specified messages from this folder, to the specified destination.
`AppendUID[]`
`copyUIDMessages(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.
`protected String`
`getEnvelopeCommand()`
Return the IMAP FETCH items to request in order to load all the "envelope" data.
`Folder`
`getFolder(String name)`
Get the named subfolder.
`String`
`getFullName()`
Get the fullname of this folder.
`long`
`getHighestModSeq()`
Returns the HIGHESTMODSEQ for this folder.
`Message`
`getMessage(int msgnum)`
Get the specified message.
`protected IMAPMessage`
`getMessageBySeqNumber(int seqnum)`
Get the message object for the given sequence number.
`Message`
`getMessageByUID(long uid)`
Get the Message corresponding to the given UID.
`int`
`getMessageCount()`
Get the total message count.
`Message[]`
`getMessages()`
Get all Message objects from this Folder.
`protected IMAPMessage[]`
`getMessagesBySeqNumbers(int[] seqnums)`
Get the message objects for the given sequence numbers.
`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.
`Message[]`
`getMessagesByUIDChangedSince(long start, long end, long modseq)`
Get the messages that have been changed since the given MODSEQ value.
`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.
`protected 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.
`Message[]`
`getSortedMessages(SortTerm[] term)`
Sort the messages in the folder according to the sort criteria.
`Message[]`
`getSortedMessages(SortTerm[] term, SearchTerm sterm)`
Sort the messages in the folder according to the sort criteria.
`long`
`getStatusItem(String item)`
Use the IMAP STATUS command to get the indicated item.
`protected 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.
`boolean`
`getUIDNotSticky()`
Servers that support the UIDPLUS extension (RFC 4315) may indicate that this folder does not support persistent UIDs; that is, UIDVALIDITY will be different each time the folder is opened.
`long`
`getUIDValidity()`
Returns the UIDValidity for this folder.
`int`
`getUnreadMessageCount()`
Get the unread message count.
`void`
`handleResponse(Response r)`
The response handler.
`boolean`
`hasNewMessages()`
Check whether this folder has new messages.
`Map<String,String>`
`id(Map<String,String> clientParams)`
Send the IMAP ID command (if supported by the server) and return the result from the server.
`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.
`protected void`
`keepConnectionAlive(boolean keepStoreAlive)`
Issue a noop command for the connection if the connection has not been used in more than a second.
`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.
`void`
`moveMessages(Message[] msgs, Folder folder)`
Move the specified messages from this folder, to the specified destination.
`AppendUID[]`
`moveUIDMessages(Message[] msgs, Folder folder)`
Move the specified messages from this folder, to the specified destination.
`Rights`
`myRights()`
Get the rights allowed to the currently authenticated user.
`protected IMAPMessage`
`newIMAPMessage(int msgnum)`
Create a new IMAPMessage object to represent the given message number.
`void`
`open(int mode)`
Open this folder in the given mode.
`List<MailEvent>`
`open(int mode, ResyncData rd)`
Open this folder in the given mode, with the given resynchronization data.
`protected void`
`releaseProtocol(boolean returnToPool)`
Release the protocol object.
`protected void`
`releaseStoreProtocol(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(int[] msgnums, Flags flag, boolean value)`
Set the specified flags for the given array of message numbers.
`void`
`setFlags(int start, int end, Flags flag, boolean value)`
Set the specified flags for the given range of message numbers.
`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.
`protected void`
`throwClosedException(ConnectionException cex)`
Throw the appropriate 'closed' exception.

### Methods inherited from class javax.mail.Folder

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

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Field Details

### fullName

protected volatile String fullName

### name

protected String name

### type

protected int type

### separator

protected char separator

### availableFlags

protected Flags availableFlags

### permanentFlags

protected Flags permanentFlags

### exists

protected volatile boolean exists

### isNamespace

protected boolean isNamespace

### attributes

protected volatile String[] attributes

### protocol

protected volatile IMAPProtocol protocol

### messageCache

protected MessageCache messageCache

### messageCacheLock

protected final Object messageCacheLock

### uidTable

protected Hashtable<Long,IMAPMessage> uidTable

### UNKNOWN_SEPARATOR

protected static final char UNKNOWN_SEPARATOR

See Also:
  - Constant Field Values

### logger

protected MailLogger logger

## Constructor Details

### 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
  `isNamespace` - if this folder represents a namespace

### IMAPFolder

protected IMAPFolder(ListInfo li, IMAPStore store)
Constructor used to create an existing folder.

Parameters:
  `li` - the ListInfo for this folder
  `store` - the store containing this folder

## Method Details

### checkExists

protected void checkExists() throws MessagingException

Throws:
  `MessagingException`

### checkClosed

protected void checkClosed()

### checkOpened

protected void checkOpened() throws FolderClosedException

Throws:
  `FolderClosedException`

### checkRange

protected void checkRange(int msgno) throws MessagingException

Throws:
  `MessagingException`

### 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` - for failures

### 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` - for other failures
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` - for other failures
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` - for other failures

### 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` - for failures
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` - for other failures

### 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` - for failures

### delete

public boolean delete(boolean recurse) throws MessagingException
Delete this folder.

Specified by:
  `delete` in class `Folder`
Parameters:
  `recurse` - also delete subfolders?
Returns:
  true if the Folder is deleted successfully
Throws:
  `FolderNotFoundException` - if this folder does not exist
  `MessagingException` - for other failures
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` - for other failures
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` - for other failures
See Also:
  - `Folder.READ_ONLY`
  - `Folder.READ_WRITE`
  - `Folder.getType()`
  - `ConnectionEvent`

### open

public List<MailEvent> open(int mode, ResyncData rd) throws MessagingException
Open this folder in the given mode, with the given resynchronization data.

Parameters:
  `mode` - the open mode (Folder.READ_WRITE or Folder.READ_ONLY)
  `rd` - the ResyncData instance
Returns:
  a List of MailEvent instances, or null if none
Throws:
  `MessagingException` - if the open fails
Since:
  JavaMail 1.5.1

### 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` - for other failures

### getEnvelopeCommand

protected String getEnvelopeCommand()
Return the IMAP FETCH items to request in order to load all the "envelope" data. Subclasses can override this method to fetch more data when FetchProfile.Item.ENVELOPE is requested.

Returns:
  the IMAP FETCH items to request
Since:
  JavaMail 1.4.6

### newIMAPMessage

protected IMAPMessage newIMAPMessage(int msgnum)
Create a new IMAPMessage object to represent the given message number. Subclasses of IMAPFolder may override this method to create a subclass of IMAPMessage.

Parameters:
  `msgnum` - the message sequence number
Returns:
  the new IMAPMessage object
Since:
  JavaMail 1.4.6

### 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` - for other failures
See Also:
  - `Message.setFlags(javax.mail.Flags, boolean)`
  - `MessageChangedEvent`

### setFlags

public void setFlags(int start, int end, Flags flag, boolean value) throws MessagingException
Set the specified flags for the given range of message numbers.

Overrides:
  `setFlags` in class `Folder`
Parameters:
  `start` - the number of the first message
  `end` - the number of the last message
  `flag` - Flags object containing the flags to be set
  `value` - set the flags to this boolean value
Throws:
  `MessagingException` - for other failures
See Also:
  - `Message.setFlags(javax.mail.Flags, boolean)`
  - `MessageChangedEvent`

### setFlags

public void setFlags(int[] msgnums, Flags flag, boolean value) throws MessagingException
Set the specified flags for the given array of message numbers.

Overrides:
  `setFlags` in class `Folder`
Parameters:
  `msgnums` - the array of message numbers
  `flag` - Flags object containing the flags to be set
  `value` - set the flags to this boolean value
Throws:
  `MessagingException` - for other failures
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` - for other failures
See Also:
  - `ConnectionEvent`

### forceClose

public void forceClose() throws MessagingException
Close this folder without waiting for the server.

Throws:
  `MessagingException` - for failures

### 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` - for other failures

### 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` - for other failures

### 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` - for other failures

### 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` - for other failures

### 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` - for other failures
See Also:
  - `Folder.getMessageCount()`
  - `Folder.fetch(javax.mail.Message[], javax.mail.FetchProfile)`

### getMessages

public Message[] getMessages() throws MessagingException
Get all Message objects from this Folder. Returns an empty array if the folder is empty. Clients can use Message objects (instead of sequence numbers) as references to the messages within a folder; this method supplies the Message objects to the client. Folder implementations are expected to provide light-weight Message objects, which get filled on demand.

This implementation invokes `getMessageCount()` to get the current message count and then uses `getMessage()` to get Message objects from 1 till the message count.

Overrides:
  `getMessages` in class `Folder`
Returns:
  array of Message objects, empty array if folder is empty.
Throws:
  `FolderNotFoundException` - if this folder does not exist.
  `MessagingException` - for other failures
See Also:
  - `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 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 4315.

Parameters:
  `msgs` - the messages to append
Returns:
  array of AppendUID objects
Throws:
  `MessagingException` - for failures
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 4315.

Parameters:
  `msgs` - the messages to add
Returns:
  the messages in this folder
Throws:
  `MessagingException` - for failures
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` - for other failures
See Also:
  - `Folder.appendMessages(javax.mail.Message[])`

### copyUIDMessages

public AppendUID[] copyUIDMessages(Message[] msgs, Folder folder) throws MessagingException
Copy the specified messages from this folder, to the specified destination. 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 copied message.

Depends on the COPYUID response code defined by the UIDPLUS extension - RFC 4315.

Parameters:
  `msgs` - the messages to copy
  `folder` - the folder to copy the messages to
Returns:
  array of AppendUID objects
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.5.1

### moveMessages

public void moveMessages(Message[] msgs, Folder folder) throws MessagingException
Move the specified messages from this folder, to the specified destination. Depends on the MOVE extension (RFC 6851).

Parameters:
  `msgs` - the messages to move
  `folder` - the folder to move the messages to
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.5.4

### moveUIDMessages

public AppendUID[] moveUIDMessages(Message[] msgs, Folder folder) throws MessagingException
Move the specified messages from this folder, to the specified destination. 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 moved message.

Depends on the MOVE extension (RFC 6851) and the COPYUID response code defined by the UIDPLUS extension (RFC 4315).

Parameters:
  `msgs` - the messages to move
  `folder` - the folder to move the messages to
Returns:
  array of AppendUID objects
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.5.4

### 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` - for other failures
See Also:
  - `Message.isExpunged()`
  - `MessageCountEvent`

### expunge

public Message[] expunge(Message[] msgs) throws MessagingException
Expunge the indicated messages, which must have been marked as DELETED. Depends on the UIDPLUS extension - RFC 4315.

Parameters:
  `msgs` - the messages to expunge
Returns:
  the expunged messages
Throws:
  `MessagingException` - for failures

### search

public Message[] search(SearchTerm term) throws MessagingException
Search whole folder for messages matching the given term. If the property `mail.imap.throwsearchexception` is true, and the search term is too complex for the IMAP protocol, SearchException is thrown. Otherwise, if the search term is too complex, `super.search` is called to do the search on the client.

Overrides:
  `search` in class `Folder`
Parameters:
  `term` - the search term
Returns:
  the messages that match
Throws:
  `SearchException` - if mail.imap.throwsearchexception is true and the search is too complex for the IMAP protocol
  `MessagingException` - for other failures
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` - for other failures
See Also:
  - `SearchTerm`

### getSortedMessages

public Message[] getSortedMessages(SortTerm[] term) throws MessagingException
Sort the messages in the folder according to the sort criteria. The messages are returned in the sorted order, but the order of the messages in the folder is not changed.

Depends on the SORT extension - RFC 5256.

Parameters:
  `term` - the SortTerms
Returns:
  the messages in sorted order
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.4.4

### getSortedMessages

public Message[] getSortedMessages(SortTerm[] term, SearchTerm sterm) throws MessagingException
Sort the messages in the folder according to the sort criteria. The messages are returned in the sorted order, but the order of the messages in the folder is not changed. Only messages matching the search criteria are considered.

Depends on the SORT extension - RFC 5256.

Parameters:
  `term` - the SortTerms
  `sterm` - the SearchTerm
Returns:
  the messages in sorted order
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.4.4

### 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` - for failures

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

Specified by:
  `getUIDNext` in interface `UIDFolder`
Returns:
  the UIDNEXT value, or -1 if unknown
Throws:
  `MessagingException` - for failures
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` - for failures

### 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` - for failures
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` - for failures

### 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` - for other failures

### getUIDNotSticky

public boolean getUIDNotSticky() throws MessagingException
Servers that support the UIDPLUS extension (RFC 4315) may indicate that this folder does not support persistent UIDs; that is, UIDVALIDITY will be different each time the folder is opened. Only valid when the folder is open.

Returns:
  true if UIDs are not sticky
Throws:
  `MessagingException` - for failures
  `IllegalStateException` - if the folder isn't open
Since:
  JavaMail 1.6.0
See Also:
  - "RFC 4315"

### getHighestModSeq

public long getHighestModSeq() throws MessagingException
Returns the HIGHESTMODSEQ for this folder.

Returns:
  the HIGHESTMODSEQ value
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.5.1
See Also:
  - "RFC 4551"

### getMessagesByUIDChangedSince

public Message[] getMessagesByUIDChangedSince(long start, long end, long modseq) throws MessagingException
Get the messages that have been changed since the given MODSEQ value. Also, prefetch the flags for the messages.

The server must support the CONDSTORE extension.

Parameters:
  `start` - the first message number
  `end` - the last message number
  `modseq` - the MODSEQ value
Returns:
  the changed messages
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.5.1
See Also:
  - "RFC 4551"

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

Returns:
  array of attributes for this folder
Throws:
  `MessagingException` - for failures
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.

Parameters:
  `once` - only do one notification?
Throws:
  `MessagingException` - if the server doesn't support the IDLE extension
  `IllegalStateException` - if the folder isn't open
Since:
  JavaMail 1.4.3

### id

public Map<String,String> id(Map<String,String> clientParams) throws MessagingException
Send the IMAP ID command (if supported by the server) and return the result from the server. The ID command identfies the client to the server and returns information about the server to the client. See RFC 2971. The returned Map is unmodifiable.

Parameters:
  `clientParams` - a Map of keys and values identifying the client
Returns:
  a Map of keys and values identifying the server
Throws:
  `MessagingException` - if the server doesn't support the ID extension
Since:
  JavaMail 1.5.1

### getStatusItem

public long getStatusItem(String item) throws MessagingException
Use the IMAP STATUS command to get the indicated item. The STATUS item may be a standard item such as "RECENT" or "UNSEEN", or may be a server-specific item. The folder must be closed. If the item is not found, or the folder is open, -1 is returned.

Parameters:
  `item` - the STATUS item to fetch
Returns:
  the value of the STATUS item, or -1
Throws:
  `MessagingException` - for errors
Since:
  JavaMail 1.5.2

### handleResponse

public void handleResponse(Response r)
The response handler. This is the callback routine that is invoked by the protocol layer.

Specified by:
  `handleResponse` in interface `ResponseHandler`

### getStoreProtocol

protected IMAPProtocol getStoreProtocol() throws 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);
>          }

ASSERT: Must be called with this folder's synchronization lock held.

Returns:
  the IMAPProtocol for the Store's connection
Throws:
  `ProtocolException` - for protocol errors

### throwClosedException

protected void throwClosedException(ConnectionException cex) throws FolderClosedException, StoreClosedException
Throw the appropriate 'closed' exception.

Parameters:
  `cex` - the ConnectionException
Throws:
  `FolderClosedException` - if the folder is closed
  `StoreClosedException` - if the store is closed

### getProtocol

protected IMAPProtocol getProtocol() throws ProtocolException
Return the IMAPProtocol object for this folder.

This method will block if necessary to wait for an IDLE command to finish.

Returns:
  the IMAPProtocol object used when the folder is open
Throws:
  `ProtocolException` - for protocol errors

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

Parameters:
  `cmd` - the protocol command
Returns:
  the result of the command
Throws:
  `MessagingException` - for failures

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

Throws:
  `ProtocolException`

### releaseStoreProtocol

protected void releaseStoreProtocol(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. ASSERT: Must be called with this folder's synchronization lock held.

Parameters:
  `p` - the IMAPProtocol object

### releaseProtocol

protected void releaseProtocol(boolean returnToPool)
Release the protocol object. ASSERT: This method must be called only when holding the messageCacheLock

Parameters:
  `returnToPool` - return the protocol object to the pool?

### keepConnectionAlive

protected void keepConnectionAlive(boolean keepStoreAlive) throws ProtocolException
Issue a noop command for the connection if the connection has not been used in more than a second. If `keepStoreAlive` is true, also issue a noop over the store's connection. ASSERT: This method must be called only when holding the messageCacheLock

Parameters:
  `keepStoreAlive` - keep the Store alive too?
Throws:
  `ProtocolException` - for protocol errors

### getMessageBySeqNumber

protected IMAPMessage getMessageBySeqNumber(int seqnum)
Get the message object for the given sequence number. If none found, null is returned. ASSERT: This method must be called only when holding the messageCacheLock

Parameters:
  `seqnum` - the message sequence number
Returns:
  the IMAPMessage object

### getMessagesBySeqNumbers

protected IMAPMessage[] getMessagesBySeqNumbers(int[] seqnums)
Get the message objects for the given sequence numbers. ASSERT: This method must be called only when holding the messageCacheLock

Parameters:
  `seqnums` - the array of message sequence numbers
Returns:
  the IMAPMessage objects
Since:
  JavaMail 1.5.3