|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjavax.mail.Folder
com.sun.mail.imap.IMAPFolder
public class IMAPFolder
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.
| Nested Class Summary | |
|---|---|
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 | |
|---|---|
protected java.lang.String[] |
attributes
|
protected Flags |
availableFlags
|
protected boolean |
exists
|
protected java.lang.String |
fullName
|
protected boolean |
isNamespace
|
protected java.util.Vector |
messageCache
|
protected java.lang.Object |
messageCacheLock
|
protected java.lang.String |
name
|
protected Flags |
permanentFlags
|
protected com.sun.mail.imap.protocol.IMAPProtocol |
protocol
|
protected char |
separator
|
protected int |
type
|
protected java.util.Hashtable |
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 |
| Constructor Summary | |
|---|---|
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)
Constructor used to create a possibly non-existent folder. |
protected |
IMAPFolder(java.lang.String fullName,
char separator,
IMAPStore store,
boolean isNamespace)
Constructor used to create a possibly non-existent folder. |
| Method Summary | |
|---|---|
void |
addACL(ACL acl)
Add an access control list entry to the access control list for 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. |
com.sun.mail.imap.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. |
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. |
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. |
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[] |
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. |
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. |
com.sun.mail.imap.protocol.IMAPProtocol |
getProtocol()
Return the IMAPProtocol object for this folder. |
Quota[] |
getQuota()
Get the quotas for the quotaroot associated with this folder. |
char |
getSeparator()
Get the separator character. |
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(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. |
long |
getUIDValidity()
Returns the UIDValidity for this folder. |
int |
getUnreadMessageCount()
Get the unread message count. |
void |
handleResponse(com.sun.mail.iap.Response r)
The response handler. |
boolean |
hasNewMessages()
Check whether this folder has new messages. |
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. |
Rights |
myRights()
Get the rights allowed to the currently authenticated user. |
void |
open(int mode)
Open this folder in the given mode. |
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(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(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. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
|---|
protected java.lang.String fullName
protected java.lang.String name
protected int type
protected char separator
protected Flags availableFlags
protected Flags permanentFlags
protected boolean exists
protected boolean isNamespace
protected java.lang.String[] attributes
protected com.sun.mail.imap.protocol.IMAPProtocol protocol
protected java.util.Vector messageCache
protected java.lang.Object messageCacheLock
protected java.util.Hashtable uidTable
protected static final char UNKNOWN_SEPARATOR
| Constructor Detail |
|---|
protected IMAPFolder(java.lang.String fullName,
char separator,
IMAPStore store)
fullName - fullname of this folderseparator - the default separator character for this
folder's namespacestore - the Store
protected IMAPFolder(java.lang.String fullName,
char separator,
IMAPStore store,
boolean isNamespace)
fullName - fullname of this folderseparator - the default separator character for this
folder's namespacestore - the Store
protected IMAPFolder(com.sun.mail.imap.protocol.ListInfo li,
IMAPStore store)
| Method Detail |
|---|
public java.lang.String getName()
getName in class Folderpublic java.lang.String getFullName()
getFullName in class Folder
public Folder getParent()
throws MessagingException
getParent in class FolderMessagingException
public boolean exists()
throws MessagingException
exists in class FolderMessagingException - typically if the connection
to the server is lost.Folder.create(int)
public Folder[] list(java.lang.String pattern)
throws MessagingException
list in class Folderpattern - the match pattern
FolderNotFoundException - if this folder does
not exist.
MessagingExceptionFolder.listSubscribed(java.lang.String)
public Folder[] listSubscribed(java.lang.String pattern)
throws MessagingException
listSubscribed in class Folderpattern - the match pattern
FolderNotFoundException - if this folder does
not exist.
MessagingExceptionFolder.list(java.lang.String)
public char getSeparator()
throws MessagingException
getSeparator in class FolderFolderNotFoundException - if the implementation
requires the folder to exist, but it does not
MessagingException
public int getType()
throws MessagingException
getType in class FolderFolderNotFoundException - if this folder does
not exist.
MessagingExceptionFolder.HOLDS_FOLDERS,
Folder.HOLDS_MESSAGESpublic boolean isSubscribed()
isSubscribed in class Folder
public void setSubscribed(boolean subscribe)
throws MessagingException
setSubscribed in class Foldersubscribe - true to subscribe, false to unsubscribe
FolderNotFoundException - if this folder does
not exist.
MethodNotSupportedException - if this store
does not support subscription
MessagingException
public boolean create(int type)
throws MessagingException
create in class Foldertype - The type of this folder.
MessagingExceptionFolder.HOLDS_FOLDERS,
Folder.HOLDS_MESSAGES,
FolderEvent
public boolean hasNewMessages()
throws MessagingException
hasNewMessages in class FolderFolderNotFoundException - if this folder does
not exist.
MessagingException
public Folder getFolder(java.lang.String name)
throws MessagingException
getFolder in class Foldername - name of the Folder
MessagingException
public boolean delete(boolean recurse)
throws MessagingException
delete in class FolderFolderNotFoundException - if this folder does
not exist
MessagingExceptionFolderEvent
public boolean renameTo(Folder f)
throws MessagingException
renameTo in class Folderf - a folder representing the new name for this Folder
FolderNotFoundException - if this folder does
not exist
MessagingExceptionFolderEvent
public void open(int mode)
throws MessagingException
open in class Foldermode - open the Folder READ_ONLY or READ_WRITE
FolderNotFoundException - if this folder does
not exist.
MessagingExceptionFolder.READ_ONLY,
Folder.READ_WRITE,
Folder.getType(),
ConnectionEvent
public void fetch(Message[] msgs,
FetchProfile fp)
throws MessagingException
fetch in class Foldermsgs - fetch items for these messagesfp - the FetchProfile
MessagingException
public void setFlags(Message[] msgs,
Flags flag,
boolean value)
throws MessagingException
setFlags in class Foldermsgs - the array of message objectsflag - Flags object containing the flags to be setvalue - set the flags to this boolean value
MessagingExceptionMessage.setFlags(javax.mail.Flags, boolean),
MessageChangedEvent
public void close(boolean expunge)
throws MessagingException
close in class Folderexpunge - expunges all deleted messages if this flag is true
MessagingExceptionConnectionEvent
public void forceClose()
throws MessagingException
MessagingExceptionpublic boolean isOpen()
isOpen in class Folderpublic Flags getPermanentFlags()
getPermanentFlags in class Folder
public int getMessageCount()
throws MessagingException
getMessageCount in class FolderFolderNotFoundException - if this folder does
not exist.
MessagingException
public int getNewMessageCount()
throws MessagingException
getNewMessageCount in class FolderFolderNotFoundException - if this folder does
not exist.
MessagingException
public int getUnreadMessageCount()
throws MessagingException
getUnreadMessageCount in class FolderFolderNotFoundException - if this folder does
not exist.
MessagingException
public int getDeletedMessageCount()
throws MessagingException
getDeletedMessageCount in class FolderFolderNotFoundException - if this folder does
not exist.
MessagingException
public Message getMessage(int msgnum)
throws MessagingException
getMessage in class Foldermsgnum - the message number
FolderNotFoundException - if this folder does
not exist.
MessagingExceptionFolder.getMessageCount(),
Folder.fetch(javax.mail.Message[], javax.mail.FetchProfile)
public void appendMessages(Message[] msgs)
throws MessagingException
appendMessages in class Foldermsgs - array of Messages to be appended
FolderNotFoundException - if this folder does
not exist.
MessagingException - if the append failed.
public com.sun.mail.imap.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 2359.
MessagingException
public 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 2359.
MessagingException
public void copyMessages(Message[] msgs,
Folder folder)
throws MessagingException
copyMessages in class Foldermsgs - the array of message objectsfolder - the folder to copy the messages to
FolderNotFoundException - if the destination
folder does not exist.
MessagingExceptionFolder.appendMessages(javax.mail.Message[])
public Message[] expunge()
throws MessagingException
expunge in class FolderFolderNotFoundException - if this folder does not
exist
MessagingExceptionMessage.isExpunged(),
MessageCountEvent
public Message[] expunge(Message[] msgs)
throws MessagingException
MessagingException
public Message[] search(SearchTerm term)
throws MessagingException
search in class Folderterm - the search criterion
SearchException - if the search
term is too complex for the implementation to handle.
FolderNotFoundException - if this folder does
not exist.
MessagingExceptionSearchTerm
public Message[] search(SearchTerm term,
Message[] msgs)
throws MessagingException
search in class Folderterm - the search criterionmsgs - the messages to be searched
SearchException - if the search
term is too complex for the implementation to handle.
MessagingExceptionSearchTerm
public long getUIDValidity()
throws MessagingException
getUIDValidity in interface UIDFolderMessagingException
public 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.
MessagingException
public Message getMessageByUID(long uid)
throws MessagingException
null is returned.
getMessageByUID in interface UIDFolderuid - UID for the desired message
null is returned
if no message corresponding to this UID is obtained.
MessagingException
public 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 UIDFolderstart - start UIDend - end UID
MessagingExceptionUIDFolder.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 UIDFolderuids - array of UIDs
MessagingException
public long getUID(Message message)
throws MessagingException
getUID in interface UIDFoldermessage - Message from this folder
MessagingException
public Quota[] getQuota()
throws MessagingException
MessagingException - if the server doesn't support the
QUOTA extension
public void setQuota(Quota quota)
throws MessagingException
getQuota method, but it
need not be.
quota - the quota to set
MessagingException - if the server doesn't support the
QUOTA extension
public ACL[] getACL()
throws MessagingException
MessagingException - if the server doesn't support the
ACL extension
public void addACL(ACL acl)
throws MessagingException
acl - the access control list entry to add
MessagingException - if the server doesn't support the
ACL extension
public void removeACL(java.lang.String name)
throws MessagingException
name - the identifier for which to remove all ACL entries
MessagingException - if the server doesn't support the
ACL extension
public void addRights(ACL acl)
throws MessagingException
acl - the identifer and rights to add
MessagingException - if the server doesn't support the
ACL extension
public void removeRights(ACL acl)
throws MessagingException
acl - the identifer and rights to remove
MessagingException - if the server doesn't support the
ACL extension
public 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 for
MessagingException - if the server doesn't support the
ACL extension
public Rights myRights()
throws MessagingException
MessagingException - if the server doesn't support the
ACL extension
public java.lang.String[] getAttributes()
throws MessagingException
MessagingExceptionpublic void handleResponse(com.sun.mail.iap.Response r)
handleResponse in interface com.sun.mail.iap.ResponseHandler
protected com.sun.mail.imap.protocol.IMAPProtocol getStoreProtocol()
throws com.sun.mail.iap.ProtocolException
com.sun.mail.iap.ProtocolExceptionpublic com.sun.mail.imap.protocol.IMAPProtocol getProtocol()
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.
doCommand(com.sun.mail.imap.IMAPFolder.ProtocolCommand)
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; } });
MessagingException
public 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
protected java.lang.Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd)
throws com.sun.mail.iap.ProtocolException
com.sun.mail.iap.ProtocolExceptionprotected void releaseStoreProtocol(com.sun.mail.imap.protocol.IMAPProtocol p)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||