public class IMAPFolder extends Folder implements UIDFolder, ResponseHandler
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.
Modifier and Type | Class and 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.
|
HOLDS_FOLDERS, HOLDS_MESSAGES, READ_ONLY, READ_WRITE
Modifier and Type | Method and 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.
|
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.
|
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) |
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.
|
java.lang.String[] |
getAttributes()
Get the attributes that the IMAP server returns with the
LIST response.
|
int |
getDeletedMessageCount()
Get the deleted message count.
|
Folder |
getFolder(java.lang.String name)
Get the named subfolder.
|
java.lang.String |
getFullName()
Get the fullname of this folder.
|
long |
getHighestModSeq()
Returns the HIGHESTMODSEQ for this folder.
|
Message |
getMessage(int msgnum)
Get the specified message.
|
Message |
getMessageByUID(long uid)
Get the Message corresponding to the given UID.
|
int |
getMessageCount()
Get the total message count.
|
Message[] |
getMessages()
Get all Message objects from this Folder.
|
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.
|
java.lang.String |
getName()
Get the name of this folder.
|
int |
getNewMessageCount()
Get the new message count.
|
Folder |
getParent()
Get this folder's parent.
|
Flags |
getPermanentFlags()
Return the permanent flags supported by the server.
|
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(java.lang.String item)
Use the IMAP STATUS command to get the indicated item.
|
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.
|
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.
|
Folder[] |
list(java.lang.String pattern)
List all subfolders matching the specified pattern.
|
Rights[] |
listRights(java.lang.String name)
Get all the rights that may be allowed to the given identifier.
|
Folder[] |
listSubscribed(java.lang.String pattern)
List all subscribed subfolders matching the specified pattern.
|
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.
|
void |
open(int mode)
Open this folder in the given mode.
|
java.util.List<MailEvent> |
open(int mode,
ResyncData rd)
Open this folder in the given mode, with the given
resynchronization data.
|
void |
removeACL(java.lang.String name)
Remove any access control list entry for the given identifier
from the access control list for this folder.
|
void |
removeRights(ACL acl)
Remove the rights specified in the ACL from the entry for the
identifier specified in the ACL.
|
boolean |
renameTo(Folder f)
Rename this folder.
|
Message[] |
search(SearchTerm term)
Search whole folder for messages matching the given term.
|
Message[] |
search(SearchTerm term,
Message[] msgs)
Search the folder for messages matching the given term.
|
void |
setFlags(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.
|
addConnectionListener, addFolderListener, addMessageChangedListener, close, getMessages, getMessages, getMode, getStore, getURLName, list, listSubscribed, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, toString
public java.lang.String getName()
public java.lang.String getFullName()
getFullName
in class Folder
public Folder getParent() throws MessagingException
getParent
in class Folder
MessagingException
- for failurespublic boolean exists() throws MessagingException
exists
in class Folder
MessagingException
- typically if the connection
to the server is lost.Folder.create(int)
public Folder[] list(java.lang.String pattern) throws MessagingException
list
in class Folder
pattern
- the match patternFolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failuresFolder.listSubscribed(java.lang.String)
public Folder[] listSubscribed(java.lang.String pattern) throws MessagingException
listSubscribed
in class Folder
pattern
- the match patternFolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failuresFolder.list(java.lang.String)
public char getSeparator() throws MessagingException
getSeparator
in class Folder
FolderNotFoundException
- if the implementation
requires the folder to exist, but it does notMessagingException
public int getType() throws MessagingException
getType
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
Folder.HOLDS_FOLDERS
,
Folder.HOLDS_MESSAGES
public boolean isSubscribed()
isSubscribed
in class Folder
public void setSubscribed(boolean subscribe) throws MessagingException
setSubscribed
in class Folder
subscribe
- true to subscribe, false to unsubscribeFolderNotFoundException
- if this folder does
not exist.MethodNotSupportedException
- if this store
does not support subscriptionMessagingException
- for other failurespublic boolean create(int type) throws MessagingException
create
in class Folder
type
- The type of this folder.MessagingException
- for failuresFolder.HOLDS_FOLDERS
,
Folder.HOLDS_MESSAGES
,
FolderEvent
public boolean hasNewMessages() throws MessagingException
hasNewMessages
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic Folder getFolder(java.lang.String name) throws MessagingException
getFolder
in class Folder
name
- name of the FolderMessagingException
- for failurespublic boolean delete(boolean recurse) throws MessagingException
delete
in class Folder
recurse
- also delete subfolders?FolderNotFoundException
- if this folder does
not existMessagingException
- for other failuresFolderEvent
public boolean renameTo(Folder f) throws MessagingException
renameTo
in class Folder
f
- a folder representing the new name for this FolderFolderNotFoundException
- if this folder does
not existMessagingException
- for other failuresFolderEvent
public void open(int mode) throws MessagingException
open
in class Folder
mode
- open the Folder READ_ONLY or READ_WRITEFolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failuresFolder.READ_ONLY
,
Folder.READ_WRITE
,
Folder.getType()
,
ConnectionEvent
public java.util.List<MailEvent> open(int mode, ResyncData rd) throws MessagingException
mode
- the open mode (Folder.READ_WRITE or Folder.READ_ONLY)rd
- the ResyncData instanceMessagingException
- if the open failspublic void fetch(Message[] msgs, FetchProfile fp) throws MessagingException
fetch
in class Folder
msgs
- fetch items for these messagesfp
- the FetchProfileMessagingException
- for other failurespublic void setFlags(Message[] msgs, Flags flag, boolean value) throws MessagingException
setFlags
in class Folder
msgs
- the array of message objectsflag
- Flags object containing the flags to be setvalue
- set the flags to this boolean valueMessagingException
- for other failuresMessage.setFlags(javax.mail.Flags, boolean)
,
MessageChangedEvent
public void setFlags(int start, int end, Flags flag, boolean value) throws MessagingException
setFlags
in class Folder
start
- the number of the first messageend
- the number of the last messageflag
- Flags object containing the flags to be setvalue
- set the flags to this boolean valueMessagingException
- for other failuresMessage.setFlags(javax.mail.Flags, boolean)
,
MessageChangedEvent
public void setFlags(int[] msgnums, Flags flag, boolean value) throws MessagingException
setFlags
in class Folder
msgnums
- the array of message numbersflag
- Flags object containing the flags to be setvalue
- set the flags to this boolean valueMessagingException
- for other failuresMessage.setFlags(javax.mail.Flags, boolean)
,
MessageChangedEvent
public void close(boolean expunge) throws MessagingException
close
in class Folder
expunge
- expunges all deleted messages if this flag is trueMessagingException
- for other failuresConnectionEvent
public void forceClose() throws MessagingException
MessagingException
- for failurespublic boolean isOpen()
public Flags getPermanentFlags()
getPermanentFlags
in class Folder
public int getMessageCount() throws MessagingException
getMessageCount
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic int getNewMessageCount() throws MessagingException
getNewMessageCount
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic int getUnreadMessageCount() throws MessagingException
getUnreadMessageCount
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic int getDeletedMessageCount() throws MessagingException
getDeletedMessageCount
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failurespublic Message getMessage(int msgnum) throws MessagingException
getMessage
in class Folder
msgnum
- the message numberFolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failuresFolder.getMessageCount()
,
Folder.fetch(javax.mail.Message[], javax.mail.FetchProfile)
public Message[] getMessages() throws MessagingException
This implementation invokes getMessageCount()
to get
the current message count and then uses getMessage()
to get Message objects from 1 till the message count.
getMessages
in class Folder
FolderNotFoundException
- if this folder does
not exist.MessagingException
- for other failuresFolder.fetch(javax.mail.Message[], javax.mail.FetchProfile)
public void appendMessages(Message[] msgs) throws MessagingException
appendMessages
in class Folder
msgs
- array of Messages to be appendedFolderNotFoundException
- if this folder does
not exist.MessagingException
- if the append failed.public AppendUID[] appendUIDMessages(Message[] msgs) throws MessagingException
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.
msgs
- the messages to appendMessagingException
- for failurespublic Message[] addMessages(Message[] msgs) throws MessagingException
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.
msgs
- the messages to addMessagingException
- for failurespublic void copyMessages(Message[] msgs, Folder folder) throws MessagingException
copyMessages
in class Folder
msgs
- the array of message objectsfolder
- the folder to copy the messages toFolderNotFoundException
- if the destination
folder does not exist.MessagingException
- for other failuresFolder.appendMessages(javax.mail.Message[])
public AppendUID[] copyUIDMessages(Message[] msgs, Folder folder) throws MessagingException
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.
msgs
- the messages to copyfolder
- the folder to copy the messages toMessagingException
- for failurespublic void moveMessages(Message[] msgs, Folder folder) throws MessagingException
msgs
- the messages to movefolder
- the folder to move the messages toMessagingException
- for failurespublic AppendUID[] moveUIDMessages(Message[] msgs, Folder folder) throws MessagingException
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).
msgs
- the messages to movefolder
- the folder to move the messages toMessagingException
- for failurespublic Message[] expunge() throws MessagingException
expunge
in class Folder
FolderNotFoundException
- if this folder does not
existMessagingException
- for other failuresMessage.isExpunged()
,
MessageCountEvent
public Message[] expunge(Message[] msgs) throws MessagingException
msgs
- the messages to expungeMessagingException
- for failurespublic Message[] search(SearchTerm term) throws MessagingException
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.search
in class Folder
term
- the search termSearchException
- if mail.imap.throwsearchexception is
true and the search is too complex for the IMAP protocolMessagingException
- for other failuresSearchTerm
public Message[] search(SearchTerm term, Message[] msgs) throws MessagingException
search
in class Folder
term
- the search criterionmsgs
- the messages to be searchedSearchException
- if the search
term is too complex for the implementation to handle.MessagingException
- for other failuresSearchTerm
public Message[] getSortedMessages(SortTerm[] term) throws MessagingException
Depends on the SORT extension - RFC 5256.
term
- the SortTermsMessagingException
- for failurespublic Message[] getSortedMessages(SortTerm[] term, SearchTerm sterm) throws MessagingException
Depends on the SORT extension - RFC 5256.
term
- the SortTermssterm
- the SearchTermMessagingException
- for failurespublic void addMessageCountListener(MessageCountListener l)
Folder
The implementation provided here adds this listener to an internal list of MessageCountListeners.
addMessageCountListener
in class Folder
l
- the Listener for MessageCount eventsMessageCountEvent
public long getUIDValidity() throws MessagingException
getUIDValidity
in interface UIDFolder
MessagingException
- for failurespublic long getUIDNext() throws MessagingException
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.
getUIDNext
in interface UIDFolder
MessagingException
- for failurespublic Message getMessageByUID(long uid) throws MessagingException
null
is returned.getMessageByUID
in interface UIDFolder
uid
- UID for the desired messagenull
is returned
if no message corresponding to this UID is obtained.MessagingException
- for failurespublic Message[] getMessagesByUID(long start, long end) throws MessagingException
Returns Message objects for all valid messages in this range. Returns an empty array if no messages are found.
getMessagesByUID
in interface UIDFolder
start
- start UIDend
- end UIDMessagingException
- for failuresUIDFolder.LASTUID
public Message[] getMessagesByUID(long[] uids) throws MessagingException
uids.length()
elements are returned.
If any UID in the array is invalid, a null
entry
is returned for that element.
getMessagesByUID
in interface UIDFolder
uids
- array of UIDsMessagingException
- for failurespublic long getUID(Message message) throws MessagingException
getUID
in interface UIDFolder
message
- Message from this folderMessagingException
- for other failurespublic boolean getUIDNotSticky() throws MessagingException
MessagingException
- for failuresjava.lang.IllegalStateException
- if the folder isn't openpublic long getHighestModSeq() throws MessagingException
MessagingException
- for failurespublic Message[] getMessagesByUIDChangedSince(long start, long end, long modseq) throws MessagingException
The server must support the CONDSTORE extension.
start
- the first message numberend
- the last message numbermodseq
- the MODSEQ valueMessagingException
- for failurespublic Quota[] getQuota() throws MessagingException
MessagingException
- if the server doesn't support the
QUOTA extensionpublic void setQuota(Quota quota) throws MessagingException
getQuota
method, but it
need not be.quota
- the quota to setMessagingException
- if the server doesn't support the
QUOTA extensionpublic ACL[] getACL() throws MessagingException
MessagingException
- if the server doesn't support the
ACL extensionpublic void addACL(ACL acl) throws MessagingException
acl
- the access control list entry to addMessagingException
- if the server doesn't support the
ACL extensionpublic void removeACL(java.lang.String name) throws MessagingException
name
- the identifier for which to remove all ACL entriesMessagingException
- if the server doesn't support the
ACL extensionpublic void addRights(ACL acl) throws MessagingException
acl
- the identifer and rights to addMessagingException
- if the server doesn't support the
ACL extensionpublic void removeRights(ACL acl) throws MessagingException
acl
- the identifer and rights to removeMessagingException
- if the server doesn't support the
ACL extensionpublic Rights[] listRights(java.lang.String name) throws MessagingException
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.
name
- the identifier to list rights forMessagingException
- if the server doesn't support the
ACL extensionpublic Rights myRights() throws MessagingException
MessagingException
- if the server doesn't support the
ACL extensionpublic java.lang.String[] getAttributes() throws MessagingException
MessagingException
- for failurespublic void idle() throws MessagingException
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.
MessagingException
- if the server doesn't support the
IDLE extensionjava.lang.IllegalStateException
- if the folder isn't openpublic void idle(boolean once) throws MessagingException
idle()
, but if once
is true, abort the
IDLE command after the first notification, to allow the caller
to process any notification synchronously.once
- only do one notification?MessagingException
- if the server doesn't support the
IDLE extensionjava.lang.IllegalStateException
- if the folder isn't openpublic java.util.Map<java.lang.String,java.lang.String> id(java.util.Map<java.lang.String,java.lang.String> clientParams) throws MessagingException
clientParams
- a Map of keys and values identifying the clientMessagingException
- if the server doesn't support the
ID extensionpublic long getStatusItem(java.lang.String item) throws MessagingException
item
- the STATUS item to fetchMessagingException
- for errorspublic void handleResponse(Response r)
handleResponse
in interface ResponseHandler
public java.lang.Object doCommand(IMAPFolder.ProtocolCommand cmd) throws MessagingException
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; } });
cmd
- the protocol commandMessagingException
- for failurespublic java.lang.Object doOptionalCommand(java.lang.String err, IMAPFolder.ProtocolCommand cmd) throws MessagingException
MessagingException
public java.lang.Object doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd) throws MessagingException
MessagingException
Copyright © 2010 - 2020 Adobe. All Rights Reserved