org.apache.geronimo.javamail.store.imap
Class IMAPFolder

java.lang.Object
  javax.mail.Folder
      org.apache.geronimo.javamail.store.imap.IMAPFolder

All Implemented Interfaces:

UIDFolder, IMAPUntaggedResponseHandler

Direct Known Subclasses:

IMAPNamespaceFolder, IMAPRootFolder

public class IMAPFolder
extends Folder
implements UIDFolder, IMAPUntaggedResponseHandler

The base IMAP implementation of the javax.mail.Folder This is a base class for both the Root IMAP server and each IMAP group folder.

Version:

$Rev: 594520 $

See Also:

Folder

Nested Class Summary

static class

IMAPFolder.FetchProfileItem Special profile item used for fetching SIZE and HEADER information.

Field Summary

protected Flags	availableFlags
protected IMAPMailboxStatus	cachedStatus
protected IMAPConnection	currentConnection
protected boolean	folderOpen
protected int	folderType
protected String	fullname
protected long	lastStatusTimeStamp
protected IMAPListResponse	listInfo
protected int	maxSequenceNumber
protected LinkedList	messages
protected String	name
protected int	nextMessageID
protected Flags	permanentFlags
protected int	recentMessages
protected char	separator
protected Session	session
protected long	statusCacheTimeout
protected boolean	subscribed
protected Map	uidCache
protected long	uidNext
protected long	uidValidity
protected static char	UNDETERMINED
protected int	unseenMessages

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(IMAPStore store, String fullname, char separator) Super class constructor the base IMAPFolder class.

Method Summary

