gnu.mail.providers.imap
Class IMAPFolder

java.lang.Object
  javax.mail.Folder
      gnu.mail.providers.imap.IMAPFolder

All Implemented Interfaces:

UIDFolder

public class IMAPFolder
extends Folder
implements UIDFolder

The folder class implementing the IMAP4rev1 mail protocol.

Author:

Chris Burdess

Nested Class Summary

Nested classes/interfaces inherited from interface javax.mail.UIDFolder

UIDFolder.FetchProfileItem

Field Summary

protected char	delimiter
protected int	messageCount
protected int	newMessageCount
protected String	path The folder path.
protected Flags	permanentFlags
protected boolean	subscribed
protected int	type The type of this folder (HOLDS_MESSAGES or HOLDS_FOLDERS).
protected long	uidValidity

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(Store store, String path) Constructor.
protected	IMAPFolder(Store store, String path, char delimiter) Constructor.
protected	IMAPFolder(Store store, String path, int type, char delimiter) Constructor.

Method Summary

void	addACL(ACL ace) Deprecated. this API will probably change incompatibly soon
void	addRights(ACL ace) Deprecated. this API will probably change incompatibly soon
void	appendMessages(Message[] messages) Appends the specified set of messages to this folder.
void	close(boolean expunge) Closes this folder.
boolean	create(int type) Create this folder.
boolean	delete(boolean flag) Delete this folder.
boolean	equals(Object other)
boolean	exists() Indicates whether this folder exists.
Message[]	expunge() Expunges this folder.
void	fetch(Message[] messages, FetchProfile fp) IMAP fetch routine.
ACL[]	getACL() Deprecated. this API will probably change incompatibly soon
int	getDeletedMessageCount() Returns the number of deleted messages in this folder.
Folder	getFolder(String name) Returns a subfolder with the specified name.
String	getFullName() Returns the full path of this folder.
Message	getMessage(int msgnum) Returns the specified message number from this folder.
Message	getMessageByUID(long uid) Returns the message corresponding to the given UID, or null if no such message exists.
int	getMessageCount() Returns the number of messages in this folder.
int	getMessageCountByCriteria(String criteria) Convenience method for returning the number of messages in the current folder that match the single criteria.
Message[]	getMessagesByUID(long[] uids) Returns the messages specified by the given UIDs.
Message[]	getMessagesByUID(long start, long end) Returns the messages in the given range.
String	getName() Returns the name of this folder.
int	getNewMessageCount() Returns the number of new messages in this folder.
Folder	getParent() Returns the parent folder of this folder.
Flags	getPermanentFlags() Returns the permanent flags for this folder.
Quota[]	getQuota() Returns the quotas for this folder.
char	getSeparator() Returns the path separator charcter.
int	getType() Returns the type of this folder.
long	getUID(Message message) Returns the UID for the specified message.
long	getUIDValidity() Returns the UIDValidity value associated with this folder.
int	getUnreadMessageCount() Returns the number of unread messages in this folder.
boolean	hasNewMessages() Indicates whether this folder contains new messages.
boolean	isOpen() Indicates whether this folder is open.
boolean	isSubscribed() Indicates whether this folder is subscribed.
Folder[]	list(String pattern) Returns the subfolders for this folder.
Rights	listRights(String name) Deprecated. this API will probably change incompatibly soon
Folder[]	listSubscribed(String pattern) Returns the subscribed subfolders for this folder.
Rights	myRights() Deprecated. this API will probably change incompatibly soon
void	open(int mode) Opens this folder.
void	removeACL(String name) Deprecated. this API will probably change incompatibly soon
void	removeRights(ACL ace) Deprecated. this API will probably change incompatibly soon
boolean	renameTo(Folder folder) Rename this folder.
Message[]	search(SearchTerm term) IMAP search function.
Message[]	search(SearchTerm term, Message[] msgs) IMAP search function.
void	setSubscribed(boolean flag) Subscribe to or unsubscribe from this folder.

Methods inherited from class javax.mail.Folder

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

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

path

protected String path

The folder path.

type

protected int type

The type of this folder (HOLDS_MESSAGES or HOLDS_FOLDERS).

permanentFlags

protected Flags permanentFlags

delimiter

protected char delimiter

messageCount

protected int messageCount

newMessageCount

protected int newMessageCount

uidValidity

protected long uidValidity

subscribed

protected boolean subscribed

Constructor Detail

IMAPFolder

protected IMAPFolder(Store store,
                     String path)

Constructor.

IMAPFolder

protected IMAPFolder(Store store,
                     String path,
                     char delimiter)

Constructor.

IMAPFolder

protected IMAPFolder(Store store,
                     String path,
                     int type,
                     char delimiter)

Constructor.

Method Detail

getName

public String getName()

Returns the name of this folder.

Specified by:

getName in class Folder

getFullName

public String getFullName()

