ResponseHandler
, java.lang.AutoCloseable
, javax.mail.UIDFolder
DefaultFolder
public class IMAPFolder extends javax.mail.Folder implements javax.mail.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 | 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.
|
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 |
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.
|
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.
|
addConnectionListener, addFolderListener, addMessageChangedListener, close, finalize, getMessages, getMessages, getMode, getStore, getURLName, list, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, notifyMessageAddedListeners, notifyMessageChangedListeners, notifyMessageRemovedListeners, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, toString
protected volatile java.lang.String fullName
protected java.lang.String name
protected int type
protected char separator
protected javax.mail.Flags availableFlags
protected javax.mail.Flags permanentFlags
protected volatile boolean exists
protected boolean isNamespace
protected volatile java.lang.String[] attributes
protected volatile com.sun.mail.imap.protocol.IMAPProtocol protocol
protected MessageCache messageCache
protected final java.lang.Object messageCacheLock
protected java.util.Hashtable<java.lang.Long,IMAPMessage> uidTable
protected static final char UNKNOWN_SEPARATOR
protected com.sun.mail.util.MailLogger logger
protected IMAPFolder(java.lang.String fullName, char separator, IMAPStore store, java.lang.Boolean isNamespace)
fullName
- fullname of this folderseparator
- the default separator character for this
folder's namespacestore
- the StoreisNamespace
- if this folder represents a namespaceprotected IMAPFolder(com.sun.mail.imap.protocol.ListInfo li, IMAPStore store)
li
- the ListInfo for this folderstore
- the store containing this folderprotected void checkExists() throws javax.mail.MessagingException
javax.mail.MessagingException
protected void checkClosed()
protected void checkOpened() throws javax.mail.FolderClosedException
javax.mail.FolderClosedException
protected void checkRange(int msgno) throws javax.mail.MessagingException
javax.mail.MessagingException
public java.lang.String getName()
getName
in class javax.mail.Folder
public java.lang.String getFullName()
getFullName
in class javax.mail.Folder
public javax.mail.Folder getParent() throws javax.mail.MessagingException
getParent
in class javax.mail.Folder
javax.mail.MessagingException
public boolean exists() throws javax.mail.MessagingException
exists
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Folder[] list(java.lang.String pattern) throws javax.mail.MessagingException
list
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Folder[] listSubscribed(java.lang.String pattern) throws javax.mail.MessagingException
listSubscribed
in class javax.mail.Folder
javax.mail.MessagingException
public char getSeparator() throws javax.mail.MessagingException
getSeparator
in class javax.mail.Folder
javax.mail.MessagingException
public int getType() throws javax.mail.MessagingException
getType
in class javax.mail.Folder
javax.mail.MessagingException
public boolean isSubscribed()
isSubscribed
in class javax.mail.Folder
public void setSubscribed(boolean subscribe) throws javax.mail.MessagingException
setSubscribed
in class javax.mail.Folder
javax.mail.MessagingException
public boolean create(int type) throws javax.mail.MessagingException
create
in class javax.mail.Folder
javax.mail.MessagingException
public boolean hasNewMessages() throws javax.mail.MessagingException
hasNewMessages
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Folder getFolder(java.lang.String name) throws javax.mail.MessagingException
getFolder
in class javax.mail.Folder
javax.mail.MessagingException
public boolean delete(boolean recurse) throws javax.mail.MessagingException
delete
in class javax.mail.Folder
javax.mail.MessagingException
public boolean renameTo(javax.mail.Folder f) throws javax.mail.MessagingException
renameTo
in class javax.mail.Folder
javax.mail.MessagingException
public void open(int mode) throws javax.mail.MessagingException
open
in class javax.mail.Folder
javax.mail.MessagingException
public java.util.List<javax.mail.event.MailEvent> open(int mode, ResyncData rd) throws javax.mail.MessagingException
mode
- the open mode (Folder.READ_WRITE or Folder.READ_ONLY)rd
- the ResyncData instancejavax.mail.MessagingException
- if the open failspublic void fetch(javax.mail.Message[] msgs, javax.mail.FetchProfile fp) throws javax.mail.MessagingException
fetch
in class javax.mail.Folder
javax.mail.MessagingException
protected java.lang.String getEnvelopeCommand()
protected IMAPMessage newIMAPMessage(int msgnum)
msgnum
- the message sequence numberpublic void setFlags(javax.mail.Message[] msgs, javax.mail.Flags flag, boolean value) throws javax.mail.MessagingException
setFlags
in class javax.mail.Folder
javax.mail.MessagingException
public void setFlags(int start, int end, javax.mail.Flags flag, boolean value) throws javax.mail.MessagingException
setFlags
in class javax.mail.Folder
javax.mail.MessagingException
public void setFlags(int[] msgnums, javax.mail.Flags flag, boolean value) throws javax.mail.MessagingException
setFlags
in class javax.mail.Folder
javax.mail.MessagingException
public void close(boolean expunge) throws javax.mail.MessagingException
close
in class javax.mail.Folder
javax.mail.MessagingException
public void forceClose() throws javax.mail.MessagingException
javax.mail.MessagingException
- for failurespublic boolean isOpen()
isOpen
in class javax.mail.Folder
public javax.mail.Flags getPermanentFlags()
getPermanentFlags
in class javax.mail.Folder
public int getMessageCount() throws javax.mail.MessagingException
getMessageCount
in class javax.mail.Folder
javax.mail.MessagingException
public int getNewMessageCount() throws javax.mail.MessagingException
getNewMessageCount
in class javax.mail.Folder
javax.mail.MessagingException
public int getUnreadMessageCount() throws javax.mail.MessagingException
getUnreadMessageCount
in class javax.mail.Folder
javax.mail.MessagingException
public int getDeletedMessageCount() throws javax.mail.MessagingException
getDeletedMessageCount
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Message getMessage(int msgnum) throws javax.mail.MessagingException
getMessage
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Message[] getMessages() throws javax.mail.MessagingException
getMessages
in class javax.mail.Folder
javax.mail.MessagingException
public void appendMessages(javax.mail.Message[] msgs) throws javax.mail.MessagingException
appendMessages
in class javax.mail.Folder
javax.mail.MessagingException
public AppendUID[] appendUIDMessages(javax.mail.Message[] msgs) throws javax.mail.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 appendjavax.mail.MessagingException
- for failurespublic javax.mail.Message[] addMessages(javax.mail.Message[] msgs) throws javax.mail.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 addjavax.mail.MessagingException
- for failurespublic void copyMessages(javax.mail.Message[] msgs, javax.mail.Folder folder) throws javax.mail.MessagingException
copyMessages
in class javax.mail.Folder
javax.mail.MessagingException
public AppendUID[] copyUIDMessages(javax.mail.Message[] msgs, javax.mail.Folder folder) throws javax.mail.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 tojavax.mail.MessagingException
- for failurespublic void moveMessages(javax.mail.Message[] msgs, javax.mail.Folder folder) throws javax.mail.MessagingException
msgs
- the messages to movefolder
- the folder to move the messages tojavax.mail.MessagingException
- for failurespublic AppendUID[] moveUIDMessages(javax.mail.Message[] msgs, javax.mail.Folder folder) throws javax.mail.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 tojavax.mail.MessagingException
- for failurespublic javax.mail.Message[] expunge() throws javax.mail.MessagingException
expunge
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Message[] expunge(javax.mail.Message[] msgs) throws javax.mail.MessagingException
msgs
- the messages to expungejavax.mail.MessagingException
- for failurespublic javax.mail.Message[] search(javax.mail.search.SearchTerm term) throws javax.mail.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 javax.mail.Folder
term
- the search termjavax.mail.search.SearchException
- if mail.imap.throwsearchexception is
true and the search is too complex for the IMAP protocoljavax.mail.MessagingException
- for other failurespublic javax.mail.Message[] search(javax.mail.search.SearchTerm term, javax.mail.Message[] msgs) throws javax.mail.MessagingException
search
in class javax.mail.Folder
javax.mail.MessagingException
public javax.mail.Message[] getSortedMessages(SortTerm[] term) throws javax.mail.MessagingException
Depends on the SORT extension - RFC 5256.
term
- the SortTermsjavax.mail.MessagingException
- for failurespublic javax.mail.Message[] getSortedMessages(SortTerm[] term, javax.mail.search.SearchTerm sterm) throws javax.mail.MessagingException
Depends on the SORT extension - RFC 5256.
term
- the SortTermssterm
- the SearchTermjavax.mail.MessagingException
- for failurespublic void addMessageCountListener(javax.mail.event.MessageCountListener l)
addMessageCountListener
in class javax.mail.Folder
public long getUIDValidity() throws javax.mail.MessagingException
getUIDValidity
in interface javax.mail.UIDFolder
javax.mail.MessagingException
public long getUIDNext() throws javax.mail.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 javax.mail.UIDFolder
javax.mail.MessagingException
- for failurespublic javax.mail.Message getMessageByUID(long uid) throws javax.mail.MessagingException
null
is returned.getMessageByUID
in interface javax.mail.UIDFolder
javax.mail.MessagingException
public javax.mail.Message[] getMessagesByUID(long start, long end) throws javax.mail.MessagingException
Returns Message objects for all valid messages in this range. Returns an empty array if no messages are found.
getMessagesByUID
in interface javax.mail.UIDFolder
javax.mail.MessagingException
public javax.mail.Message[] getMessagesByUID(long[] uids) throws javax.mail.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 javax.mail.UIDFolder
javax.mail.MessagingException
public long getUID(javax.mail.Message message) throws javax.mail.MessagingException
getUID
in interface javax.mail.UIDFolder
javax.mail.MessagingException
public boolean getUIDNotSticky() throws javax.mail.MessagingException
javax.mail.MessagingException
- for failuresjava.lang.IllegalStateException
- if the folder isn't openpublic long getHighestModSeq() throws javax.mail.MessagingException
javax.mail.MessagingException
- for failurespublic javax.mail.Message[] getMessagesByUIDChangedSince(long start, long end, long modseq) throws javax.mail.MessagingException
The server must support the CONDSTORE extension.
start
- the first message numberend
- the last message numbermodseq
- the MODSEQ valuejavax.mail.MessagingException
- for failurespublic javax.mail.Quota[] getQuota() throws javax.mail.MessagingException
javax.mail.MessagingException
- if the server doesn't support the
QUOTA extensionpublic void setQuota(javax.mail.Quota quota) throws javax.mail.MessagingException
getQuota
method, but it
need not be.quota
- the quota to setjavax.mail.MessagingException
- if the server doesn't support the
QUOTA extensionpublic ACL[] getACL() throws javax.mail.MessagingException
javax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic void addACL(ACL acl) throws javax.mail.MessagingException
acl
- the access control list entry to addjavax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic void removeACL(java.lang.String name) throws javax.mail.MessagingException
name
- the identifier for which to remove all ACL entriesjavax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic void addRights(ACL acl) throws javax.mail.MessagingException
acl
- the identifer and rights to addjavax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic void removeRights(ACL acl) throws javax.mail.MessagingException
acl
- the identifer and rights to removejavax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic Rights[] listRights(java.lang.String name) throws javax.mail.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 forjavax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic Rights myRights() throws javax.mail.MessagingException
javax.mail.MessagingException
- if the server doesn't support the
ACL extensionpublic java.lang.String[] getAttributes() throws javax.mail.MessagingException
javax.mail.MessagingException
- for failurespublic void idle() throws javax.mail.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.
javax.mail.MessagingException
- if the server doesn't support the
IDLE extensionjava.lang.IllegalStateException
- if the folder isn't openpublic void idle(boolean once) throws javax.mail.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?javax.mail.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 javax.mail.MessagingException
clientParams
- a Map of keys and values identifying the clientjavax.mail.MessagingException
- if the server doesn't support the
ID extensionpublic long getStatusItem(java.lang.String item) throws javax.mail.MessagingException
item
- the STATUS item to fetchjavax.mail.MessagingException
- for errorspublic void handleResponse(Response r)
handleResponse
in interface ResponseHandler
protected com.sun.mail.imap.protocol.IMAPProtocol getStoreProtocol() throws ProtocolException
ASSERT: Must be called with this folder's synchronization lock held.IMAPProtocol p = null; try { p = getStoreProtocol(); // perform the command } catch (WhateverException ex) { // handle it } finally { releaseStoreProtocol(p); }
ProtocolException
- for protocol errorsprotected void throwClosedException(ConnectionException cex) throws javax.mail.FolderClosedException, javax.mail.StoreClosedException
cex
- the ConnectionExceptionjavax.mail.FolderClosedException
- if the folder is closedjavax.mail.StoreClosedException
- if the store is closedprotected com.sun.mail.imap.protocol.IMAPProtocol getProtocol() throws ProtocolException
This method will block if necessary to wait for an IDLE command to finish.
ProtocolException
- for protocol errorspublic java.lang.Object doCommand(IMAPFolder.ProtocolCommand cmd) throws javax.mail.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 commandjavax.mail.MessagingException
- for failurespublic java.lang.Object doOptionalCommand(java.lang.String err, IMAPFolder.ProtocolCommand cmd) throws javax.mail.MessagingException
javax.mail.MessagingException
public java.lang.Object doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd) throws javax.mail.MessagingException
javax.mail.MessagingException
protected java.lang.Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd) throws ProtocolException
ProtocolException
protected void releaseStoreProtocol(com.sun.mail.imap.protocol.IMAPProtocol p)
p
- the IMAPProtocol objectprotected void releaseProtocol(boolean returnToPool)
returnToPool
- return the protocol object to the pool?protected void keepConnectionAlive(boolean keepStoreAlive) throws ProtocolException
keepStoreAlive
is true,
also issue a noop over the store's connection.
ASSERT: This method must be called only when holding the
messageCacheLockkeepStoreAlive
- keep the Store alive too?ProtocolException
- for protocol errorsprotected IMAPMessage getMessageBySeqNumber(int seqnum)
seqnum
- the message sequence numberprotected IMAPMessage[] getMessagesBySeqNumbers(int[] seqnums)
seqnums
- the array of message sequence numbers