void	addACL(ACL acl) Add an entry to the access control list for this folder.
void	addRights(ACL acl) Add Rights to a given ACL entry.
protected void	addToUidCache(Long key, Message msg) Add a message to the UID mapping cache, ensuring that the UID value is updated.
protected void	appendMessage(Message msg) Append a single message to the IMAP Folder.
void	appendMessages(Message[] msgs) Append the supplied messages to this folder.
protected void	checkClosed() Ensure the folder is not open for operations that require the folder to be closed.
protected void	checkFolderValidity() Verify that this folder exists on the server before performning an operation that requires a valid Folder instance.
protected void	checkMessageFolder(Message msg) Check if a Message is properly within the target folder.
protected void	checkMessageValidity(int messageNumber) Validate that a target message number is considered valid by the IMAP server.
protected void	checkOpen() Ensure the folder is open.
protected void	checkOpenReadWrite() Check that the folder is open and in read/write mode.
protected void	checkReadWrite() Ensure that the folder is open for read/write mode before doing an operation that would make a change.
protected void	cleanupFolder(boolean expunge, boolean disconnected) Do folder cleanup.
void	close(boolean expunge) Close this folder; it must already be open.
void	copyMessages(Message[] messages, Folder folder) Copy the specified messages to another folder.
boolean	create(int newType) Create a new folder capable of containing subfolder and/or messages as determined by the type parameter.
boolean	delete(boolean recurse) Delete this folder and possibly any subfolders.
boolean	exists() Check to see if this folder physically exists in the store.
Message[]	expunge() Permanently delete all supplied messages that have the DELETED flag set from the Store.
protected Message	expungeMessage(int sequenceNumber) Process an EXPUNGE response for a message, removing the message from the message cache.
void	fetch(Message[] messages, FetchProfile profile) Hint to the store to prefetch information on the supplied messages.
protected Folder[]	filterFolders(String pattern, boolean subscribed) Retrieve the list of matching groups from the IMAP server using the LIST or LSUB command.
protected IMAPListResponse	findListResponse(List responses, String name) Search a list of LIST responses for one containing information for a particular mailbox name.
protected String	generateMessageSet(List messages) Generate a message set string from a List of messages rather than an array.
protected String	generateMessageSet(Message[] messages) Take an array of messages and generate a String argument as specified by RFC 2060.
String[]	getAttributes() Get the set of attributes defined for the folder as the set of capabilities returned when the folder was opened.
protected IMAPConnection	getConnection() Retrieve the connection attached to this folder.
int	getDeletedMessageCount() Return the number of messages in this folder that have the Flag.DELETED flag set.
Folder	getFolder(String name) Get the Folder determined by the supplied name; if the name is relative then it is interpreted relative to this folder.
String	getFullName() Retrieve the folder's full name (including hierarchy information).
protected String	getMailBoxName() Protected class intended for subclass overrides.
Message	getMessage(int msgNum) Retrieve the message with the specified index in this Folder; messages indices start at 1 not zero.
Message	getMessageByUID(long uid) Retrieve a message using the UID rather than the message sequence number.
int	getMessageCount() Return the number of messages this folder contains.
Message[]	getMessages(int start, int end) Retrieve a range of messages for this folder.
Message[]	getMessagesByUID(long[] ids) Retrieve a set of messages by explicit UIDs.
Message[]	getMessagesByUID(long start, long end) Get a series of messages using a UID range.
String	getName() Retrieve the folder name.
int	getNewMessageCount() Return the numbew of messages in this folder that have the Flag.RECENT flag set.
Folder	getParent() Return the parent for this folder; if the folder is at the root of a heirarchy this returns null.
Flags	getPermanentFlags() Get the permanentFlags
Quota[]	getQuota() Get the quota values assigned to the current folder.
char	getSeparator() Return the character used by this folder's Store to separate path components.
int	getType() Return whether this folder can hold just messages or also subfolders.
long	getUID(Message message) Retrieve the UID for a message from this Folder.
long	getUIDValidity() Get the UID validity value for this Folder.
int	getUnreadMessageCount() Return the number of messages in this folder that do not have the Flag.SEEN flag set.
boolean	handleResponse(IMAPUntaggedResponse response) Handle an unsolicited response from the server.
boolean	hasNewMessages() Check to see if this Folder conatins messages with the Flag.RECENT flag set.
protected boolean	holdsFolders() Test if a folder can hold sub folders.
boolean	isOpen() Tests the open status of the folder.
boolean	isSubscribed() Return the subscription status of this folder.
Folder[]	list(String pattern) Return a list of folders from this Folder's namespace that match the supplied pattern.
Rights[]	listRights(String name) List the rights associated with a given name.
Folder[]	listSubscribed(String pattern) Return a list of folders to which the user is subscribed and which match the supplied pattern.
Rights	myRights() List the rights for the currently authenticated user.
void	notifyMessageChangedListeners(int type, Message m) Notify the message changed listeners that a message contained in the folder has been updated.
void	open(int mode) Open this folder; the folder must be able to contain messages and must currently be closed.
protected void	populateMessageCache() Populate the message cache with dummy messages, ensuring we're filled up to the server-reported number of messages.
protected void	refreshStatus(boolean force) Refresh the status information on this folder.
protected void	releaseConnection(IMAPConnection connection) Release our connection back to the Store.
void	removeACL(ACL acl) Remove an entry from the access control list for this folder.
void	removeRights(ACL acl) Remove ACL Rights from a folder.
boolean	renameTo(Folder f) Rename this folder; the folder must be closed.
protected Message[]	resolveMessages(int[] messageNumbers) Resolve an array of message numbers into an array of the referenced messages.
protected Message	retrieveMessageByUid(Long key, int msgNumber) Retrieve a message from a UID/message mapping.
Message[]	search(SearchTerm term) Search the supplied messages for those that match the supplied criteria; messages must belong to this folder.
Message[]	search(SearchTerm term, Message[] messages) Search the supplied messages for those that match the supplied criteria; messages must belong to this folder.
void	setFlags(int[] ids, Flags flags, boolean value) Set flags on a set of messages to the supplied value.
void	setFlags(int start, int end, Flags flags, boolean value) Set flags on a range of messages to the supplied value.
void	setFlags(Message[] messages, Flags flags, boolean set) Set flags on the messages to the supplied value; all messages must belong to this folder.
void	setQuota(Quota quota) Set the quota value for a quota root
void	setSubscribed(boolean flag) Set or clear the subscription status of a file.

Methods inherited from class javax.mail.Folder

addConnectionListener, addFolderListener, addMessageChangedListener, addMessageCountListener, finalize, getMessages, getMessages, getMode, getStore, getURLName, list, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, notifyMessageAddedListeners, notifyMessageRemovedListeners, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNDETERMINED

protected static final char UNDETERMINED

See Also:

Constant Field Values

session

protected Session session

messages

protected LinkedList messages

uidCache

protected Map uidCache

separator

protected char separator

fullname

protected String fullname

name