Returns the full path of this folder.

Specified by:

getFullName in class Folder

getType

public int getType()
            throws MessagingException

Returns the type of this folder.

Specified by:

getType in class Folder

Throws:

MessagingException - if a messaging error occurred

exists

public boolean exists()
               throws MessagingException

Indicates whether this folder exists.

Specified by:

exists in class Folder

Throws:

MessagingException - if a messaging error occurred

hasNewMessages

public boolean hasNewMessages()
                       throws MessagingException

Indicates whether this folder contains new messages.

Specified by:

hasNewMessages in class Folder

Throws:

MessagingException - if a messaging error occurred

open

public void open(int mode)
          throws MessagingException

Opens this folder.

Specified by:

open in class Folder

Parameters:

mode - open the Folder READ_ONLY or READ_WRITE

Throws:

MessagingException - if a messaging error occurred

create

public boolean create(int type)
               throws MessagingException

Create this folder.

Specified by:

create in class Folder

Parameters:

type - the desired type of the folder

Throws:

MessagingException

delete

public boolean delete(boolean flag)
               throws MessagingException

Delete this folder.

Specified by:

delete in class Folder

Parameters:

flag - delete any subfolders

Returns:

true if the folder is deleted successfully, false otherwise

Throws:

FolderNotFoundException - if this folder does not exist

MessagingException

renameTo

public boolean renameTo(Folder folder)
                 throws MessagingException

Rename this folder.

Specified by:

renameTo in class Folder

Parameters:

folder - a folder representing the new name for this folder

Returns:

true if the folder is renamed successfully, false otherwise

Throws:

FolderNotFoundException - if this folder does not exist

MessagingException

close

public void close(boolean expunge)
           throws MessagingException

Closes this folder.

Specified by:

close in class Folder

Parameters:

expunge - if the folder is to be expunged before it is closed

Throws:

MessagingException - if a messaging error occurred

expunge

public Message[] expunge()
                  throws MessagingException

Expunges this folder. This deletes all the messages marked as deleted.

Specified by:

expunge in class Folder

Throws:

MessagingException - if a messaging error occurred

isOpen

public boolean isOpen()

Indicates whether this folder is open.

Specified by:

isOpen in class Folder

getPermanentFlags

public Flags getPermanentFlags()

Returns the permanent flags for this folder.

Specified by:

getPermanentFlags in class Folder

getMessageCount

public int getMessageCount()
                    throws MessagingException

Returns the number of messages in this folder.

Specified by:

getMessageCount in class Folder

Throws:

MessagingException - if a messaging error occurred

getNewMessageCount

public int getNewMessageCount()
                       throws MessagingException

Returns the number of new messages in this folder.

Overrides:

getNewMessageCount in class Folder

Throws:

MessagingException - if a messaging error occurred

getMessage

public Message getMessage(int msgnum)
                   throws MessagingException

Returns the specified message number from this folder. The message is only retrieved once from the server. Subsequent getMessage() calls to the same message are cached. Since POP3 does not provide a mechanism for retrieving only part of the message(headers, etc), the entire message is retrieved.

Specified by:

getMessage in class Folder

Parameters:

msgnum - the message number

Throws:

MessagingException - if a messaging error occurred

appendMessages

public void appendMessages(Message[] messages)
                    throws MessagingException

Appends the specified set of messages to this folder. Only MimeMessages are accepted.

Specified by:

appendMessages in class Folder

Parameters:

messages - array of messages to be appended

Throws:

FolderNotFoundException - if this folder does not exist

MessagingException - if the append operation failed

fetch

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

IMAP fetch routine. This executes the fetch for the specified message numbers and updates the messages according to the message statuses returned.

Overrides:

fetch in class Folder

Parameters:

messages - the messages to fetch the items for

fp - the fetch profile

Throws:

MessagingException

search

public Message[] search(SearchTerm term)
                 throws MessagingException

IMAP search function.

Overrides:

search in class Folder

Parameters:

term - the search term

Throws:

FolderNotFoundException - if this folder does not exist

MessagingException

search

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

IMAP search function.

Overrides:

search in class Folder

Parameters:

term - the search term

msgs - the messages to be searched

Throws:

MessagingException

isSubscribed

public boolean isSubscribed()

Description copied from class: Folder

Indicates whether this folder is subscribed.

This method can be invoked on a closed folder.

Overrides:

isSubscribed in class Folder

setSubscribed

public void setSubscribed(boolean flag)
                   throws MessagingException

Description copied from class: Folder

Subscribe to or unsubscribe from this folder. Not all Stores support subscription.

This method can be invoked on a closed folder.

Overrides:

setSubscribed in class Folder

Throws:

MessagingException

list

public Folder[] list(String pattern)
              throws MessagingException

Returns the subfolders for this folder.

Specified by:

list in class Folder

Parameters:

pattern - the match pattern

