com.sun.mail.imap

Class IMAPFolder

Implemented Interfaces:
ResponseHandler, UIDFolder

public class IMAPFolder
extends Folder
implements UIDFolder, ResponseHandler

This class implements an IMAP folder.

A closed IMAPFolder object shares a protocol connection with its IMAPStore object. When the folder is opened, it gets its own protocol connection.

Applications that need to make use of IMAP-specific features may cast a Folder object to an IMAPFolder object and use the methods on this class. The getQuota and setQuota methods support the IMAP QUOTA extension. Refer to RFC 2087 for more information.

The getACL, addACL, removeACL, addRights, removeRights, listRights, and myRights methods support the IMAP ACL extension. Refer to RFC 2086 for more information.

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

Version:
1.74, 05/11/17
Authors:
John Mani
Bill Shannon
Jim Glennon

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 static char
UNKNOWN_SEPARATOR
protected String[]
attributes
protected Flags
availableFlags
protected boolean
exists
protected String
fullName
protected boolean
isNamespace
protected Vector
messageCache
protected Object
messageCacheLock
protected String
name
protected Flags
permanentFlags
protected IMAPProtocol
protocol
protected char
separator
protected int
type
protected Hashtable
uidTable

Constructor Summary

IMAPFolder(ListInfo li, IMAPStore store)
Constructor used to create an existing folder.
IMAPFolder(String fullName, char separator, IMAPStore store)
Constructor used to create a possibly non-existent folder.
IMAPFolder(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.
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.
Object
doCommand(IMAPFolder.ProtocolCommand cmd)
Execute a user-supplied IMAP command.
Object
doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd)
Object
doOptionalCommand(String err, IMAPFolder.ProtocolCommand cmd)
protected 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.
String[]
getAttributes()
Get the attributes that the IMAP server returns with the LIST response.
int
getDeletedMessageCount()
Get the deleted message count.
Folder
getFolder(String name)
Get the named subfolder.
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 start, long end)
Get the Messages specified by the given range.
Message[]
getMessagesByUID(long[] uids)
Get the Messages specified by the given array.
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.
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 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(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(String pattern)
List all subfolders matching the specified pattern.
Rights[]
listRights(String name)
Get all the rights that may be allowed to the given identifier.
Folder[]
listSubscribed(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(IMAPProtocol p)
Release the store protocol object.
void
removeACL(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.

Field Details

UNKNOWN_SEPARATOR

protected static final char UNKNOWN_SEPARATOR
Field Value:
'\uffff'

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

type

protected int type

uidTable

protected Hashtable uidTable

Constructor Details

IMAPFolder

protected IMAPFolder(ListInfo li,
                     IMAPStore store)
Constructor used to create an existing folder.

IMAPFolder

protected IMAPFolder(String fullName,
                     char separator,
                     IMAPStore store)
Constructor used to create a possibly non-existent folder.
Parameters:
fullName - fullname of this folder
separator - the default separator character for this folder's namespace
store - the Store

IMAPFolder

protected IMAPFolder(String fullName,
                     char separator,
                     IMAPStore store,
                     boolean isNamespace)
Constructor used to create a possibly non-existent folder.
Parameters:
fullName - fullname of this folder
separator - the default separator character for this folder's namespace
store - the Store

Method Details

addACL

public void addACL(ACL acl)
            throws MessagingException
Add an access control list entry to the access control list for this folder.
Parameters:
acl - the access control list entry to add

addMessages

public Message[] addMessages(Message[] msgs)
            throws MessagingException

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

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; } });

doCommandIgnoreFailure

public Object doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd)
            throws MessagingException

doOptionalCommand

public Object doOptionalCommand(String err,
                                IMAPFolder.ProtocolCommand cmd)
            throws MessagingException

doProtocolCommand

protected Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd)
            throws ProtocolException

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.
Returns:
array of access control list entries

getAttributes

public String[] getAttributes()
            throws MessagingException
Get the attributes that the IMAP server returns with the LIST response.
Since:
JavaMail 1.3.3

getDeletedMessageCount

public int getDeletedMessageCount()
            throws MessagingException
Get the deleted message count.

getFolder

public Folder getFolder(String name)
            throws MessagingException
Get the named subfolder.


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.

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

Returns:
the UIDNEXT value, or -1 if unknown
Since:
JavaMail 1.3.3

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.

Parameters:
name - the identifier to list rights for
Returns:
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.
Returns:
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.
Parameters:
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.
Parameters:
acl - the identifer and rights to remove

renameTo

public boolean renameTo(Folder f)
            throws MessagingException
Rename this folder.


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.
Parameters:
quota - the quota to set

setSubscribed

public void setSubscribed(boolean subscribe)
            throws MessagingException
Subscribe/Unsubscribe this folder.