protected String name

folderOpen

protected boolean folderOpen

folderType

protected int folderType

subscribed

protected boolean subscribed

nextMessageID

protected int nextMessageID

maxSequenceNumber

protected int maxSequenceNumber

recentMessages

protected int recentMessages

unseenMessages

protected int unseenMessages

uidValidity

protected long uidValidity

uidNext

protected long uidNext

permanentFlags

protected Flags permanentFlags

availableFlags

protected Flags availableFlags

cachedStatus

protected IMAPMailboxStatus cachedStatus

listInfo

protected IMAPListResponse listInfo

statusCacheTimeout

protected long statusCacheTimeout

lastStatusTimeStamp

protected long lastStatusTimeStamp

currentConnection

protected IMAPConnection currentConnection

Constructor Detail

IMAPFolder

protected IMAPFolder(IMAPStore store,
                     String fullname,
                     char separator)

Super class constructor the base IMAPFolder class.

Parameters:

store - The javamail store this folder is attached to.

fullname - The fully qualified name of this folder.

separator - The separtor character used to delimit the different levels of the folder hierarchy. This is used to decompose the full name into smaller parts and create the names of subfolders.

Method Detail

getName

public String getName()

Retrieve the folder name. This is the simple folder name at the its hiearchy level. This can be invoked when the folder is closed.

Specified by:

getName in class Folder

Returns:

The folder's name.

getFullName

public String getFullName()

Retrieve the folder's full name (including hierarchy information). This can be invoked when the folder is closed.

Specified by:

getFullName in class Folder

Returns:

The full name value.

getParent

public Folder getParent()
                 throws MessagingException

Return the parent for this folder; if the folder is at the root of a heirarchy this returns null. This can be invoked when the folder is closed.

Specified by:

getParent in class Folder

Returns:

this folder's parent

Throws:

MessagingException

exists

public boolean exists()
               throws MessagingException

Check to see if this folder physically exists in the store. This can be invoked when the folder is closed.

Specified by:

exists in class Folder

Returns:

true if the folder really exists

Throws:

MessagingException - if there was a problem accessing the store

list

public Folder[] list(String pattern)
              throws MessagingException

Return a list of folders from this Folder's namespace that match the supplied pattern. Patterns may contain the following wildcards:

• '%' which matches any characater except hierarchy delimiters
• '*' which matches any character including hierarchy delimiters

This can be invoked when the folder is closed.

Specified by:

list in class Folder

Parameters:

pattern - the pattern to search for

Returns:

a possibly empty array containing Folders that matched the pattern

Throws:

MessagingException - if there was a problem accessing the store

listSubscribed

public Folder[] listSubscribed(String pattern)
                        throws MessagingException

Return a list of folders to which the user is subscribed and which match the supplied pattern. If the store does not support the concept of subscription then this should match against all folders; the default implementation of this method achieves this by defaulting to the list(String) method.

Overrides:

listSubscribed in class Folder

Parameters:

pattern - the pattern to search for

Returns:

a possibly empty array containing subscribed Folders that matched the pattern

Throws:

MessagingException - if there was a problem accessing the store

getSeparator

public char getSeparator()
                  throws MessagingException

Return the character used by this folder's Store to separate path components.

Specified by:

getSeparator in class Folder

Returns:

the name separater character

Throws:

MessagingException - if there was a problem accessing the store

getType

public int getType()
            throws MessagingException

Return whether this folder can hold just messages or also subfolders.

Specified by:

getType in class Folder

Returns:

The combination of Folder.HOLDS_MESSAGES and Folder.HOLDS_FOLDERS, depending on the folder capabilities.

Throws:

MessagingException

create

public boolean create(int newType)
               throws MessagingException

Create a new folder capable of containing subfolder and/or messages as determined by the type parameter. Any hierarchy defined by the folder name will be recursively created. If the folder was sucessfully created, a CREATED FolderEvent is sent to all FolderListeners registered with this Folder or with the Store.

Specified by:

create in class Folder

Parameters:

newType - the type, indicating if this folder should contain subfolders, messages or both

Returns:

true if the folder was sucessfully created

Throws:

MessagingException - if there was a problem accessing the store

isSubscribed

public boolean isSubscribed()

Return the subscription status of this folder.

Overrides:

isSubscribed in class Folder

Returns:

true if the folder is marked as subscribed, false for unsubscribed.

setSubscribed

public void setSubscribed(boolean flag)
                   throws MessagingException

Set or clear the subscription status of a file.

Overrides:

setSubscribed in class Folder

Parameters:

flag - The new subscription state.

Throws:

MessagingException

hasNewMessages

public boolean hasNewMessages()
                       throws MessagingException

Check to see if this Folder conatins messages with the Flag.RECENT flag set. This can be used when the folder is closed to perform a light-weight check for new mail; to perform an incremental check for new mail the folder must be opened.

Specified by:

hasNewMessages in class Folder

Returns:

true if the Store has recent messages

Throws:

MessagingException - if there was a problem accessing the store

getFolder

public Folder getFolder(String name)
                 throws MessagingException

Get the Folder determined by the supplied name; if the name is relative then it is interpreted relative to this folder. This does not check that the named folder actually exists.

Specified by:

getFolder in class Folder

Parameters:

name - the name of the folder to return

Returns:

the named folder

Throws:

MessagingException - if there was a problem accessing the store

delete

public boolean delete(boolean recurse)
               throws MessagingException

Delete this folder and possibly any subfolders. This operation can only be performed on a closed folder. If recurse is true, then all subfolders are deleted first, then any messages in this folder are removed and it is finally deleted; FolderEvent.DELETED events are sent as appropriate. If recurse is false, then the behaviour depends on the folder type and store implementation as followd:

• If the folder can only conrain messages, then all messages are removed and then the folder is deleted; a FolderEvent.DELETED event is sent.
• If the folder can onlu contain subfolders, then if it is empty it will be deleted and a FolderEvent.DELETED event is sent; if the folder is not empty then the delete fails and this method returns false.
• If the folder can contain both subfolders and messages, then if the folder does not contain any subfolders, any messages are deleted, the folder itself is deleted and a FolderEvent.DELETED event is sent; if the folder does contain subfolders then the implementation may choose from the following three behaviors:
  1. it may return false indicting the operation failed
  2. it may remove all messages within the folder, send a FolderEvent.DELETED event, and then return true to indicate the delete was performed. Note this does not delete the folder itself and the exists() operation for this folder will return true
  3. it may remove all messages within the folder as per the previous option; in addition it may change the type of the Folder to only HOLDS_FOLDERS indictaing that messages may no longer be added

FolderEvents are sent to all listeners registered with this folder or with the Store.

Specified by:

delete in class Folder

Parameters:

recurse - whether subfolders should be recursively deleted as well

Returns:

true if the delete operation succeeds

Throws:

MessagingException - if there was a problem accessing the store

renameTo

public boolean renameTo(Folder f)
                 throws MessagingException

Rename this folder; the folder must be closed. If the rename is successfull, a FolderEvent.RENAMED event is sent to all listeners registered with this folder or with the store.

Specified by:

renameTo in class Folder

Parameters:

newName - the new name for this folder

Returns:

true if the rename succeeded

Throws:

MessagingException - if there was a problem accessing the store

open

public void open(int mode)
          throws MessagingException

Open this folder; the folder must be able to contain messages and must currently be closed. If the folder is opened successfully then a ConnectionEvent.OPENED event is sent to listeners registered with this Folder.

Whether the Store allows multiple connections or if it allows multiple writers is implementation defined.

Specified by:

open in class Folder

Parameters:

mode - READ_ONLY or READ_WRITE

Throws:

MessagingException - if there was a problem accessing the store

populateMessageCache

protected void populateMessageCache()

Populate the message cache with dummy messages, ensuring we're filled up to the server-reported number of messages.

Throws:

MessagingException

close

public void close(boolean expunge)
           throws MessagingException

Close this folder; it must already be open. A @link ConnectionEvent#CLOSED} event is sent to all listeners registered {* with this folder.

Specified by:

close in class Folder

Parameters:

expunge - whether to expunge all deleted messages

Throws:

MessagingException - if there was a problem accessing the store; the folder is still closed

cleanupFolder

protected void cleanupFolder(boolean expunge,
                             boolean disconnected)
                      throws MessagingException

Do folder cleanup. This is used both for normal close operations, and adnormal closes where the server has sent us a BYE message.

Parameters:

expunge - Indicates whether open messages should be expunged.

