Module org.eclipse.angus.mail
Package org.eclipse.angus.mail.imap

Class IMAPFolder

java.lang.Object
jakarta.mail.Folder
org.eclipse.angus.mail.imap.IMAPFolder
All Implemented Interfaces:
UIDFolder, AutoCloseable, org.eclipse.angus.mail.iap.ResponseHandler
Direct Known Subclasses:
GmailFolder
public class IMAPFolder extends Folder implements UIDFolder, org.eclipse.angus.mail.iap.ResponseHandler
This class implements an IMAP folder.

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

Applications that need to make use of IMAP-specific features may cast a Folder object to an IMAPFolder object and use the methods on this class.

The getQuota and setQuota methods support the IMAP QUOTA extension. Refer to RFC 2087 for more information.

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

The getSortedMessages methods support the IMAP SORT extension. Refer to RFC 5256 for more information.

The open(int,ResyncData) method and ResyncData class supports the IMAP CONDSTORE and QRESYNC extensions. Refer to RFC 4551 and RFC 5162 for more information.

The doCommand method and IMAPFolder.ProtocolCommand interface support use of arbitrary IMAP protocol commands.

See the org.eclipse.angus.mail.imap package documentation for further information on the IMAP protocol provider.

WARNING: The APIs unique to this class should be considered EXPERIMENTAL. They may be changed in the future in ways that are incompatible with applications using the current APIs.

  • Field Details

    • fullName

      protected volatile String fullName

    • name

      protected String name

    • type

      protected int type

    • separator

      protected char separator

    • availableFlags

      protected Flags availableFlags

    • permanentFlags

      protected Flags permanentFlags

    • exists

      protected volatile boolean exists

    • isNamespace

      protected boolean isNamespace

    • attributes

      protected volatile String[] attributes

    • protocol

      protected volatile org.eclipse.angus.mail.imap.protocol.IMAPProtocol protocol

    • messageCache

      protected org.eclipse.angus.mail.imap.MessageCache messageCache

    • messageCacheLock

      protected final Object messageCacheLock

    • uidTable

      protected Hashtable<Long,IMAPMessage> uidTable

    • UNKNOWN_SEPARATOR

      protected static final char UNKNOWN_SEPARATOR
      See Also:

    • logger

      protected org.eclipse.angus.mail.util.MailLogger logger

  • Constructor Details

    • IMAPFolder

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

    • IMAPFolder

      protected IMAPFolder(org.eclipse.angus.mail.imap.protocol.ListInfo li, IMAPStore store)
      Constructor used to create an existing folder.
      Parameters:
      li - the ListInfo for this folder
      store - the store containing this folder

  • Method Details

    • checkExists

      protected void checkExists() throws MessagingException
      Throws:
      MessagingException

    • checkClosed

      protected void checkClosed()

    • checkOpened

      protected void checkOpened() throws FolderClosedException
      Throws:
      FolderClosedException

    • checkRange

      protected void checkRange(int msgno) throws MessagingException
      Throws:
      MessagingException

    • getName

      public String getName()
      Get the name of this folder.
      Specified by:
      getName in class Folder
      Returns:
      name of the Folder

    • getFullName

      public String getFullName()
      Get the fullname of this folder.
      Specified by:
      getFullName in class Folder
      Returns:
      full name of the Folder

    • getParent

      public Folder getParent() throws MessagingException
      Get this folder's parent.
      Specified by:
      getParent in class Folder
      Returns:
      Parent folder
      Throws:
      MessagingException - for failures

    • exists

      public boolean exists() throws MessagingException
      Check whether this folder really exists on the server.
      Specified by:
      exists in class Folder
      Returns:
      true if the folder exists, otherwise false
      Throws:
      MessagingException - typically if the connection to the server is lost.
      See Also:

    • list

      public Folder[] list(String pattern) throws MessagingException
      List all subfolders matching the specified pattern.
      Specified by:
      list in class Folder
      Parameters:
      pattern - the match pattern
      Returns:
      array of matching Folder objects. An empty array is returned if no matching Folders exist.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures
      See Also:

    • listSubscribed

      public Folder[] listSubscribed(String pattern) throws MessagingException
      List all subscribed subfolders matching the specified pattern.
      Overrides:
      listSubscribed in class Folder
      Parameters:
      pattern - the match pattern
      Returns:
      array of matching subscribed Folder objects. An empty array is returned if no matching subscribed folders exist.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures
      See Also:

    • getSeparator

      public char getSeparator() throws MessagingException
      Get the separator character.
      Specified by:
      getSeparator in class Folder
      Returns:
      Hierarchy separator character
      Throws:
      FolderNotFoundException - if the implementation requires the folder to exist, but it does not
      MessagingException

    • getType

      public int getType() throws MessagingException
      Get the type of this folder.
      Specified by:
      getType in class Folder
      Returns:
      integer with appropriate bits set
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException
      See Also:

    • isSubscribed

      public boolean isSubscribed()
      Check whether this folder is subscribed.
      Overrides:
      isSubscribed in class Folder
      Returns:
      true if this Folder is subscribed

    • setSubscribed

      public void setSubscribed(boolean subscribe) throws MessagingException
      Subscribe/Unsubscribe this folder.
      Overrides:
      setSubscribed in class Folder
      Parameters:
      subscribe - true to subscribe, false to unsubscribe
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MethodNotSupportedException - if this store does not support subscription
      MessagingException - for other failures

    • create

      public boolean create(int type) throws MessagingException
      Create this folder, with the specified type.
      Specified by:
      create in class Folder
      Parameters:
      type - The type of this folder.
      Returns:
      true if the creation succeeds, else false.
      Throws:
      MessagingException - for failures
      See Also:

    • hasNewMessages

      public boolean hasNewMessages() throws MessagingException
      Check whether this folder has new messages.
      Specified by:
      hasNewMessages in class Folder
      Returns:
      true if the Store has new Messages
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures

    • getFolder

      public Folder getFolder(String name) throws MessagingException
      Get the named subfolder.
      Specified by:
      getFolder in class Folder
      Parameters:
      name - name of the Folder
      Returns:
      Folder object
      Throws:
      MessagingException - for failures

    • delete

      public boolean delete(boolean recurse) throws MessagingException
      Delete this folder.
      Specified by:
      delete in class Folder
      Parameters:
      recurse - also delete subfolders?
      Returns:
      true if the Folder is deleted successfully
      Throws:
      FolderNotFoundException - if this folder does not exist
      MessagingException - for other failures
      See Also:

    • renameTo

      public boolean renameTo(Folder f) throws MessagingException
      Rename this folder.
      Specified by:
      renameTo in class Folder
      Parameters:
      f - a folder representing the new name for this Folder
      Returns:
      true if the Folder is renamed successfully
      Throws:
      FolderNotFoundException - if this folder does not exist
      MessagingException - for other failures
      See Also:

    • open

      public void open(int mode) throws MessagingException
      Open this folder in the given mode.
      Specified by:
      open in class Folder
      Parameters:
      mode - open the Folder READ_ONLY or READ_WRITE
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures
      See Also:

    • open

      public List<MailEvent> open(int mode, ResyncData rd) throws MessagingException
      Open this folder in the given mode, with the given resynchronization data.
      Parameters:
      mode - the open mode (Folder.READ_WRITE or Folder.READ_ONLY)
      rd - the ResyncData instance
      Returns:
      a List of MailEvent instances, or null if none
      Throws:
      MessagingException - if the open fails
      Since:
      JavaMail 1.5.1

    • fetch

      public void fetch(Message[] msgs, FetchProfile fp) throws MessagingException
      Prefetch attributes, based on the given FetchProfile.
      Overrides:
      fetch in class Folder
      Parameters:
      msgs - fetch items for these messages
      fp - the FetchProfile
      Throws:
      MessagingException - for other failures

    • getEnvelopeCommand

      protected String getEnvelopeCommand()
      Return the IMAP FETCH items to request in order to load all the "envelope" data. Subclasses can override this method to fetch more data when FetchProfile.Item.ENVELOPE is requested.
      Returns:
      the IMAP FETCH items to request
      Since:
      JavaMail 1.4.6

    • newIMAPMessage

      protected IMAPMessage newIMAPMessage(int msgnum)
      Create a new IMAPMessage object to represent the given message number. Subclasses of IMAPFolder may override this method to create a subclass of IMAPMessage.
      Parameters:
      msgnum - the message sequence number
      Returns:
      the new IMAPMessage object
      Since:
      JavaMail 1.4.6

    • setFlags

      public void setFlags(Message[] msgs, Flags flag, boolean value) throws MessagingException
      Set the specified flags for the given array of messages.
      Overrides:
      setFlags in class Folder
      Parameters:
      msgs - the array of message objects
      flag - Flags object containing the flags to be set
      value - set the flags to this boolean value
      Throws:
      MessagingException - for other failures
      See Also:

    • setFlags

      public void setFlags(int start, int end, Flags flag, boolean value) throws MessagingException
      Set the specified flags for the given range of message numbers.
      Overrides:
      setFlags in class Folder
      Parameters:
      start - the number of the first message
      end - the number of the last message
      flag - Flags object containing the flags to be set
      value - set the flags to this boolean value
      Throws:
      MessagingException - for other failures
      See Also:

    • setFlags

      public void setFlags(int[] msgnums, Flags flag, boolean value) throws MessagingException
      Set the specified flags for the given array of message numbers.
      Overrides:
      setFlags in class Folder
      Parameters:
      msgnums - the array of message numbers
      flag - Flags object containing the flags to be set
      value - set the flags to this boolean value
      Throws:
      MessagingException - for other failures
      See Also:

    • close

      public void close(boolean expunge) throws MessagingException
      Close this folder.
      Specified by:
      close in class Folder
      Parameters:
      expunge - expunges all deleted messages if this flag is true
      Throws:
      MessagingException - for other failures
      See Also:

    • forceClose

      public void forceClose() throws MessagingException
      Close this folder without waiting for the server.
      Throws:
      MessagingException - for failures

    • isOpen

      public boolean isOpen()
      Check whether this connection is really open.
      Specified by:
      isOpen in class Folder
      Returns:
      true if this Folder is in the 'open' state.

    • getPermanentFlags

      public Flags getPermanentFlags()
      Return the permanent flags supported by the server.
      Specified by:
      getPermanentFlags in class Folder
      Returns:
      permanent flags, or null if not known

    • getMessageCount

      public int getMessageCount() throws MessagingException
      Get the total message count.
      Specified by:
      getMessageCount in class Folder
      Returns:
      total number of messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures

    • getNewMessageCount

      public int getNewMessageCount() throws MessagingException
      Get the new message count.
      Overrides:
      getNewMessageCount in class Folder
      Returns:
      number of new messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures

    • getUnreadMessageCount

      public int getUnreadMessageCount() throws MessagingException
      Get the unread message count.
      Overrides:
      getUnreadMessageCount in class Folder
      Returns:
      total number of unread messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures

    • getDeletedMessageCount

      public int getDeletedMessageCount() throws MessagingException
      Get the deleted message count.
      Overrides:
      getDeletedMessageCount in class Folder
      Returns:
      number of deleted messages. -1 may be returned by certain implementations if this method is invoked on a closed folder.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures

    • getMessage

      public Message getMessage(int msgnum) throws MessagingException
      Get the specified message.
      Specified by:
      getMessage in class Folder
      Parameters:
      msgnum - the message number
      Returns:
      the Message object
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures
      See Also:

    • getMessages

      public Message[] getMessages() throws MessagingException
      Get all Message objects from this Folder. Returns an empty array if the folder is empty. Clients can use Message objects (instead of sequence numbers) as references to the messages within a folder; this method supplies the Message objects to the client. Folder implementations are expected to provide light-weight Message objects, which get filled on demand.

      This implementation invokes getMessageCount() to get the current message count and then uses getMessage() to get Message objects from 1 till the message count.

      Overrides:
      getMessages in class Folder
      Returns:
      array of Message objects, empty array if folder is empty.
      Throws:
      FolderNotFoundException - if this folder does not exist.
      MessagingException - for other failures
      See Also:

    • appendMessages

      public void appendMessages(Message[] msgs) throws MessagingException
      Append the given messages into this folder.
      Specified by:
      appendMessages in class Folder
      Parameters:
      msgs - array of Messages to be appended
      Throws:
      MessagingException - if the append failed.
      FolderNotFoundException - if this folder does not exist.

    • appendUIDMessages

      public org.eclipse.angus.mail.imap.AppendUID[] appendUIDMessages(Message[] msgs) throws MessagingException
      Append the given messages into this folder. Return array of AppendUID objects containing UIDs of these messages in the destination folder. Each element of the returned array corresponds to an element of the msgs array. A null element means the server didn't return UID information for the appended message.

      Depends on the APPENDUID response code defined by the UIDPLUS extension - RFC 4315.

      Parameters:
      msgs - the messages to append
      Returns:
      array of AppendUID objects
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.4

    • addMessages

      public Message[] addMessages(Message[] msgs) throws MessagingException
      Append the given messages into this folder. Return array of Message objects representing the messages in the destination folder. Note that the folder must be open. Each element of the returned array corresponds to an element of the msgs array. A null element means the server didn't return UID information for the appended message.

      Depends on the APPENDUID response code defined by the UIDPLUS extension - RFC 4315.

      Parameters:
      msgs - the messages to add
      Returns:
      the messages in this folder
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.4

    • copyMessages

      public void copyMessages(Message[] msgs, Folder folder) throws MessagingException
      Copy the specified messages from this folder, to the specified destination.
      Overrides:
      copyMessages in class Folder
      Parameters:
      msgs - the array of message objects
      folder - the folder to copy the messages to
      Throws:
      FolderNotFoundException - if the destination folder does not exist.
      MessagingException - for other failures
      See Also:

    • copyUIDMessages

      public org.eclipse.angus.mail.imap.AppendUID[] copyUIDMessages(Message[] msgs, Folder folder) throws MessagingException
      Copy the specified messages from this folder, to the specified destination. Return array of AppendUID objects containing UIDs of these messages in the destination folder. Each element of the returned array corresponds to an element of the msgs array. A null element means the server didn't return UID information for the copied message.

      Depends on the COPYUID response code defined by the UIDPLUS extension - RFC 4315.

      Parameters:
      msgs - the messages to copy
      folder - the folder to copy the messages to
      Returns:
      array of AppendUID objects
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.5.1

    • moveMessages

      public void moveMessages(Message[] msgs, Folder folder) throws MessagingException
      Move the specified messages from this folder, to the specified destination. Depends on the MOVE extension (RFC 6851).
      Parameters:
      msgs - the messages to move
      folder - the folder to move the messages to
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.5.4

    • moveUIDMessages

      public org.eclipse.angus.mail.imap.AppendUID[] moveUIDMessages(Message[] msgs, Folder folder) throws MessagingException
      Move the specified messages from this folder, to the specified destination. Return array of AppendUID objects containing UIDs of these messages in the destination folder. Each element of the returned array corresponds to an element of the msgs array. A null element means the server didn't return UID information for the moved message.

      Depends on the MOVE extension (RFC 6851) and the COPYUID response code defined by the UIDPLUS extension (RFC 4315).

      Parameters:
      msgs - the messages to move
      folder - the folder to move the messages to
      Returns:
      array of AppendUID objects
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.5.4

    • expunge

      public Message[] expunge() throws MessagingException
      Expunge all messages marked as DELETED.
      Specified by:
      expunge in class Folder
      Returns:
      array of expunged Message objects
      Throws:
      FolderNotFoundException - if this folder does not exist
      MessagingException - for other failures
      See Also:

    • expunge

      public Message[] expunge(Message[] msgs) throws MessagingException
      Expunge the indicated messages, which must have been marked as DELETED. Depends on the UIDPLUS extension - RFC 4315.
      Parameters:
      msgs - the messages to expunge
      Returns:
      the expunged messages
      Throws:
      MessagingException - for failures

    • search

      public Message[] search(SearchTerm term) throws MessagingException
      Search whole folder for messages matching the given term. If the property mail.imap.throwsearchexception is true, and the search term is too complex for the IMAP protocol, SearchException is thrown. Otherwise, if the search term is too complex, super.search is called to do the search on the client.
      Overrides:
      search in class Folder
      Parameters:
      term - the search term
      Returns:
      the messages that match
      Throws:
      SearchException - if mail.imap.throwsearchexception is true and the search is too complex for the IMAP protocol
      MessagingException - for other failures
      See Also:

    • search

      public Message[] search(SearchTerm term, Message[] msgs) throws MessagingException
      Search the folder for messages matching the given term. Returns array of matching messages. Returns an empty array if no matching messages are found.
      Overrides:
      search in class Folder
      Parameters:
      term - the search criterion
      msgs - the messages to be searched
      Returns:
      array of matching messages
      Throws:
      SearchException - if the search term is too complex for the implementation to handle.
      MessagingException - for other failures
      See Also:

    • getSortedMessages

      public Message[] getSortedMessages(SortTerm[] term) throws MessagingException
      Sort the messages in the folder according to the sort criteria. The messages are returned in the sorted order, but the order of the messages in the folder is not changed.

      Depends on the SORT extension - RFC 5256.

      Parameters:
      term - the SortTerms
      Returns:
      the messages in sorted order
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.4.4

    • getSortedMessages

      public Message[] getSortedMessages(SortTerm[] term, SearchTerm sterm) throws MessagingException
      Sort the messages in the folder according to the sort criteria. The messages are returned in the sorted order, but the order of the messages in the folder is not changed. Only messages matching the search criteria are considered.

      Depends on the SORT extension - RFC 5256.

      Parameters:
      term - the SortTerms
      sterm - the SearchTerm
      Returns:
      the messages in sorted order
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.4.4

    • addMessageCountListener

      public void addMessageCountListener(MessageCountListener l)
      Description copied from class: Folder
      Add a listener for MessageCount events on this Folder.

      The implementation provided here adds this listener to an internal list of MessageCountListeners.

      Overrides:
      addMessageCountListener in class Folder
      Parameters:
      l - the Listener for MessageCount events
      See Also:

    • getUIDValidity

      public long getUIDValidity() throws MessagingException
      Returns the UIDValidity for this folder.
      Specified by:
      getUIDValidity in interface UIDFolder
      Returns:
      UIDValidity
      Throws:
      MessagingException - for failures

    • getUIDNext

      public long getUIDNext() throws MessagingException
      Returns the predicted UID that will be assigned to the next message that is appended to this folder. If the folder is closed, the STATUS command is used to retrieve this value. If the folder is open, the value returned from the SELECT or EXAMINE command is returned. Note that messages may have been appended to the folder while it was open and thus this value may be out of date.

      Servers implementing RFC2060 likely won't return this value when a folder is opened. Servers implementing RFC3501 should return this value when a folder is opened.

      Specified by:
      getUIDNext in interface UIDFolder
      Returns:
      the UIDNEXT value, or -1 if unknown
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.3.3

    • getMessageByUID

      public Message getMessageByUID(long uid) throws MessagingException
      Get the Message corresponding to the given UID. If no such message exists, null is returned.
      Specified by:
      getMessageByUID in interface UIDFolder
      Parameters:
      uid - UID for the desired message
      Returns:
      the Message object. null is returned if no message corresponding to this UID is obtained.
      Throws:
      MessagingException - for failures

    • getMessagesByUID

      public Message[] getMessagesByUID(long start, long end) throws MessagingException
      Get the Messages specified by the given range.

      Returns Message objects for all valid messages in this range. Returns an empty array if no messages are found.

      Specified by:
      getMessagesByUID in interface UIDFolder
      Parameters:
      start - start UID
      end - end UID
      Returns:
      array of Message objects
      Throws:
      MessagingException - for failures
      See Also:

    • getMessagesByUID

      public Message[] getMessagesByUID(long[] uids) throws MessagingException
      Get the Messages specified by the given array.

      uids.length() elements are returned. If any UID in the array is invalid, a null entry is returned for that element.

      Specified by:
      getMessagesByUID in interface UIDFolder
      Parameters:
      uids - array of UIDs
      Returns:
      array of Message objects
      Throws:
      MessagingException - for failures

    • getUID

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

    • getUIDNotSticky

      public boolean getUIDNotSticky() throws MessagingException
      Servers that support the UIDPLUS extension (RFC 4315) may indicate that this folder does not support persistent UIDs; that is, UIDVALIDITY will be different each time the folder is opened. Only valid when the folder is open.
      Returns:
      true if UIDs are not sticky
      Throws:
      MessagingException - for failures
      IllegalStateException - if the folder isn't open
      Since:
      JavaMail 1.6.0
      See Also:
      • "RFC 4315"

    • getHighestModSeq

      public long getHighestModSeq() throws MessagingException
      Returns the HIGHESTMODSEQ for this folder.
      Returns:
      the HIGHESTMODSEQ value
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.5.1
      See Also:
      • "RFC 4551"

    • getMessagesByUIDChangedSince

      public Message[] getMessagesByUIDChangedSince(long start, long end, long modseq) throws MessagingException
      Get the messages that have been changed since the given MODSEQ value. Also, prefetch the flags for the messages.

      The server must support the CONDSTORE extension.

      Parameters:
      start - the first message number
      end - the last message number
      modseq - the MODSEQ value
      Returns:
      the changed messages
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.5.1
      See Also:
      • "RFC 4551"

    • getQuota

      public Quota[] getQuota() throws MessagingException
      Get the quotas for the quotaroot associated with this folder. Note that many folders may have the same quotaroot. Quotas are controlled on the basis of a quotaroot, not (necessarily) a folder. The relationship between folders and quotaroots depends on the IMAP server. Some servers might implement a single quotaroot for all folders owned by a user. Other servers might implement a separate quotaroot for each folder. A single folder can even have multiple quotaroots, perhaps controlling quotas for different resources.
      Returns:
      array of Quota objects for the quotaroots associated with this folder
      Throws:
      MessagingException - if the server doesn't support the QUOTA extension

    • setQuota

      public void setQuota(Quota quota) throws MessagingException
      Set the quotas for the quotaroot specified in the quota argument. Typically this will be one of the quotaroots associated with this folder, as obtained from the getQuota method, but it need not be.
      Parameters:
      quota - the quota to set
      Throws:
      MessagingException - if the server doesn't support the QUOTA extension

    • getACL

      public ACL[] getACL() throws MessagingException
      Get the access control list entries for this folder.
      Returns:
      array of access control list entries
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • addACL

      public void addACL(ACL acl) throws MessagingException
      Add an access control list entry to the access control list for this folder.
      Parameters:
      acl - the access control list entry to add
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • removeACL

      public void removeACL(String name) throws MessagingException
      Remove any access control list entry for the given identifier from the access control list for this folder.
      Parameters:
      name - the identifier for which to remove all ACL entries
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • addRights

      public void addRights(ACL acl) throws MessagingException
      Add the rights specified in the ACL to the entry for the identifier specified in the ACL. If an entry for the identifier doesn't already exist, add one.
      Parameters:
      acl - the identifer and rights to add
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • removeRights

      public void removeRights(ACL acl) throws MessagingException
      Remove the rights specified in the ACL from the entry for the identifier specified in the ACL.
      Parameters:
      acl - the identifer and rights to remove
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • listRights

      public Rights[] listRights(String name) throws MessagingException
      Get all the rights that may be allowed to the given identifier. Rights are grouped per RFC 2086 and each group is returned as an element of the array. The first element of the array is the set of rights that are always granted to the identifier. Later elements are rights that may be optionally granted to the identifier.

      Note that this method lists the rights that it is possible to assign to the given identifier, not the rights that are actually granted to the given identifier. For the latter, see the getACL method.

      Parameters:
      name - the identifier to list rights for
      Returns:
      array of Rights objects representing possible rights for the identifier
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • myRights

      public Rights myRights() throws MessagingException
      Get the rights allowed to the currently authenticated user.
      Returns:
      the rights granted to the current user
      Throws:
      MessagingException - if the server doesn't support the ACL extension

    • getAttributes

      public String[] getAttributes() throws MessagingException
      Get the attributes that the IMAP server returns with the LIST response.
      Returns:
      array of attributes for this folder
      Throws:
      MessagingException - for failures
      Since:
      JavaMail 1.3.3

    • idle

      public void idle() throws MessagingException
      Use the IMAP IDLE command (see RFC 2177), if supported by the server, to enter idle mode so that the server can send unsolicited notifications of new messages arriving, etc. without the need for the client to constantly poll the server. Use an appropriate listener to be notified of new messages or other events. When another thread (e.g., the listener thread) needs to issue an IMAP comand for this folder, the idle mode will be terminated and this method will return. Typically the caller will invoke this method in a loop.

      The mail.imap.minidletime property enforces a minimum delay before returning from this method, to ensure that other threads have a chance to issue commands before the caller invokes this method again. The default delay is 10 milliseconds.

      Throws:
      MessagingException - if the server doesn't support the IDLE extension
      IllegalStateException - if the folder isn't open
      Since:
      JavaMail 1.4.1

    • idle

      public void idle(boolean once) throws MessagingException
      Like idle(), but if once is true, abort the IDLE command after the first notification, to allow the caller to process any notification synchronously.
      Parameters:
      once - only do one notification?
      Throws:
      MessagingException - if the server doesn't support the IDLE extension
      IllegalStateException - if the folder isn't open
      Since:
      JavaMail 1.4.3

    • id

      public Map<String,String> id(Map<String,String> clientParams) throws MessagingException
      Send the IMAP ID command (if supported by the server) and return the result from the server. The ID command identfies the client to the server and returns information about the server to the client. See RFC 2971. The returned Map is unmodifiable.
      Parameters:
      clientParams - a Map of keys and values identifying the client
      Returns:
      a Map of keys and values identifying the server
      Throws:
      MessagingException - if the server doesn't support the ID extension
      Since:
      JavaMail 1.5.1

    • getStatusItem

      public long getStatusItem(String item) throws MessagingException
      Use the IMAP STATUS command to get the indicated item. The STATUS item may be a standard item such as "RECENT" or "UNSEEN", or may be a server-specific item. The folder must be closed. If the item is not found, or the folder is open, -1 is returned.
      Parameters:
      item - the STATUS item to fetch
      Returns:
      the value of the STATUS item, or -1
      Throws:
      MessagingException - for errors
      Since:
      JavaMail 1.5.2

    • handleResponse

      public void handleResponse(org.eclipse.angus.mail.iap.Response r)
      The response handler. This is the callback routine that is invoked by the protocol layer.
      Specified by:
      handleResponse in interface org.eclipse.angus.mail.iap.ResponseHandler

    • getStoreProtocol

      protected org.eclipse.angus.mail.imap.protocol.IMAPProtocol getStoreProtocol() throws org.eclipse.angus.mail.iap.ProtocolException
      Get this folder's Store's protocol connection. When acquiring a store protocol object, it is important to use the following steps: 
           IMAPProtocol p = null;
     try {
         p = getStoreProtocol();
         // perform the command
     } catch (WhateverException ex) {
         // handle it
     } finally {
         releaseStoreProtocol(p);
     }
      ASSERT: Must be called with this folder's synchronization lock held.
      Returns:
      the IMAPProtocol for the Store's connection
      Throws:
      org.eclipse.angus.mail.iap.ProtocolException - for protocol errors

    • throwClosedException

      protected void throwClosedException(org.eclipse.angus.mail.iap.ConnectionException cex) throws FolderClosedException, StoreClosedException
      Throw the appropriate 'closed' exception.
      Parameters:
      cex - the ConnectionException
      Throws:
      FolderClosedException - if the folder is closed
      StoreClosedException - if the store is closed

    • getProtocol

      protected org.eclipse.angus.mail.imap.protocol.IMAPProtocol getProtocol() throws org.eclipse.angus.mail.iap.ProtocolException
      Return the IMAPProtocol object for this folder.

      This method will block if necessary to wait for an IDLE command to finish.

      Returns:
      the IMAPProtocol object used when the folder is open
      Throws:
      org.eclipse.angus.mail.iap.ProtocolException - for protocol errors

    • doCommand

      public Object doCommand(IMAPFolder.ProtocolCommand cmd) throws MessagingException
      Execute a user-supplied IMAP command. The command is executed in the appropriate context with the necessary locks held and using the appropriate IMAPProtocol object.

      This method returns whatever the ProtocolCommand object's doCommand method returns. If the doCommand method throws a ConnectionException it is translated into a StoreClosedException or FolderClosedException as appropriate. If the doCommand method throws a ProtocolException it is translated into a MessagingException.

      The following example shows how to execute the IMAP NOOP command. Executing more complex IMAP commands requires intimate knowledge of the org.eclipse.angus.mail.iap and org.eclipse.angus.mail.imap.protocol packages, best acquired by reading the source code. 

       import org.eclipse.angus.mail.iap.*;
 import org.eclipse.angus.mail.imap.*;
 import org.eclipse.angus.mail.imap.protocol.*;

 ...

 IMAPFolder f = (IMAPFolder)folder;
 Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
        public Object doCommand(IMAPProtocol p)
                        throws ProtocolException {
            p.simpleCommand("NOOP", null);
            return null;
    }
 });

      Here's a more complex example showing how to use the proposed IMAP SORT extension: 

       import org.eclipse.angus.mail.iap.*;
 import org.eclipse.angus.mail.imap.*;
 import org.eclipse.angus.mail.imap.protocol.*;

 ...

 IMAPFolder f = (IMAPFolder)folder;
 Object val = f.doCommand(new IMAPFolder.ProtocolCommand() {
        public Object doCommand(IMAPProtocol p)
                        throws ProtocolException {
            // Issue command
            Argument args = new Argument();
            Argument list = new Argument();
            list.writeString("SUBJECT");
            args.writeArgument(list);
            args.writeString("UTF-8");
            args.writeString("ALL");
            Response[] r = p.command("SORT", args);
            Response response = r[r.length-1];

            // Grab response
            Vector v = new Vector();
            if (response.isOK()) { // command succesful
                for (int i = 0, len = r.length; i < len; i++) {
                    if (!(r[i] instanceof IMAPResponse))
                        continue;

                    IMAPResponse ir = (IMAPResponse)r[i];
                    if (ir.keyEquals("SORT")) {
                        String num;
                        while ((num = ir.readAtomString()) != null)
                            System.out.println(num);
                        r[i] = null;
            }
        }
        }

            // dispatch remaining untagged responses
            p.notifyResponseHandlers(r);
            p.handleResult(response);

            return null;
    }
 });
      Parameters:
      cmd - the protocol command
      Returns:
      the result of the command
      Throws:
      MessagingException - for failures

    • doOptionalCommand

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

    • doCommandIgnoreFailure

      public Object doCommandIgnoreFailure(IMAPFolder.ProtocolCommand cmd) throws MessagingException
      Throws:
      MessagingException

    • doProtocolCommand

      protected Object doProtocolCommand(IMAPFolder.ProtocolCommand cmd) throws org.eclipse.angus.mail.iap.ProtocolException
      Throws:
      org.eclipse.angus.mail.iap.ProtocolException

    • releaseStoreProtocol

      protected void releaseStoreProtocol(org.eclipse.angus.mail.imap.protocol.IMAPProtocol p)
      Release the store protocol object. If we borrowed a protocol object from the connection pool, give it back. If we used our own protocol object, nothing to do. ASSERT: Must be called with this folder's synchronization lock held.
      Parameters:
      p - the IMAPProtocol object

    • releaseProtocol

      protected void releaseProtocol(boolean returnToPool)
      Release the protocol object. ASSERT: This method must be called only when holding the messageCacheLock
      Parameters:
      returnToPool - return the protocol object to the pool?

    • keepConnectionAlive

      protected void keepConnectionAlive(boolean keepStoreAlive) throws org.eclipse.angus.mail.iap.ProtocolException
      Issue a noop command for the connection if the connection has not been used in more than a second. If keepStoreAlive is true, also issue a noop over the store's connection. ASSERT: This method must be called only when holding the messageCacheLock
      Parameters:
      keepStoreAlive - keep the Store alive too?
      Throws:
      org.eclipse.angus.mail.iap.ProtocolException - for protocol errors

    • getMessageBySeqNumber

      protected IMAPMessage getMessageBySeqNumber(int seqnum)
      Get the message object for the given sequence number. If none found, null is returned. ASSERT: This method must be called only when holding the messageCacheLock
      Parameters:
      seqnum - the message sequence number
      Returns:
      the IMAPMessage object

    • getMessagesBySeqNumbers

      protected IMAPMessage[] getMessagesBySeqNumbers(int[] seqnums)
      Get the message objects for the given sequence numbers. ASSERT: This method must be called only when holding the messageCacheLock
      Parameters:
      seqnums - the array of message sequence numbers
      Returns:
      the IMAPMessage objects
      Since:
      JavaMail 1.5.3