Throws:

MessagingException

listSubscribed

public Folder[] listSubscribed(String pattern)
                        throws MessagingException

Returns the subscribed subfolders for this folder.

Overrides:

listSubscribed in class Folder

Parameters:

pattern - the match pattern

Throws:

MessagingException

getParent

public Folder getParent()
                 throws MessagingException

Returns the parent folder of this folder.

Specified by:

getParent in class Folder

Throws:

MessagingException

getFolder

public Folder getFolder(String name)
                 throws MessagingException

Returns a subfolder with the specified name.

Specified by:

getFolder in class Folder

Parameters:

name - the name of the folder

Throws:

MessagingException

getSeparator

public char getSeparator()
                  throws MessagingException

Returns the path separator charcter.

Specified by:

getSeparator in class Folder

Throws:

MessagingException

equals

public boolean equals(Object other)

Overrides:

equals in class Object

getUIDValidity

public long getUIDValidity()
                    throws MessagingException

Description copied from interface: UIDFolder

Returns the UIDValidity value associated with this folder.

A client should compare this value against a UIDValidity value saved from a previous session to ensure that any cached UIDs are valid.

Specified by:

getUIDValidity in interface UIDFolder

Throws:

MessagingException

getMessageByUID

public Message getMessageByUID(long uid)
                        throws MessagingException

Description copied from interface: UIDFolder

Returns the message corresponding to the given UID, or null if no such message exists.

Specified by:

getMessageByUID in interface UIDFolder

Parameters:

uid - the UID of the desired message

Throws:

MessagingException

getMessagesByUID

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

Description copied from interface: UIDFolder

Returns the messages in the given range. The special value LASTUID can be used as the end parameter to indicate the last available UID.

Specified by:

getMessagesByUID in interface UIDFolder

Parameters:

start - the start UID

end - the end UID

Throws:

MessagingException

getMessagesByUID

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

Description copied from interface: UIDFolder

Returns the messages specified by the given UIDs. If any UID is invalid, null is returned for that entry.

The returned array will be of the same size as the specified UIDs.

Specified by:

getMessagesByUID in interface UIDFolder

Parameters:

uids - the UIDs

Throws:

MessagingException

getUID

public long getUID(Message message)
            throws MessagingException

Description copied from interface: UIDFolder

Returns the UID for the specified message.

Specified by:

getUID in interface UIDFolder

Parameters:

message - a message in this folder

Throws:

MessagingException

getQuota

public Quota[] getQuota()
                 throws MessagingException

Returns the quotas for this folder.

Throws:

MessagingException

getUnreadMessageCount

public int getUnreadMessageCount()
                          throws MessagingException

Returns the number of unread messages in this folder.

Overrides:

getUnreadMessageCount in class Folder

Throws:

MessagingException

See Also:

Folder.getUnreadMessageCount()

getDeletedMessageCount

public int getDeletedMessageCount()
                           throws MessagingException

Returns the number of deleted messages in this folder.

Overrides:

getDeletedMessageCount in class Folder

Throws:

FolderNotFoundException - if this folder does not exist

MessagingException

See Also:

Folder.getDeletedMessageCount()

getMessageCountByCriteria

public int getMessageCountByCriteria(String criteria)
                              throws MessagingException

Convenience method for returning the number of messages in the current folder that match the single criteria.

Throws:

MessagingException

getACL

public ACL[] getACL()
             throws MessagingException

Deprecated. this API will probably change incompatibly soon

Returns the access control list for this folder. This is an array of access control entries.

Throws:

MessagingException

addACL

public void addACL(ACL ace)
            throws MessagingException

Deprecated. this API will probably change incompatibly soon

Adds the specified access control entry to this folder.

Parameters:

ace - the access control entry

Throws:

MessagingException

removeACL

public void removeACL(String name)
               throws MessagingException

Deprecated. this API will probably change incompatibly soon

Removes the ACL for the given principal.

Parameters:

name - the name of the principal

Throws:

MessagingException

addRights

public void addRights(ACL ace)
               throws MessagingException

Deprecated. this API will probably change incompatibly soon

Adds the rights for the specified access control entry.

Parameters:

ace - the access control entry

Throws:

MessagingException

removeRights

public void removeRights(ACL ace)
                  throws MessagingException

Deprecated. this API will probably change incompatibly soon

Removes the rights specified in the given access control entry from the principal.

Parameters:

ace - the access control entry

Throws:

MessagingException

listRights

public Rights listRights(String name)
                  throws MessagingException

Deprecated. this API will probably change incompatibly soon

Returns the rights currently assigned to the given principal.

Parameters:

name - the name of the principal

Throws:

MessagingException

myRights

public Rights myRights()
                throws MessagingException

Deprecated. this API will probably change incompatibly soon

Returns the rights assigned to the currently authenticated principal.

Throws:

MessagingException