disconnected - The disconnected flag. If true, the server has cut us off, which means our connection can not be returned to the connection pool.

Throws:

MessagingException

isOpen

public boolean isOpen()

Tests the open status of the folder.

Specified by:

isOpen in class Folder

Returns:

true if the folder is open, false otherwise.

getPermanentFlags

public Flags getPermanentFlags()

Get the permanentFlags

Specified by:

getPermanentFlags in class Folder

Returns:

The set of permanent flags we support (only SEEN).

getMessageCount

public int getMessageCount()
                    throws MessagingException

Return the number of messages this folder contains. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder.

Specified by:

getMessageCount in class Folder

Returns:

the number of messages, or -1 if unknown

Throws:

MessagingException - if there was a problem accessing the store

getNewMessageCount

public int getNewMessageCount()
                       throws MessagingException

Return the numbew of messages in this folder that have the Flag.RECENT flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation. NB: This is an override of the default Folder implementation, which examines each of the messages in the folder. IMAP has more efficient mechanisms for grabbing the information.

Overrides:

getNewMessageCount in class Folder

Returns:

the number of new messages, or -1 if unknown

Throws:

MessagingException - if there was a problem accessing the store

getUnreadMessageCount

public int getUnreadMessageCount()
                          throws MessagingException

Return the number of messages in this folder that do not have the Flag.SEEN flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation. NB: This is an override of the default Folder implementation, which examines each of the messages in the folder. IMAP has more efficient mechanisms for grabbing the information.

Overrides:

getUnreadMessageCount in class Folder

Returns:

the number of new messages, or -1 if unknown

Throws:

MessagingException - if there was a problem accessing the store

getDeletedMessageCount

public int getDeletedMessageCount()
                           throws MessagingException

Return the number of messages in this folder that have the Flag.DELETED flag set. If this operation is invoked on a closed folder, the implementation may choose to return -1 to avoid the expense of opening the folder. The default implmentation of this method iterates over all messages in the folder; subclasses should override if possible to provide a more efficient implementation.

Overrides:

getDeletedMessageCount in class Folder

Returns:

the number of new messages, or -1 if unknown

Throws:

MessagingException - if there was a problem accessing the store

getMessage

public Message getMessage(int msgNum)
                   throws MessagingException

Retrieve the message with the specified index in this Folder; messages indices start at 1 not zero. Clients should note that the index for a specific message may change if the folder is expunged; Message objects should be used as references instead.

Specified by:

getMessage in class Folder

Parameters:

msgNum - The message sequence number of the target message.

Returns:

the message

Throws:

MessagingException - if there was a problem accessing the store

getMessages

public Message[] getMessages(int start,
                             int end)
                      throws MessagingException

Retrieve a range of messages for this folder. messages indices start at 1 not zero.

Overrides:

getMessages in class Folder

Parameters:

start - Index of the first message to fetch, inclusive.

end - Index of the last message to fetch, inclusive.

Returns:

An array of the fetched messages.

Throws:

MessagingException - if there was a problem accessing the store

appendMessages

public void appendMessages(Message[] msgs)
                    throws MessagingException

Append the supplied messages to this folder. A MessageCountEvent is sent to all listeners registered with this folder when all messages have been appended. If the array contains a previously expunged message, it must be re-appended to the Store and implementations must not abort this operation.

Specified by:

appendMessages in class Folder

Parameters:

msgs - The array of messages to append to the folder.

Throws:

MessagingException - if there was a problem accessing the store

fetch

public void fetch(Message[] messages,
                  FetchProfile profile)
           throws MessagingException

Hint to the store to prefetch information on the supplied messages. Subclasses should override this method to provide an efficient implementation; the default implementation in this class simply returns.

Overrides:

fetch in class Folder

Parameters:

messages - messages for which information should be fetched

profile - the information to fetch

Throws:

MessagingException - if there was a problem accessing the store

See Also:

FetchProfile

setFlags

public void setFlags(Message[] messages,
                     Flags flags,
                     boolean set)
              throws MessagingException

Set flags on the messages to the supplied value; all messages must belong to this folder. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply calls Message.setFlags(Flags, boolean) for each supplied messages.

Overrides:

setFlags in class Folder

Parameters:

messages - whose flags should be set

flags - the set of flags to modify

set - Indicates whether the flags should be set or cleared.

