Package com.sun.mail.imap

Class IMAPFolder

java.lang.Object

javax.mail.Folder

com.sun.mail.imap.IMAPFolder

All Implemented Interfaces:

ResponseHandler, java.lang.AutoCloseable, javax.mail.UIDFolder

Direct Known Subclasses:

DefaultFolder

public class IMAPFolder
extends javax.mail.Folder
implements javax.mail.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.

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 java.lang.String[]	attributes
protected javax.mail.Flags	availableFlags
protected boolean	exists
protected java.lang.String	fullName
protected boolean	isNamespace
protected com.sun.mail.util.MailLogger	logger
protected MessageCache	messageCache
protected java.lang.Object	messageCacheLock
protected java.lang.String	name
protected javax.mail.Flags	permanentFlags
protected com.sun.mail.imap.protocol.IMAPProtocol	protocol
protected char	separator
protected int	type
protected java.util.Hashtable<java.lang.Long,IMAPMessage>	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, MAXUID

Constructor Summary

Constructors

Modifier	Constructor	Description
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, java.lang.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(javax.mail.event.MessageCountListener l)
javax.mail.Message[]	addMessages(javax.mail.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(javax.mail.Message[] msgs)	Append the given messages into this folder.
AppendUID[]	appendUIDMessages(javax.mail.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(javax.mail.Message[] msgs, javax.mail.Folder folder)	Copy the specified messages from this folder, to the specified destination.
AppendUID[]	copyUIDMessages(javax.mail.Message[] msgs, javax.mail.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.
javax.mail.Message[]	expunge()	Expunge all messages marked as DELETED.
javax.mail.Message[]	expunge(javax.mail.Message[] msgs)	Expunge the indicated messages, which must have been marked as DELETED.
void	fetch(javax.mail.Message[] msgs, javax.mail.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.
java.lang.String[]	getAttributes()	Get the attributes that the IMAP server returns with the LIST response.
int	getDeletedMessageCount()	Get the deleted message count.
protected java.lang.String	getEnvelopeCommand()	Return the IMAP FETCH items to request in order to load all the "envelope" data.
javax.mail.Folder	getFolder(java.lang.String name)	Get the named subfolder.
java.lang.String	getFullName()	Get the fullname of this folder.
long	getHighestModSeq()	Returns the HIGHESTMODSEQ for this folder.
javax.mail.Message	getMessage(int msgnum)	Get the specified message.
protected IMAPMessage	getMessageBySeqNumber(int seqnum)	Get the message object for the given sequence number.
javax.mail.Message	getMessageByUID(long uid)	Get the Message corresponding to the given UID.
int	getMessageCount()	Get the total message count.
javax.mail.Message[]	getMessages()
protected IMAPMessage[]	getMessagesBySeqNumbers(int[] seqnums)	Get the message objects for the given sequence numbers.
javax.mail.Message[]	getMessagesByUID(long[] uids)	Get the Messages specified by the given array.
javax.mail.Message[]	getMessagesByUID(long start, long end)	Get the Messages specified by the given range.
javax.mail.Message[]	getMessagesByUIDChangedSince(long start, long end, long modseq)	Get the messages that have been changed since the given MODSEQ value.
java.lang.String	getName()	Get the name of this folder.
int	getNewMessageCount()	Get the new message count.
javax.mail.Folder	getParent()	Get this folder's parent.
javax.mail.Flags	getPermanentFlags()	Return the permanent flags supported by the server.
protected com.sun.mail.imap.protocol.IMAPProtocol	getProtocol()	Return the IMAPProtocol object for this folder.
javax.mail.Quota[]	getQuota()	Get the quotas for the quotaroot associated with this folder.
char	getSeparator()	Get the separator character.
javax.mail.Message[]	getSortedMessages(SortTerm[] term)	Sort the messages in the folder according to the sort criteria.
javax.mail.Message[]	getSortedMessages(SortTerm[] term, javax.mail.search.SearchTerm sterm)	Sort the messages in the folder according to the sort criteria.
long	getStatusItem(java.lang.String item)	Use the IMAP STATUS command to get the indicated item.
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(javax.mail.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.
java.util.Map<java.lang.String,java.lang.String>	id(java.util.Map<java.lang.String,java.lang.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.
javax.mail.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.
javax.mail.Folder[]	listSubscribed(java.lang.String pattern)	List all subscribed subfolders matching the specified pattern.
void	moveMessages(javax.mail.Message[] msgs, javax.mail.Folder folder)	Move the specified messages from this folder, to the specified destination.
AppendUID[]	moveUIDMessages(javax.mail.Message[] msgs, javax.mail.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.
java.util.List<javax.mail.event.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(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(javax.mail.Folder f)	Rename this folder.
javax.mail.Message[]	search(javax.mail.search.SearchTerm term)	Search whole folder for messages matching the given term.
javax.mail.Message[]	search(javax.mail.search.SearchTerm term, javax.mail.Message[] msgs)	Search the folder for messages matching the given term.
void	setFlags(int[] msgnums, javax.mail.Flags flag, boolean value)	Set the specified flags for the given array of message numbers.
void	setFlags(int start, int end, javax.mail.Flags flag, boolean value)	Set the specified flags for the given range of message numbers.
void	setFlags(javax.mail.Message[] msgs, javax.mail.Flags flag, boolean value)	Set the specified flags for the given array of messages.
void	setQuota(javax.mail.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 Detail

fullName

protected volatile java.lang.String fullName

name

protected java.lang.String name

type

protected int type

separator

protected char separator

availableFlags

protected javax.mail.Flags availableFlags

permanentFlags

protected javax.mail.Flags permanentFlags

exists

protected volatile boolean exists

isNamespace

protected boolean isNamespace

attributes

protected volatile java.lang.String[] attributes

protocol

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

messageCache

protected MessageCache messageCache

messageCacheLock

protected final java.lang.Object messageCacheLock

uidTable

protected java.util.Hashtable<java.lang.Long,IMAPMessage> uidTable

UNKNOWN_SEPARATOR

protected static final char UNKNOWN_SEPARATOR

See Also:

Constant Field Values

logger

protected com.sun.mail.util.MailLogger logger

Constructor Detail

IMAPFolder

protected IMAPFolder(java.lang.String fullName,
                     char separator,
                     IMAPStore store,
                     java.lang.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(com.sun.mail.imap.protocol.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 Detail

checkExists

protected void checkExists()
                    throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

checkClosed

protected void checkClosed()

checkOpened

protected void checkOpened()
                    throws javax.mail.FolderClosedException

Throws:

javax.mail.FolderClosedException

checkRange

protected void checkRange(int msgno)
                   throws javax.mail.MessagingException

Throws:

javax.mail.MessagingException

getName

public java.lang.String getName()

Get the name of this folder.

Specified by:

getName in class javax.mail.Folder

getFullName

public java.lang.String getFullName()

Get the fullname of this folder.

Specified by:

getFullName in class javax.mail.Folder

getParent

public javax.mail.Folder getParent()
                            throws javax.mail.MessagingException

Get this folder's parent.

Specified by:

getParent in class javax.mail.Folder

Throws:

javax.mail.MessagingException

exists

public boolean exists()
               throws javax.mail.MessagingException

Check whether this folder really exists on the server.

Specified by:

exists in class javax.mail.Folder

Throws:

javax.mail.MessagingException

list

public javax.mail.Folder[] list(java.lang.String pattern)
                         throws javax.mail.MessagingException

List all subfolders matching the specified pattern.

Specified by:

list in class javax.mail.Folder

Throws:

javax.mail.MessagingException

listSubscribed

public javax.mail.Folder[] listSubscribed(java.lang.String pattern)
                                   throws javax.mail.MessagingException

List all subscribed subfolders matching the specified pattern.

Overrides:

listSubscribed in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getSeparator

public char getSeparator()
                  throws javax.mail.MessagingException

Get the separator character.

Specified by:

getSeparator in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getType

public int getType()
            throws javax.mail.MessagingException

Get the type of this folder.

Specified by:

getType in class javax.mail.Folder

Throws:

javax.mail.MessagingException

isSubscribed

public boolean isSubscribed()

Check whether this folder is subscribed.

Overrides:

isSubscribed in class javax.mail.Folder

setSubscribed

public void setSubscribed(boolean subscribe)
                   throws javax.mail.MessagingException

Subscribe/Unsubscribe this folder.

Overrides:

setSubscribed in class javax.mail.Folder

Throws:

javax.mail.MessagingException

create

public boolean create(int type)
               throws javax.mail.MessagingException

Create this folder, with the specified type.

Specified by:

create in class javax.mail.Folder

Throws:

javax.mail.MessagingException

hasNewMessages

public boolean hasNewMessages()
                       throws javax.mail.MessagingException

Check whether this folder has new messages.

Specified by:

hasNewMessages in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getFolder

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

Get the named subfolder.

Specified by:

getFolder in class javax.mail.Folder

Throws:

javax.mail.MessagingException

delete

public boolean delete(boolean recurse)
               throws javax.mail.MessagingException

Delete this folder.

Specified by:

delete in class javax.mail.Folder

Throws:

javax.mail.MessagingException

renameTo

public boolean renameTo(javax.mail.Folder f)
                 throws javax.mail.MessagingException

Rename this folder.

Specified by:

renameTo in class javax.mail.Folder

Throws:

javax.mail.MessagingException

open

public void open(int mode)
          throws javax.mail.MessagingException

Open this folder in the given mode.

Specified by:

open in class javax.mail.Folder

Throws:

javax.mail.MessagingException

open

public java.util.List<javax.mail.event.MailEvent> open(int mode,
                                                       ResyncData rd)
                                                throws javax.mail.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:

javax.mail.MessagingException - if the open fails

Since:

JavaMail 1.5.1

fetch

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

Prefetch attributes, based on the given FetchProfile.

Overrides:

fetch in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getEnvelopeCommand

protected java.lang.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(javax.mail.Message[] msgs,
                     javax.mail.Flags flag,
                     boolean value)
              throws javax.mail.MessagingException

Set the specified flags for the given array of messages.

Overrides:

setFlags in class javax.mail.Folder

Throws:

javax.mail.MessagingException

setFlags

public void setFlags(int start,
                     int end,
                     javax.mail.Flags flag,
                     boolean value)
              throws javax.mail.MessagingException

Set the specified flags for the given range of message numbers.

Overrides:

setFlags in class javax.mail.Folder

Throws:

javax.mail.MessagingException

setFlags

public void setFlags(int[] msgnums,
                     javax.mail.Flags flag,
                     boolean value)
              throws javax.mail.MessagingException

Set the specified flags for the given array of message numbers.

Overrides:

setFlags in class javax.mail.Folder

Throws:

javax.mail.MessagingException

close

public void close(boolean expunge)
           throws javax.mail.MessagingException

Close this folder.

Specified by:

close in class javax.mail.Folder

Throws:

javax.mail.MessagingException

forceClose

public void forceClose()
                throws javax.mail.MessagingException

Close this folder without waiting for the server.

Throws:

javax.mail.MessagingException - for failures

isOpen

public boolean isOpen()

Check whether this connection is really open.

Specified by:

isOpen in class javax.mail.Folder

getPermanentFlags

public javax.mail.Flags getPermanentFlags()

Return the permanent flags supported by the server.

Specified by:

getPermanentFlags in class javax.mail.Folder

getMessageCount

public int getMessageCount()
                    throws javax.mail.MessagingException

Get the total message count.

Specified by:

getMessageCount in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getNewMessageCount

public int getNewMessageCount()
                       throws javax.mail.MessagingException

Get the new message count.

Overrides:

getNewMessageCount in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getUnreadMessageCount

public int getUnreadMessageCount()
                          throws javax.mail.MessagingException

Get the unread message count.

Overrides:

getUnreadMessageCount in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getDeletedMessageCount

public int getDeletedMessageCount()
                           throws javax.mail.MessagingException

Get the deleted message count.

Overrides:

getDeletedMessageCount in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getMessage

public javax.mail.Message getMessage(int msgnum)
                              throws javax.mail.MessagingException

Get the specified message.

Specified by:

getMessage in class javax.mail.Folder

Throws:

javax.mail.MessagingException

getMessages

public javax.mail.Message[] getMessages()
                                 throws javax.mail.MessagingException

Overrides:

getMessages in class javax.mail.Folder

Throws:

javax.mail.MessagingException

appendMessages

public void appendMessages(javax.mail.Message[] msgs)
                    throws javax.mail.MessagingException

Append the given messages into this folder.

Specified by:

appendMessages in class javax.mail.Folder

Throws:

javax.mail.MessagingException

appendUIDMessages

public AppendUID[] appendUIDMessages(javax.mail.Message[] msgs)
                              throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.4

addMessages

public javax.mail.Message[] addMessages(javax.mail.Message[] msgs)
                                 throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.4

copyMessages

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

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

Overrides:

copyMessages in class javax.mail.Folder

Throws:

javax.mail.MessagingException

copyUIDMessages

public AppendUID[] copyUIDMessages(javax.mail.Message[] msgs,
                                   javax.mail.Folder folder)
                            throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.5.1

moveMessages

public void moveMessages(javax.mail.Message[] msgs,
                         javax.mail.Folder folder)
                  throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.5.4

moveUIDMessages

public AppendUID[] moveUIDMessages(javax.mail.Message[] msgs,
                                   javax.mail.Folder folder)
                            throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.5.4

expunge

public javax.mail.Message[] expunge()
                             throws javax.mail.MessagingException

Expunge all messages marked as DELETED.

Specified by:

expunge in class javax.mail.Folder

Throws:

javax.mail.MessagingException

expunge

public javax.mail.Message[] expunge(javax.mail.Message[] msgs)
                             throws javax.mail.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:

javax.mail.MessagingException - for failures

search

public javax.mail.Message[] search(javax.mail.search.SearchTerm term)
                            throws javax.mail.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 javax.mail.Folder

Parameters:

term - the search term

Returns:

the messages that match

Throws:

javax.mail.search.SearchException - if mail.imap.throwsearchexception is true and the search is too complex for the IMAP protocol

javax.mail.MessagingException - for other failures

search

public javax.mail.Message[] search(javax.mail.search.SearchTerm term,
                                   javax.mail.Message[] msgs)
                            throws javax.mail.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 javax.mail.Folder

Throws:

javax.mail.MessagingException

getSortedMessages

public javax.mail.Message[] getSortedMessages(SortTerm[] term)
                                       throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.4.4

getSortedMessages

public javax.mail.Message[] getSortedMessages(SortTerm[] term,
                                              javax.mail.search.SearchTerm sterm)
                                       throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.4.4

addMessageCountListener

public void addMessageCountListener(javax.mail.event.MessageCountListener l)

Overrides:

addMessageCountListener in class javax.mail.Folder

getUIDValidity

public long getUIDValidity()
                    throws javax.mail.MessagingException

Returns the UIDValidity for this folder.

Specified by:

getUIDValidity in interface javax.mail.UIDFolder

Throws:

javax.mail.MessagingException

getUIDNext

public long getUIDNext()
                throws javax.mail.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 javax.mail.UIDFolder

Returns:

the UIDNEXT value, or -1 if unknown

Throws:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.3.3

getMessageByUID

public javax.mail.Message getMessageByUID(long uid)
                                   throws javax.mail.MessagingException

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

Specified by:

getMessageByUID in interface javax.mail.UIDFolder

Throws:

javax.mail.MessagingException

getMessagesByUID

public javax.mail.Message[] getMessagesByUID(long start,
                                             long end)
                                      throws javax.mail.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 javax.mail.UIDFolder

Throws:

javax.mail.MessagingException

getMessagesByUID

public javax.mail.Message[] getMessagesByUID(long[] uids)
                                      throws javax.mail.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 javax.mail.UIDFolder

Throws:

javax.mail.MessagingException

getUID

public long getUID(javax.mail.Message message)
            throws javax.mail.MessagingException

Get the UID for the specified message.

Specified by:

getUID in interface javax.mail.UIDFolder

Throws:

javax.mail.MessagingException

getUIDNotSticky

public boolean getUIDNotSticky()
                        throws javax.mail.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:

javax.mail.MessagingException - for failures

java.lang.IllegalStateException - if the folder isn't open

Since:

JavaMail 1.6.0

See Also:

"RFC 4315"

getHighestModSeq

public long getHighestModSeq()
                      throws javax.mail.MessagingException

Returns the HIGHESTMODSEQ for this folder.

Returns:

the HIGHESTMODSEQ value

Throws:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.5.1

See Also:

"RFC 4551"

getMessagesByUIDChangedSince

public javax.mail.Message[] getMessagesByUIDChangedSince(long start,
                                                         long end,
                                                         long modseq)
                                                  throws javax.mail.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:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.5.1

See Also:

"RFC 4551"

getQuota

public javax.mail.Quota[] getQuota()
                            throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the QUOTA extension

setQuota

public void setQuota(javax.mail.Quota quota)
              throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the QUOTA extension

getACL

public ACL[] getACL()
             throws javax.mail.MessagingException

Get the access control list entries for this folder.

Returns:

array of access control list entries

Throws:

javax.mail.MessagingException - if the server doesn't support the ACL extension

addACL

public void addACL(ACL acl)
            throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the ACL extension

removeACL

public void removeACL(java.lang.String name)
               throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the ACL extension

addRights

public void addRights(ACL acl)
               throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the ACL extension

removeRights

public void removeRights(ACL acl)
                  throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the ACL extension

listRights

public Rights[] listRights(java.lang.String name)
                    throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the ACL extension

myRights

public Rights myRights()
                throws javax.mail.MessagingException

Get the rights allowed to the currently authenticated user.

Returns:

the rights granted to the current user

Throws:

javax.mail.MessagingException - if the server doesn't support the ACL extension

getAttributes

public java.lang.String[] getAttributes()
                                 throws javax.mail.MessagingException

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

Returns:

array of attributes for this folder

Throws:

javax.mail.MessagingException - for failures

Since:

JavaMail 1.3.3

idle

public void idle()
          throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the IDLE extension

java.lang.IllegalStateException - if the folder isn't open

Since:

JavaMail 1.4.1

idle

public void idle(boolean once)
          throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the IDLE extension

java.lang.IllegalStateException - if the folder isn't open

Since:

JavaMail 1.4.3

id

public java.util.Map<java.lang.String,java.lang.String> id(java.util.Map<java.lang.String,java.lang.String> clientParams)
                                                          throws javax.mail.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:

javax.mail.MessagingException - if the server doesn't support the ID extension

Since:

JavaMail 1.5.1

getStatusItem

public long getStatusItem(java.lang.String item)
                   throws javax.mail.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:

javax.mail.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 com.sun.mail.imap.protocol.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 javax.mail.FolderClosedException,
                                    javax.mail.StoreClosedException

Throw the appropriate 'closed' exception.

Parameters:

cex - the ConnectionException

Throws:

javax.mail.FolderClosedException - if the folder is closed

javax.mail.StoreClosedException - if the store is closed

getProtocol

protected com.sun.mail.imap.protocol.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 java.lang.Object doCommand(IMAPFolder.ProtocolCommand cmd)
                           throws javax.mail.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:

javax.mail.MessagingException - for failures

doOptionalCommand

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

Throws:

javax.mail.MessagingException

doCommandIgnoreFailure

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

Throws:

javax.mail.MessagingException

doProtocolCommand

protected java.lang.Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd)
                                      throws ProtocolException

Throws:

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