gnu.mail.providers.imap
Class IMAPFolder

java.lang.Object
  extended by javax.mail.Folder
      extended by 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  java.lang.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, java.lang.String path)
          Constructor.
protected IMAPFolder(Store store, java.lang.String path, char delimiter)
          Constructor.
protected IMAPFolder(Store store, java.lang.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(java.lang.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(java.lang.String name)
          Returns a subfolder with the specified name.
 java.lang.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(java.lang.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.
 java.lang.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(java.lang.String pattern)
          Returns the subfolders for this folder.
 Rights listRights(java.lang.String name)
          Deprecated. this API will probably change incompatibly soon
 Folder[] listSubscribed(java.lang.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(java.lang.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 java.lang.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,
                     java.lang.String path)
Constructor.


IMAPFolder

protected IMAPFolder(Store store,
                     java.lang.String path,
                     char delimiter)
Constructor.


IMAPFolder

protected IMAPFolder(Store store,
                     java.lang.String path,
                     int type,
                     char delimiter)
Constructor.

Method Detail

getName

public java.lang.String getName()
Returns the name of this folder.

Specified by:
getName in class Folder

getFullName

public java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.Object other)
Overrides:
equals in class java.lang.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(java.lang.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(java.lang.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(java.lang.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


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