Throws:

MessagingException - if there was a problem accessing the store

setFlags

public void setFlags(int start,
                     int end,
                     Flags flags,
                     boolean value)
              throws MessagingException

Set flags on a range of messages to the supplied value. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply gets each message and then calls Message.setFlags(Flags, boolean).

Overrides:

setFlags in class Folder

Parameters:

start - first message end set

end - last message end set

flags - the set of flags end modify

value - Indicates whether the flags should be set or cleared.

Throws:

MessagingException - if there was a problem accessing the store

setFlags

public void setFlags(int[] ids,
                     Flags flags,
                     boolean value)
              throws MessagingException

Set flags on a set of messages to the supplied value. This method may be overridden by subclasses that can optimize the setting of flags on multiple messages at once; the default implementation simply gets each message and then calls Message.setFlags(Flags, boolean).

Overrides:

setFlags in class Folder

Parameters:

ids - the indexes of the messages to set

flags - the set of flags end modify

value - Indicates whether the flags should be set or cleared.

Throws:

MessagingException - if there was a problem accessing the store

copyMessages

public void copyMessages(Message[] messages,
                         Folder folder)
                  throws MessagingException

Copy the specified messages to another folder. The default implementation simply appends the supplied messages to the target folder using appendMessages(Message[]).

Overrides:

copyMessages in class Folder

Parameters:

messages - the messages to copy

folder - the folder to copy to

Throws:

MessagingException - if there was a problem accessing the store

expunge

public Message[] expunge()
                  throws MessagingException

Permanently delete all supplied messages that have the DELETED flag set from the Store. The original message indices of all messages actually deleted are returned and a MessageCountEvent event is sent to all listeners with this folder. The expunge may cause the indices of all messaged that remain in the folder to change.

Specified by:

expunge in class Folder

Returns:

the original indices of messages that were actually deleted

Throws:

MessagingException - if there was a problem accessing the store

search

public Message[] search(SearchTerm term)
                 throws MessagingException

Search the supplied messages for those that match the supplied criteria; messages must belong to this folder. The default implementation iterates through the messages, returning those whose Message.match(javax.mail.search.SearchTerm) method returns true; subclasses may provide a more efficient implementation.

Overrides:

search in class Folder

Parameters:

term - the search criteria

messages - the messages to search

Returns:

an array containing messages that match the criteria

Throws:

MessagingException - if there was a problem accessing the store

search

public Message[] search(SearchTerm term,
                        Message[] messages)
                 throws MessagingException

Search the supplied messages for those that match the supplied criteria; messages must belong to this folder. The default implementation iterates through the messages, returning those whose Message.match(javax.mail.search.SearchTerm) method returns true; subclasses may provide a more efficient implementation.

Overrides:

search in class Folder

Parameters:

term - the search criteria

messages - the messages to search

Returns:

an array containing messages that match the criteria

Throws:

MessagingException - if there was a problem accessing the store

getUIDValidity

public long getUIDValidity()
                    throws MessagingException

Get the UID validity value for this Folder.

Specified by:

getUIDValidity in interface UIDFolder

Returns:

The current UID validity value, as a long.

Throws:

MessagingException

getMessageByUID

public Message getMessageByUID(long uid)
                        throws MessagingException

Retrieve a message using the UID rather than the message sequence number. Returns null if the message doesn't exist.

Specified by:

getMessageByUID in interface UIDFolder

Parameters:

uid - The target UID.

Returns:

the Message object. Returns null if the message does not exist.

Throws:

MessagingException

getMessagesByUID

public Message[] getMessagesByUID(long start,
                                  long end)
                           throws MessagingException

Get a series of messages using a UID range. The special value LASTUID can be used to mark the last available message.

Specified by:

getMessagesByUID in interface UIDFolder

Parameters:

start - The start of the UID range.

end - The end of the UID range. The special value LASTUID can be used to request all messages up to the last UID.

Returns:

An array containing all of the messages in the range.

Throws:

MessagingException

getMessagesByUID

public Message[] getMessagesByUID(long[] ids)
                           throws MessagingException

Retrieve a set of messages by explicit UIDs. If any message in the list does not exist, null will be returned for the corresponding item.

Specified by:

getMessagesByUID in interface UIDFolder

Parameters:

ids - An array of UID values to be retrieved.

