gnu.mail.providers.imap

Class IMAPFolder

Implemented Interfaces:
UIDFolder

public class IMAPFolder
extends Folder
implements UIDFolder

The folder class implementing the IMAP4rev1 mail protocol.
Author:
Chris Burdess

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, READ_ONLY, READ_WRITE, mode, store

Fields inherited from interface javax.mail.UIDFolder

LASTUID

Constructor Summary

IMAPFolder(Store store, String path)
Constructor.
IMAPFolder(Store store, String path, char delimiter)
Constructor.
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 start, long end)
Returns the messages in the given range.
Message[]
getMessagesByUID(long[] uids)
Returns the messages specified by the given UIDs.
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, appendMessages, close, copyMessages, create, delete, exists, expunge, fetch, getDeletedMessageCount, getFolder, getFullName, getMessage, getMessageCount, getMessages, getMessages, getMessages, getMode, getName, getNewMessageCount, getParent, getPermanentFlags, getSeparator, getStore, getType, getURLName, getUnreadMessageCount, hasNewMessages, isOpen, isSubscribed, list, list, listSubscribed, listSubscribed, notifyConnectionListeners, notifyFolderListeners, notifyFolderRenamedListeners, notifyMessageAddedListeners, notifyMessageChangedListeners, notifyMessageRemovedListeners, open, removeConnectionListener, removeFolderListener, removeMessageChangedListener, removeMessageCountListener, renameTo, search, search, setFlags, setFlags, setFlags, setSubscribed, toString

Field Details

delimiter

protected char delimiter

messageCount

protected int messageCount

newMessageCount

protected int newMessageCount

path

protected String path
The folder path.

permanentFlags

protected Flags permanentFlags

subscribed

protected boolean subscribed

type

protected int type
The type of this folder (HOLDS_MESSAGES or HOLDS_FOLDERS).

uidValidity

protected long uidValidity

Constructor Details

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 Details

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

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

appendMessages

public void appendMessages(Message[] messages)
            throws MessagingException
Appends the specified set of messages to this folder. Only MimeMessages are accepted.
Overrides:
appendMessages in interface Folder

close

public void close(boolean expunge)
            throws MessagingException
Closes this folder.
Overrides:
close in interface Folder
Parameters:
expunge - if the folder is to be expunged before it is closed
Throws:
MessagingException - if a messaging error occurred

create

public boolean create(int type)
            throws MessagingException
Create this folder.
Overrides:
create in interface Folder

delete

public boolean delete(boolean flag)
            throws MessagingException
Delete this folder.
Overrides:
delete in interface Folder

equals

public boolean equals(Object other)

exists

public boolean exists()
            throws MessagingException
Indicates whether this folder exists.
Overrides:
exists in interface Folder
Throws:
MessagingException - if a messaging error occurred

expunge

public Message[] expunge()
            throws MessagingException
Expunges this folder. This deletes all the messages marked as deleted.
Overrides:
expunge in interface Folder
Throws:
MessagingException - if a messaging error occurred

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 interface Folder

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.

getDeletedMessageCount

public int getDeletedMessageCount()
            throws MessagingException
Returns the number of deleted messages in this folder.
Overrides:
getDeletedMessageCount in interface Folder

getFolder

public Folder getFolder(String name)
            throws MessagingException
Returns a subfolder with the specified name.
Overrides:
getFolder in interface Folder

getFullName

public String getFullName()
Returns the full path of this folder.
Overrides:
getFullName in interface Folder

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.
Overrides:
getMessage in interface Folder
Throws:
MessagingException - if a messaging error occurred

getMessageByUID

public Message getMessageByUID(long uid)
            throws MessagingException
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

getMessageCount

public int getMessageCount()
            throws MessagingException
Returns the number of messages in this folder.
Overrides:
getMessageCount in interface Folder
Throws:
MessagingException - if a messaging error occurred

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.

getMessagesByUID

public Message[] getMessagesByUID(long start,
                                  long end)
            throws MessagingException
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

getMessagesByUID

public Message[] getMessagesByUID(long[] uids)
            throws MessagingException
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

getName

public String getName()
Returns the name of this folder.
Overrides:
getName in interface Folder

getNewMessageCount

public int getNewMessageCount()
            throws MessagingException
Returns the number of new messages in this folder.
Overrides:
getNewMessageCount in interface Folder
Throws:
MessagingException - if a messaging error occurred

getParent

public Folder getParent()
            throws MessagingException
Returns the parent folder of this folder.
Overrides:
getParent in interface Folder

getPermanentFlags

public Flags getPermanentFlags()
Returns the permanent flags for this folder.
Overrides:
getPermanentFlags in interface Folder

getQuota

public Quota[] getQuota()
            throws MessagingException
Returns the quotas for this folder.

getSeparator

public char getSeparator()
            throws MessagingException
Returns the path separator charcter.
Overrides:
getSeparator in interface Folder

getType

public int getType()
            throws MessagingException
Returns the type of this folder.
Overrides:
getType in interface Folder
Throws:
MessagingException - if a messaging error occurred

getUID

public long getUID(Message message)
            throws MessagingException
Returns the UID for the specified message.
Specified by:
getUID in interface UIDFolder
Parameters:
message - a message in this folder

getUIDValidity

public long getUIDValidity()
            throws MessagingException
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

getUnreadMessageCount

public int getUnreadMessageCount()
            throws MessagingException
Returns the number of unread messages in this folder.
Overrides:
getUnreadMessageCount in interface Folder

hasNewMessages

public boolean hasNewMessages()
            throws MessagingException
Indicates whether this folder contains new messages.
Overrides:
hasNewMessages in interface Folder
Throws:
MessagingException - if a messaging error occurred

isOpen

public boolean isOpen()
Indicates whether this folder is open.
Overrides:
isOpen in interface Folder

isSubscribed

public boolean isSubscribed()
Indicates whether this folder is subscribed.

This method can be invoked on a closed folder.

Overrides:
isSubscribed in interface Folder

list

public Folder[] list(String pattern)
            throws MessagingException
Returns the subfolders for this folder.
Overrides:
list in interface Folder

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

listSubscribed

public Folder[] listSubscribed(String pattern)
            throws MessagingException
Returns the subscribed subfolders for this folder.
Overrides:
listSubscribed in interface Folder

myRights

public Rights myRights()
            throws MessagingException

Deprecated. this API will probably change incompatibly soon

Returns the rights assigned to the currently authenticated principal.

open

public void open(int mode)
            throws MessagingException
Opens this folder.
Overrides:
open in interface Folder
Throws:
MessagingException - if a messaging error occurred

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

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

renameTo

public boolean renameTo(Folder folder)
            throws MessagingException
Rename this folder.
Overrides:
renameTo in interface Folder

search

public Message[] search(SearchTerm term)
            throws MessagingException
IMAP search function.
Overrides:
search in interface Folder

search

public Message[] search(SearchTerm term,
                        Message[] msgs)
            throws MessagingException
IMAP search function.
Overrides:
search in interface Folder

setSubscribed

public void setSubscribed(boolean flag)
            throws MessagingException
Subscribe to or unsubscribe from this folder. Not all Stores support subscription.

This method can be invoked on a closed folder.

Overrides:
setSubscribed in interface Folder

© Copyright 2003, 2004 The Free Software Foundation, All rights reserved