This class implements an IMAP folder.
A closed IMAPFolder object shares a protocol connection with its IMAPStore
object. When the folder is opened, it gets its own protocol connection.
Applications that need to make use of IMAP-specific features may cast
a
Folder
object to an
IMAPFolder
object and
use the methods on this class. The
getQuota
and
setQuota
methods support the IMAP QUOTA extension.
Refer to
RFC 2087
for more information.
The
getACL
,
addACL
,
removeACL
,
addRights
,
removeRights
,
listRights
, and
myRights
methods support the IMAP ACL extension.
Refer to
RFC 2086
for more information.
The
doCommand
method and
IMAPFolder.ProtocolCommand
interface support use of arbitrary IMAP protocol commands.
See the
com.sun.mail.imap package
documentation for further information on the IMAP protocol provider.
WARNING: The APIs unique to this class should be
considered
EXPERIMENTAL. They may be changed in the
future in ways that are incompatible with applications using the
current APIs.
UNKNOWN_SEPARATOR
protected static final char UNKNOWN_SEPARATOR
attributes
protected String[] attributes
availableFlags
protected Flags availableFlags
exists
protected boolean exists
fullName
protected String fullName
isNamespace
protected boolean isNamespace
messageCache
protected Vector messageCache
messageCacheLock
protected Object messageCacheLock
name
protected String name
permanentFlags
protected Flags permanentFlags
protocol
protected IMAPProtocol protocol
separator
protected char separator
uidTable
protected Hashtable uidTable
addACL
public void addACL(ACL acl)
throws MessagingException
Add an access control list entry to the access control list
for this folder.
acl
- the access control list entry to add
addMessages
public Message[] addMessages(Message[] msgs)
throws MessagingException
Append the given messages into this folder.
Return array of Message objects representing
the messages in the destination folder. Note
that the folder must be open.
Each element of the returned array corresponds to
an element of the
msgs
array. A null
element means the server didn't return UID information
for the appended message.
Depends on the APPENDUID response code defined by the
UIDPLUS extension -
RFC 2359.
addRights
public void addRights(ACL acl)
throws MessagingException
Add the rights specified in the ACL to the entry for the
identifier specified in the ACL. If an entry for the identifier
doesn't already exist, add one.
acl
- the identifer and rights to add
appendMessages
public void appendMessages(Message[] msgs)
throws MessagingException
Append the given messages into this folder.
appendUIDMessages
public AppendUID[] appendUIDMessages(Message[] msgs)
throws MessagingException
Append the given messages into this folder.
Return array of AppendUID objects containing
UIDs of these messages in the destination folder.
Each element of the returned array corresponds to
an element of the
msgs
array. A null
element means the server didn't return UID information
for the appended message.
Depends on the APPENDUID response code defined by the
UIDPLUS extension -
RFC 2359.
close
public void close(boolean expunge)
throws MessagingException
Close this folder.
copyMessages
public void copyMessages(Message[] msgs,
Folder folder)
throws MessagingException
Copy the specified messages from this folder, to the
specified destination.
create
public boolean create(int type)
throws MessagingException
Create this folder, with the specified type.
delete
public boolean delete(boolean recurse)
throws MessagingException
Delete this folder.
doCommand
public Object doCommand(IMAPFolder.ProtocolCommand cmd)
throws MessagingException
Execute a user-supplied IMAP command. The command is executed
in the appropriate context with the necessary locks held and
using the appropriate
IMAPProtocol
object.
This method returns whatever the
ProtocolCommand
object's
doCommand
method returns. If the
doCommand
method throws a
ConnectionException
it is translated into a
StoreClosedException
or
FolderClosedException
as appropriate. If the
doCommand
method throws a
ProtocolException
it is translated into a
MessagingException
.
The following example shows how to execute the IMAP NOOP command.
Executing more complex IMAP commands requires intimate knowledge
of the
com.sun.mail.iap
and
com.sun.mail.imap.protocol
packages, best acquired by
reading the source code.
import com.sun.mail.iap.*;
import com.sun.mail.imap.*;
import com.sun.mail.imap.protocol.*;
...
IMAPFolder f = (IMAPFolder)folder;
Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
public Object doCommand(IMAPProtocol p)
throws ProtocolException {
p.simpleCommand("NOOP", null);
return null;
}
});
Here's a more complex example showing how to use the proposed
IMAP SORT extension:
import com.sun.mail.iap.*;
import com.sun.mail.imap.*;
import com.sun.mail.imap.protocol.*;
...
IMAPFolder f = (IMAPFolder)folder;
Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
public Object doCommand(IMAPProtocol p)
throws ProtocolException {
// Issue command
Argument args = new Argument();
Argument list = new Argument();
list.writeString("SUBJECT");
args.writeArgument(list);
args.writeString("UTF-8");
args.writeString("ALL");
Response[] r = p.command("SORT", args);
Response response = r[r.length-1];
// Grab response
Vector v = new Vector();
if (response.isOK()) { // command succesful
for (int i = 0, len = r.length; i <32len; 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;
}
});
exists
public boolean exists()
throws MessagingException
Check whether this folder really exists on the server.
expunge
public Message[] expunge()
throws MessagingException
Expunge all messages marked as DELETED.
expunge
public Message[] expunge(Message[] msgs)
throws MessagingException
Expunge the indicated messages, which must have been marked as DELETED.
fetch
public void fetch(Message[] msgs,
FetchProfile fp)
throws MessagingException
Prefetch attributes, based on the given FetchProfile.
forceClose
public void forceClose()
throws MessagingException
Close this folder without waiting for the server.
getACL
public ACL[] getACL()
throws MessagingException
Get the access control list entries for this folder.
- array of access control list entries
getAttributes
public String[] getAttributes()
throws MessagingException
Get the attributes that the IMAP server returns with the
LIST response.
getDeletedMessageCount
public int getDeletedMessageCount()
throws MessagingException
Get the deleted message count.
getFolder
public Folder getFolder(String name)
throws MessagingException
getFullName
public String getFullName()
Get the fullname of this folder.
getMessage
public Message getMessage(int msgnum)
throws MessagingException
Get the specified message.
getMessageByUID
public Message getMessageByUID(long uid)
throws MessagingException
Get the Message corresponding to the given UID.
If no such message exists, null
is returned.
getMessageCount
public int getMessageCount()
throws MessagingException
Get the total message count.
getMessagesByUID
public Message[] getMessagesByUID(long start,
long end)
throws MessagingException
Get the Messages specified by the given range.
Returns Message objects for all valid messages in this range.
Returns an empty array if no messages are found.
getMessagesByUID
public Message[] getMessagesByUID(long[] uids)
throws MessagingException
Get the Messages specified by the given array.
uids.length()
elements are returned.
If any UID in the array is invalid, a
null
entry
is returned for that element.
getName
public String getName()
Get the name of this folder.
getNewMessageCount
public int getNewMessageCount()
throws MessagingException
Get the new message count.
getParent
public Folder getParent()
throws MessagingException
Get this folder's parent.
getPermanentFlags
public Flags getPermanentFlags()
Return the permanent flags supported by the server.
getProtocol
public IMAPProtocol getProtocol()
Return the IMAPProtocol object for this folder.
NOTE:
This method was intended to allow experimentation with
simple extension commands that can use the low level
Protocol object APIs to send commands and process
responses.
NOTE: Using this protocol object is completely
UNSAFE because there's no way to aquire
the required locks. See the
doCommand
method
for a safe alternative.
- the IMAPProtocol object used when the folder is open
getQuota
public Quota[] getQuota()
throws MessagingException
Get the quotas for the quotaroot associated with this
folder. Note that many folders may have the same quotaroot.
Quotas are controlled on the basis of a quotaroot, not
(necessarily) a folder. The relationship between folders
and quotaroots depends on the IMAP server. Some servers
might implement a single quotaroot for all folders owned by
a user. Other servers might implement a separate quotaroot
for each folder. A single folder can even have multiple
quotaroots, perhaps controlling quotas for different
resources.
- array of Quota objects for the quotaroots associated with
this folder
getSeparator
public char getSeparator()
throws MessagingException
Get the separator character.
getStoreProtocol
protected IMAPProtocol getStoreProtocol()
throws ProtocolException
Get this folder's Store's protocol connection.
When acquiring a store protocol object, it is important to
use the following steps:
IMAPProtocol p = null;
try {
p = getStoreProtocol();
// perform the command
} catch (WhateverException ex) {
// handle it
} finally {
releaseStoreProtocol(p);
}
getType
public int getType()
throws MessagingException
Get the type of this folder.
getUID
public long getUID(Message message)
throws MessagingException
Get the UID for the specified message.
getUIDNext
public long getUIDNext()
throws MessagingException
Returns the predicted UID that will be assigned to the
next message that is appended to this folder.
If the folder is closed, the STATUS command is used to
retrieve this value. If the folder is open, the value
returned from the SELECT or EXAMINE command is returned.
Note that messages may have been appended to the folder
while it was open and thus this value may be out of
date.
Servers implementing RFC2060 likely won't return this value
when a folder is opened. Servers implementing RFC3501
should return this value when a folder is opened.
- the UIDNEXT value, or -1 if unknown
getUIDValidity
public long getUIDValidity()
throws MessagingException
Returns the UIDValidity for this folder.
getUnreadMessageCount
public int getUnreadMessageCount()
throws MessagingException
Get the unread message count.
handleResponse
public void handleResponse(Response r)
The response handler. This is the callback routine that is
invoked by the protocol layer.
hasNewMessages
public boolean hasNewMessages()
throws MessagingException
Check whether this folder has new messages.
isOpen
public boolean isOpen()
Check whether this connection is really open.
isSubscribed
public boolean isSubscribed()
Check whether this folder is subscribed.
list
public Folder[] list(String pattern)
throws MessagingException
List all subfolders matching the specified pattern.
listRights
public Rights[] listRights(String name)
throws MessagingException
Get all the rights that may be allowed to the given identifier.
Rights are grouped per RFC 2086 and each group is returned as an
element of the array. The first element of the array is the set
of rights that are always granted to the identifier. Later
elements are rights that may be optionally granted to the
identifier.
Note that this method lists the rights that it is possible to
assign to the given identifier,
not the rights that are
actually granted to the given identifier. For the latter, see
the
getACL
method.
name
- the identifier to list rights for
- array of Rights objects representing possible
rights for the identifier
listSubscribed
public Folder[] listSubscribed(String pattern)
throws MessagingException
List all subscribed subfolders matching the specified pattern.
myRights
public Rights myRights()
throws MessagingException
Get the rights allowed to the currently authenticated user.
- the rights granted to the current user
open
public void open(int mode)
throws MessagingException
Open this folder in the given mode.
releaseStoreProtocol
protected void releaseStoreProtocol(IMAPProtocol p)
Release the store protocol object. If we borrowed a protocol
object from the connection pool, give it back. If we used our
own protocol object, nothing to do.
removeACL
public void removeACL(String name)
throws MessagingException
Remove any access control list entry for the given identifier
from the access control list for this folder.
name
- the identifier for which to remove all ACL entries
removeRights
public void removeRights(ACL acl)
throws MessagingException
Remove the rights specified in the ACL from the entry for the
identifier specified in the ACL.
acl
- the identifer and rights to remove
renameTo
public boolean renameTo(Folder f)
throws MessagingException
search
public Message[] search(SearchTerm term)
throws MessagingException
Search whole folder for messages matching the given term.
search
public Message[] search(SearchTerm term,
Message[] msgs)
throws MessagingException
Search the folder for messages matching the given term. Returns
array of matching messages. Returns an empty array if no matching
messages are found.
setFlags
public void setFlags(Message[] msgs,
Flags flag,
boolean value)
throws MessagingException
Set the specified flags for the given array of messages.
setQuota
public void setQuota(Quota quota)
throws MessagingException
Set the quotas for the quotaroot specified in the quota argument.
Typically this will be one of the quotaroots associated with this
folder, as obtained from the getQuota
method, but it
need not be.
setSubscribed
public void setSubscribed(boolean subscribe)
throws MessagingException
Subscribe/Unsubscribe this folder.