Returns:

An array of Message items the same size as the ids argument array. This array will contain null entries for any UIDs that do not exist.

Throws:

MessagingException

getUID

public long getUID(Message message)
            throws MessagingException

Retrieve the UID for a message from this Folder. The argument Message MUST belong to this Folder instance, otherwise a NoSuchElementException will be thrown.

Specified by:

getUID in interface UIDFolder

Parameters:

message - The target message.

Returns:

The UID associated with this message.

Throws:

MessagingException

retrieveMessageByUid

protected Message retrieveMessageByUid(Long key,
                                       int msgNumber)
                                throws MessagingException

Retrieve a message from a UID/message mapping.

Parameters:

key - The UID key used for the mapping.

msgNumber - The message sequence number.

Returns:

The Message object corresponding to the message.

Throws:

MessagingException

addToUidCache

protected void addToUidCache(Long key,
                             Message msg)

Add a message to the UID mapping cache, ensuring that the UID value is updated.

Parameters:

key - The UID key.

msg - The message to add.

appendMessage

protected void appendMessage(Message msg)
                      throws MessagingException

Append a single message to the IMAP Folder.

Parameters:

msg - The message to append.

Throws:

MessagingException

filterFolders

protected Folder[] filterFolders(String pattern,
                                 boolean subscribed)
                          throws MessagingException

Retrieve the list of matching groups from the IMAP server using the LIST or LSUB command. The server does the wildcard matching for us.

Parameters:

pattern - The pattern string (in wildmat format) used to match.

Returns:

An array of folders for the matching groups.

Throws:

MessagingException

holdsFolders

protected boolean holdsFolders()
                        throws MessagingException

Test if a folder can hold sub folders.

Returns:

True if the folder is allowed to have subfolders.

Throws:

MessagingException

checkMessageValidity

protected void checkMessageValidity(int messageNumber)
                             throws MessagingException

Validate that a target message number is considered valid by the IMAP server. If outside of the range we currently are a ware of, we'll ping the IMAP server to see if there have been any updates.

Parameters:

messageNumber - The message number we're checking.

Throws:

MessagingException

checkOpen

protected void checkOpen()
                  throws IllegalStateException

Ensure the folder is open. Throws a MessagingException if not in the correct state for the operation.

Throws:

IllegalStateException

checkClosed

protected void checkClosed()
                    throws IllegalStateException

Ensure the folder is not open for operations that require the folder to be closed.

Throws:

IllegalStateException

checkReadWrite

protected void checkReadWrite()
                       throws IllegalStateException

Ensure that the folder is open for read/write mode before doing an operation that would make a change.

Throws:

IllegalStateException

checkOpenReadWrite

protected void checkOpenReadWrite()
                           throws IllegalStateException

Check that the folder is open and in read/write mode.

Throws:

IllegalStateException

notifyMessageChangedListeners

public void notifyMessageChangedListeners(int type,
                                          Message m)

Notify the message changed listeners that a message contained in the folder has been updated.

Overrides:

notifyMessageChangedListeners in class Folder

Parameters:

type - The type of update made to the message.

m - The message that was updated.

See Also:

Folder.notifyMessageChangedListeners(int, javax.mail.Message)

getConnection

protected IMAPConnection getConnection()
                                throws MessagingException

Retrieve the connection attached to this folder. Throws an exception if we don't have an active connection.

Returns:

The current connection object.

Throws:

MessagingException

releaseConnection

protected void releaseConnection(IMAPConnection connection)
                          throws MessagingException

Release our connection back to the Store.

Parameters:

connection - The connection to release.

Throws:

MessagingException

refreshStatus

protected void refreshStatus(boolean force)
                      throws MessagingException

Refresh the status information on this folder.

Parameters:

force - Force a status refresh always.

Throws:

MessagingException

expungeMessage

protected Message expungeMessage(int sequenceNumber)
                          throws MessagingException

Process an EXPUNGE response for a message, removing the message from the message cache.

Parameters:

sequenceNumber - The sequence number for the expunged message.

Returns:

The Message object corresponding to this expunged message.

Throws:

MessagingException

resolveMessages

protected Message[] resolveMessages(int[] messageNumbers)
                             throws MessagingException

Resolve an array of message numbers into an array of the referenced messages.

Parameters:

messageNumbers - The array of message numbers (can be null).

Returns:

An array of Message[] containing the resolved messages from the list. Returns a zero-length array if there are no messages to resolve.

Throws:

MessagingException

generateMessageSet

protected String generateMessageSet(List messages)
                             throws MessagingException

Generate a message set string from a List of messages rather than an array.

Parameters:

messages - The List of messages.

Returns:

The evaluated message set string.

Throws:

MessagingException

generateMessageSet

protected String generateMessageSet(Message[] messages)
                             throws MessagingException

Take an array of messages and generate a String argument as specified by RFC 2060. The message set argument is a comma-separated list of message number ranges. A single element range is just one number. A longer range is a pair of numbers separated by a ":". The generated string should not have any blanks. This will attempt to locate consequetive ranges of message numbers, but will only do this for messages that are already ordered in the array (i.e., we don't try to sort). Expunged messages are excluded from the search, since they don't exist anymore. A valid search string will look something like this: "3,6:10,15,21:35"

Parameters:

messages - The array of messages we generate from.

Returns:

A string formatted version of these message identifiers that can be used on an IMAP command.

Throws:

MessagingException

checkFolderValidity

protected void checkFolderValidity()
                            throws MessagingException

Verify that this folder exists on the server before performning an operation that requires a valid Folder instance.

Throws:

MessagingException

checkMessageFolder

protected void checkMessageFolder(Message msg)
                           throws MessagingException

Check if a Message is properly within the target folder.

Parameters:

msg - The message we're checking.

Throws:

MessagingException

findListResponse

protected IMAPListResponse findListResponse(List responses,
                                            String name)

Search a list of LIST responses for one containing information for a particular mailbox name.

Parameters:

responses - The list of responses.

name - The desired mailbox name.

Returns:

The IMAPListResponse information for the requested name.

getMailBoxName

protected String getMailBoxName()

Protected class intended for subclass overrides. For normal folders, the mailbox name is fullname. For Namespace root folders, the mailbox name is the prefix + separator.

Returns:

The string name to use as the mailbox name for exists() and issubscribed() calls.

handleResponse

public boolean handleResponse(IMAPUntaggedResponse response)

Handle an unsolicited response from the server. Most unsolicited responses are replies to specific commands sent to the server. The remainder must be handled by the Store or the Folder using the connection. These are critical to handle, as events such as expunged messages will alter the sequence numbers of the live messages. We need to keep things in sync.

Specified by:

handleResponse in interface IMAPUntaggedResponseHandler

Parameters:

response - The UntaggedResponse to process.

Returns:

true if we handled this response and no further handling is required. false means this one wasn't one of ours.

removeACL

public void removeACL(ACL acl)
               throws MessagingException

Remove an entry from the access control list for this folder.

Parameters:

acl - The ACL element to remove.

Throws:

MessagingException

addACL

public void addACL(ACL acl)
            throws MessagingException

Add an entry to the access control list for this folder.

Parameters:

acl - The new ACL to add.

Throws:

MessagingException

addRights

public void addRights(ACL acl)
               throws MessagingException

Add Rights to a given ACL entry.

Parameters:

acl - The target ACL to update.

Throws:

MessagingException

removeRights

public void removeRights(ACL acl)
                  throws MessagingException

Remove ACL Rights from a folder.

Parameters:

acl - The ACL describing the Rights to remove.

Throws:

MessagingException

listRights

public Rights[] listRights(String name)
                    throws MessagingException

List the rights associated with a given name.

Parameters:

name - The user name for the Rights.

Returns:

The set of Rights associated with the user name.

Throws:

MessagingException

myRights

public Rights myRights()
                throws MessagingException

List the rights for the currently authenticated user.

Returns:

The set of Rights for the current user.

Throws:

MessagingException

getQuota

public Quota[] getQuota()
                 throws MessagingException

Get the quota values assigned to the current folder.

Returns:

The Quota information for the folder.

Throws:

MessagingException

setQuota

public void setQuota(Quota quota)
              throws MessagingException

Set the quota value for a quota root

Parameters:

quota - The new quota information to set.

Throws:

MessagingException

getAttributes

public String[] getAttributes()
                       throws MessagingException

Get the set of attributes defined for the folder as the set of capabilities returned when the folder was opened.

Returns:

The set of attributes associated with the folder.

Throws:

MessagingException