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

Class IMAPFolder

  • All Implemented Interfaces:
    jakarta.mail.UIDFolder, java.lang.AutoCloseable, ResponseHandler
    Direct Known Subclasses:
    DefaultFolder
    public class IMAPFolder
extends jakarta.mail.Folder
implements jakarta.mail.UIDFolder, 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.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected IMAPFolder​(java.lang.String fullName, char separator, IMAPStore store, java.lang.Boolean isNamespace)
      Constructor used to create a possibly non-existent folder.
      protected IMAPFolder​(ListInfo li, IMAPStore store)
      Constructor used to create an existing folder.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addACL​(ACL acl)
      Add an access control list entry to the access control list for this folder.
      void addMessageCountListener​(jakarta.mail.event.MessageCountListener l)  
      jakarta.mail.Message[] addMessages​(jakarta.mail.Message[] msgs)
      Append the given messages into this folder.
      void addRights​(ACL acl)
      Add the rights specified in the ACL to the entry for the identifier specified in the ACL.
      void appendMessages​(jakarta.mail.Message[] msgs)
      Append the given messages into this folder.
      AppendUID[] appendUIDMessages​(jakarta.mail.Message[] msgs)
      Append the given messages into this folder.
      protected void checkClosed()  
      protected void checkExists()  
      protected void checkOpened()  
      protected void checkRange​(int msgno)  
      void close​(boolean expunge)
      Close this folder.
      void copyMessages​(jakarta.mail.Message[] msgs, jakarta.mail.Folder folder)
      Copy the specified messages from this folder, to the specified destination.
      AppendUID[] copyUIDMessages​(jakarta.mail.Message[] msgs, jakarta.mail.Folder folder)
      Copy the specified messages from this folder, to the specified destination.
      boolean create​(int type)
      Create this folder, with the specified type.
      boolean delete​(boolean recurse)
      Delete this folder.
      java.lang.Object doCommand​(IMAPFolder.ProtocolCommand cmd)
      Execute a user-supplied IMAP command.
      java.lang.Object doCommandIgnoreFailure​(IMAPFolder.ProtocolCommand cmd)  
      java.lang.Object doOptionalCommand​(java.lang.String err, IMAPFolder.ProtocolCommand cmd)  
      protected java.lang.Object doProtocolCommand​(IMAPFolder.ProtocolCommand cmd)  
      boolean exists()
      Check whether this folder really exists on the server.
      jakarta.mail.Message[] expunge()
      Expunge all messages marked as DELETED.
      jakarta.mail.Message[] expunge​(jakarta.mail.Message[] msgs)
      Expunge the indicated messages, which must have been marked as DELETED.
      void fetch​(jakarta.mail.Message[] msgs, jakarta.mail.FetchProfile fp)
      Prefetch attributes, based on the given FetchProfile.
      void forceClose()
      Close this folder without waiting for the server.
      ACL[] getACL()
      Get the access control list entries for this folder.
      java.lang.String[] getAttributes()
      Get the attributes that the IMAP server returns with the LIST response.
      int getDeletedMessageCount()
      Get the deleted message count.
      protected java.lang.String getEnvelopeCommand()
      Return the IMAP FETCH items to request in order to load all the "envelope" data.
      jakarta.mail.Folder getFolder​(java.lang.String name)
      Get the named subfolder.
      java.lang.String getFullName()
      Get the fullname of this folder.
      long getHighestModSeq()
      Returns the HIGHESTMODSEQ for this folder.
      jakarta.mail.Message getMessage​(int msgnum)
      Get the specified message.
      protected IMAPMessage getMessageBySeqNumber​(int seqnum)
      Get the message object for the given sequence number.
      jakarta.mail.Message getMessageByUID​(long uid)
      Get the Message corresponding to the given UID.
      int getMessageCount()
      Get the total message count.
      jakarta.mail.Message[] getMessages()
      protected IMAPMessage[] getMessagesBySeqNumbers​(int[] seqnums)
      Get the message objects for the given sequence numbers.
      jakarta.mail.Message[] getMessagesByUID​(long[] uids)
      Get the Messages specified by the given array.
      jakarta.mail.Message[] getMessagesByUID​(long start, long end)
      Get the Messages specified by the given range.
      jakarta.mail.Message[] getMessagesByUIDChangedSince​(long start, long end, long modseq)
      Get the messages that have been changed since the given MODSEQ value.
      java.lang.String getName()
      Get the name of this folder.
      int getNewMessageCount()
      Get the new message count.
      jakarta.mail.Folder getParent()
      Get this folder's parent.
      jakarta.mail.Flags getPermanentFlags()
      Return the permanent flags supported by the server.
      protected IMAPProtocol getProtocol()
      Return the IMAPProtocol object for this folder.
      jakarta.mail.Quota[] getQuota()
      Get the quotas for the quotaroot associated with this folder.
      char getSeparator()
      Get the separator character.
      jakarta.mail.Message[] getSortedMessages​(SortTerm[] term)
      Sort the messages in the folder according to the sort criteria.
      jakarta.mail.Message[] getSortedMessages​(SortTerm[] term, jakarta.mail.search.SearchTerm sterm)
      Sort the messages in the folder according to the sort criteria.
      long getStatusItem​(java.lang.String item)
      Use the IMAP STATUS command to get the indicated item.
      protected IMAPProtocol getStoreProtocol()
      Get this folder's Store's protocol connection.
      int getType()
      Get the type of this folder.
      long getUID​(jakarta.mail.Message message)
      Get the UID for the specified message.
      long getUIDNext()
      Returns the predicted UID that will be assigned to the next message that is appended to this folder.
      boolean getUIDNotSticky()
      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.
      long getUIDValidity()
      Returns the UIDValidity for this folder.
      int getUnreadMessageCount()
      Get the unread message count.
      void handleResponse​(Response r)
      The response handler.
      boolean hasNewMessages()
      Check whether this folder has new messages.
      java.util.Map<java.lang.String,​java.lang.String> id​(java.util.Map<java.lang.String,​java.lang.String> clientParams)
      Send the IMAP ID command (if supported by the server) and return the result from the server.
      void idle()
      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.
      void idle​(boolean once)
      Like idle(), but if once is true, abort the IDLE command after the first notification, to allow the caller to process any notification synchronously.
      boolean isOpen()
      Check whether this connection is really open.
      boolean isSubscribed()
      Check whether this folder is subscribed.
      protected void keepConnectionAlive​(boolean keepStoreAlive)
      Issue a noop command for the connection if the connection has not been used in more than a second.
      jakarta.mail.Folder[] list​(java.lang.String pattern)
      List all subfolders matching the specified pattern.
      Rights[] listRights​(java.lang.String name)
      Get all the rights that may be allowed to the given identifier.
      jakarta.mail.Folder[] listSubscribed​(java.lang.String pattern)
      List all subscribed subfolders matching the specified pattern.
      void moveMessages​(jakarta.mail.Message[] msgs, jakarta.mail.Folder folder)
      Move the specified messages from this folder, to the specified destination.
      AppendUID[] moveUIDMessages​(jakarta.mail.Message[] msgs, jakarta.mail.Folder folder)
      Move the specified messages from this folder, to the specified destination.
      Rights myRights()
      Get the rights allowed to the currently authenticated user.
      protected IMAPMessage newIMAPMessage​(int msgnum)
      Create a new IMAPMessage object to represent the given message number.
      void open​(int mode)
      Open this folder in the given mode.
      java.util.List<jakarta.mail.event.MailEvent> open​(int mode, ResyncData rd)
      Open this folder in the given mode, with the given resynchronization data.
      protected void releaseProtocol​(boolean returnToPool)
      Release the protocol object.
      protected void releaseStoreProtocol​(IMAPProtocol p)
      Release the store protocol object.
      void removeACL​(java.lang.String name)
      Remove any access control list entry for the given identifier from the access control list for this folder.
      void removeRights​(ACL acl)
      Remove the rights specified in the ACL from the entry for the identifier specified in the ACL.
      boolean renameTo​(jakarta.mail.Folder f)
      Rename this folder.
      jakarta.mail.Message[] search​(jakarta.mail.search.SearchTerm term)
      Search whole folder for messages matching the given term.
      jakarta.mail.Message[] search​(jakarta.mail.search.SearchTerm term, jakarta.mail.Message[] msgs)
      Search the folder for messages matching the given term.
      void setFlags​(int[] msgnums, jakarta.mail.Flags flag, boolean value)
      Set the specified flags for the given array of message numbers.
      void setFlags​(int start, int end, jakarta.mail.Flags flag, boolean value)
      Set the specified flags for the given range of message numbers.
      void setFlags​(jakarta.mail.Message[] msgs, jakarta.mail.Flags flag, boolean value)
      Set the specified flags for the given array of messages.
      void setQuota​(jakarta.mail.Quota quota)
      Set the quotas for the quotaroot specified in the quota argument.
      void setSubscribed​(boolean subscribe)
      Subscribe/Unsubscribe this folder.
      protected void throwClosedException​(ConnectionException cex)
      Throw the appropriate 'closed' exception.

      • Methods inherited from class jakarta.mail.Folder

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

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • fullName

        protected volatile java.lang.String fullName

      • name

        protected java.lang.String name

      • type

        protected int type

      • separator

        protected char separator

      • availableFlags

        protected jakarta.mail.Flags availableFlags

      • permanentFlags

        protected jakarta.mail.Flags permanentFlags

      • exists

        protected volatile boolean exists

      • isNamespace

        protected boolean isNamespace

      • attributes

        protected volatile java.lang.String[] attributes

      • messageCacheLock

        protected final java.lang.Object messageCacheLock

      • uidTable

        protected java.util.Hashtable<java.lang.Long,​IMAPMessage> uidTable

    • Constructor Detail

      • IMAPFolder

        protected IMAPFolder​(java.lang.String fullName,
                     char separator,
                     IMAPStore store,
                     java.lang.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​(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 Detail

      • checkExists

        protected void checkExists()
                    throws jakarta.mail.MessagingException
        Throws:
        jakarta.mail.MessagingException

      • checkClosed

        protected void checkClosed()

      • checkOpened

        protected void checkOpened()
                    throws jakarta.mail.FolderClosedException
        Throws:
        jakarta.mail.FolderClosedException

      • checkRange

        protected void checkRange​(int msgno)
                   throws jakarta.mail.MessagingException
        Throws:
        jakarta.mail.MessagingException

      • getName

        public java.lang.String getName()
        Get the name of this folder.
        Specified by:
        getName in class jakarta.mail.Folder

      • getFullName

        public java.lang.String getFullName()
        Get the fullname of this folder.
        Specified by:
        getFullName in class jakarta.mail.Folder

      • getParent

        public jakarta.mail.Folder getParent()
                              throws jakarta.mail.MessagingException
        Get this folder's parent.
        Specified by:
        getParent in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • exists

        public boolean exists()
               throws jakarta.mail.MessagingException
        Check whether this folder really exists on the server.
        Specified by:
        exists in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • list

        public jakarta.mail.Folder[] list​(java.lang.String pattern)
                           throws jakarta.mail.MessagingException
        List all subfolders matching the specified pattern.
        Specified by:
        list in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • listSubscribed

        public jakarta.mail.Folder[] listSubscribed​(java.lang.String pattern)
                                     throws jakarta.mail.MessagingException
        List all subscribed subfolders matching the specified pattern.
        Overrides:
        listSubscribed in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getSeparator

        public char getSeparator()
                  throws jakarta.mail.MessagingException
        Get the separator character.
        Specified by:
        getSeparator in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getType

        public int getType()
            throws jakarta.mail.MessagingException
        Get the type of this folder.
        Specified by:
        getType in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • isSubscribed

        public boolean isSubscribed()
        Check whether this folder is subscribed.
        Overrides:
        isSubscribed in class jakarta.mail.Folder

      • setSubscribed

        public void setSubscribed​(boolean subscribe)
                   throws jakarta.mail.MessagingException
        Subscribe/Unsubscribe this folder.
        Overrides:
        setSubscribed in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • create

        public boolean create​(int type)
               throws jakarta.mail.MessagingException
        Create this folder, with the specified type.
        Specified by:
        create in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • hasNewMessages

        public boolean hasNewMessages()
                       throws jakarta.mail.MessagingException
        Check whether this folder has new messages.
        Specified by:
        hasNewMessages in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getFolder

        public jakarta.mail.Folder getFolder​(java.lang.String name)
                              throws jakarta.mail.MessagingException
        Get the named subfolder.
        Specified by:
        getFolder in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • delete

        public boolean delete​(boolean recurse)
               throws jakarta.mail.MessagingException
        Delete this folder.
        Specified by:
        delete in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • renameTo

        public boolean renameTo​(jakarta.mail.Folder f)
                 throws jakarta.mail.MessagingException
        Rename this folder.
        Specified by:
        renameTo in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • open

        public void open​(int mode)
          throws jakarta.mail.MessagingException
        Open this folder in the given mode.
        Specified by:
        open in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • open

        public java.util.List<jakarta.mail.event.MailEvent> open​(int mode,
                                                         ResyncData rd)
                                                  throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the open fails
        Since:
        JavaMail 1.5.1

      • fetch

        public void fetch​(jakarta.mail.Message[] msgs,
                  jakarta.mail.FetchProfile fp)
           throws jakarta.mail.MessagingException
        Prefetch attributes, based on the given FetchProfile.
        Overrides:
        fetch in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getEnvelopeCommand

        protected java.lang.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​(jakarta.mail.Message[] msgs,
                     jakarta.mail.Flags flag,
                     boolean value)
              throws jakarta.mail.MessagingException
        Set the specified flags for the given array of messages.
        Overrides:
        setFlags in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • setFlags

        public void setFlags​(int start,
                     int end,
                     jakarta.mail.Flags flag,
                     boolean value)
              throws jakarta.mail.MessagingException
        Set the specified flags for the given range of message numbers.
        Overrides:
        setFlags in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • setFlags

        public void setFlags​(int[] msgnums,
                     jakarta.mail.Flags flag,
                     boolean value)
              throws jakarta.mail.MessagingException
        Set the specified flags for the given array of message numbers.
        Overrides:
        setFlags in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • close

        public void close​(boolean expunge)
           throws jakarta.mail.MessagingException
        Close this folder.
        Specified by:
        close in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • forceClose

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

      • isOpen

        public boolean isOpen()
        Check whether this connection is really open.
        Specified by:
        isOpen in class jakarta.mail.Folder

      • getPermanentFlags

        public jakarta.mail.Flags getPermanentFlags()
        Return the permanent flags supported by the server.
        Specified by:
        getPermanentFlags in class jakarta.mail.Folder

      • getMessageCount

        public int getMessageCount()
                    throws jakarta.mail.MessagingException
        Get the total message count.
        Specified by:
        getMessageCount in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getNewMessageCount

        public int getNewMessageCount()
                       throws jakarta.mail.MessagingException
        Get the new message count.
        Overrides:
        getNewMessageCount in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getUnreadMessageCount

        public int getUnreadMessageCount()
                          throws jakarta.mail.MessagingException
        Get the unread message count.
        Overrides:
        getUnreadMessageCount in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getDeletedMessageCount

        public int getDeletedMessageCount()
                           throws jakarta.mail.MessagingException
        Get the deleted message count.
        Overrides:
        getDeletedMessageCount in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getMessage

        public jakarta.mail.Message getMessage​(int msgnum)
                                throws jakarta.mail.MessagingException
        Get the specified message.
        Specified by:
        getMessage in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getMessages

        public jakarta.mail.Message[] getMessages()
                                   throws jakarta.mail.MessagingException
        Overrides:
        getMessages in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • appendMessages

        public void appendMessages​(jakarta.mail.Message[] msgs)
                    throws jakarta.mail.MessagingException
        Append the given messages into this folder.
        Specified by:
        appendMessages in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • appendUIDMessages

        public AppendUID[] appendUIDMessages​(jakarta.mail.Message[] msgs)
                              throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.4

      • addMessages

        public jakarta.mail.Message[] addMessages​(jakarta.mail.Message[] msgs)
                                   throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.4

      • copyMessages

        public void copyMessages​(jakarta.mail.Message[] msgs,
                         jakarta.mail.Folder folder)
                  throws jakarta.mail.MessagingException
        Copy the specified messages from this folder, to the specified destination.
        Overrides:
        copyMessages in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • copyUIDMessages

        public AppendUID[] copyUIDMessages​(jakarta.mail.Message[] msgs,
                                   jakarta.mail.Folder folder)
                            throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.5.1

      • moveMessages

        public void moveMessages​(jakarta.mail.Message[] msgs,
                         jakarta.mail.Folder folder)
                  throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.5.4

      • moveUIDMessages

        public AppendUID[] moveUIDMessages​(jakarta.mail.Message[] msgs,
                                   jakarta.mail.Folder folder)
                            throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.5.4

      • expunge

        public jakarta.mail.Message[] expunge()
                               throws jakarta.mail.MessagingException
        Expunge all messages marked as DELETED.
        Specified by:
        expunge in class jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • expunge

        public jakarta.mail.Message[] expunge​(jakarta.mail.Message[] msgs)
                               throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures

      • search

        public jakarta.mail.Message[] search​(jakarta.mail.search.SearchTerm term)
                              throws jakarta.mail.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 jakarta.mail.Folder
        Parameters:
        term - the search term
        Returns:
        the messages that match
        Throws:
        jakarta.mail.search.SearchException - if mail.imap.throwsearchexception is true and the search is too complex for the IMAP protocol
        jakarta.mail.MessagingException - for other failures

      • search

        public jakarta.mail.Message[] search​(jakarta.mail.search.SearchTerm term,
                                     jakarta.mail.Message[] msgs)
                              throws jakarta.mail.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 jakarta.mail.Folder
        Throws:
        jakarta.mail.MessagingException

      • getSortedMessages

        public jakarta.mail.Message[] getSortedMessages​(SortTerm[] term)
                                         throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.4.4

      • getSortedMessages

        public jakarta.mail.Message[] getSortedMessages​(SortTerm[] term,
                                                jakarta.mail.search.SearchTerm sterm)
                                         throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.4.4

      • addMessageCountListener

        public void addMessageCountListener​(jakarta.mail.event.MessageCountListener l)
        Overrides:
        addMessageCountListener in class jakarta.mail.Folder

      • getUIDValidity

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

      • getUIDNext

        public long getUIDNext()
                throws jakarta.mail.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 jakarta.mail.UIDFolder
        Returns:
        the UIDNEXT value, or -1 if unknown
        Throws:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.3.3

      • getMessageByUID

        public jakarta.mail.Message getMessageByUID​(long uid)
                                     throws jakarta.mail.MessagingException
        Get the Message corresponding to the given UID. If no such message exists, null is returned.
        Specified by:
        getMessageByUID in interface jakarta.mail.UIDFolder
        Throws:
        jakarta.mail.MessagingException

      • getMessagesByUID

        public jakarta.mail.Message[] getMessagesByUID​(long start,
                                               long end)
                                        throws jakarta.mail.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 jakarta.mail.UIDFolder
        Throws:
        jakarta.mail.MessagingException

      • getMessagesByUID

        public jakarta.mail.Message[] getMessagesByUID​(long[] uids)
                                        throws jakarta.mail.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 jakarta.mail.UIDFolder
        Throws:
        jakarta.mail.MessagingException

      • getUID

        public long getUID​(jakarta.mail.Message message)
            throws jakarta.mail.MessagingException
        Get the UID for the specified message.
        Specified by:
        getUID in interface jakarta.mail.UIDFolder
        Throws:
        jakarta.mail.MessagingException

      • getUIDNotSticky

        public boolean getUIDNotSticky()
                        throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        java.lang.IllegalStateException - if the folder isn't open
        Since:
        JavaMail 1.6.0
        See Also:
        "RFC 4315"

      • getHighestModSeq

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

      • getMessagesByUIDChangedSince

        public jakarta.mail.Message[] getMessagesByUIDChangedSince​(long start,
                                                           long end,
                                                           long modseq)
                                                    throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures
        Since:
        JavaMail 1.5.1
        See Also:
        "RFC 4551"

      • getQuota

        public jakarta.mail.Quota[] getQuota()
                              throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the QUOTA extension

      • setQuota

        public void setQuota​(jakarta.mail.Quota quota)
              throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the QUOTA extension

      • getACL

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

      • addACL

        public void addACL​(ACL acl)
            throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the ACL extension

      • removeACL

        public void removeACL​(java.lang.String name)
               throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the ACL extension

      • addRights

        public void addRights​(ACL acl)
               throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the ACL extension

      • removeRights

        public void removeRights​(ACL acl)
                  throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the ACL extension

      • listRights

        public Rights[] listRights​(java.lang.String name)
                    throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the ACL extension

      • myRights

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

      • getAttributes

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

      • idle

        public void idle()
          throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the IDLE extension
        java.lang.IllegalStateException - if the folder isn't open
        Since:
        JavaMail 1.4.1

      • idle

        public void idle​(boolean once)
          throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the IDLE extension
        java.lang.IllegalStateException - if the folder isn't open
        Since:
        JavaMail 1.4.3

      • id

        public java.util.Map<java.lang.String,​java.lang.String> id​(java.util.Map<java.lang.String,​java.lang.String> clientParams)
                                                          throws jakarta.mail.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:
        jakarta.mail.MessagingException - if the server doesn't support the ID extension
        Since:
        JavaMail 1.5.1

      • getStatusItem

        public long getStatusItem​(java.lang.String item)
                   throws jakarta.mail.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:
        jakarta.mail.MessagingException - for errors
        Since:
        JavaMail 1.5.2

      • handleResponse

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

      • getStoreProtocol

        protected IMAPProtocol getStoreProtocol()
                                 throws 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:
        ProtocolException - for protocol errors

      • throwClosedException

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

      • getProtocol

        protected IMAPProtocol getProtocol()
                            throws 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:
        ProtocolException - for protocol errors

      • doCommand

        public java.lang.Object doCommand​(IMAPFolder.ProtocolCommand cmd)
                           throws jakarta.mail.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:
        jakarta.mail.MessagingException - for failures

      • doOptionalCommand

        public java.lang.Object doOptionalCommand​(java.lang.String err,
                                          IMAPFolder.ProtocolCommand cmd)
                                   throws jakarta.mail.MessagingException
        Throws:
        jakarta.mail.MessagingException

      • doCommandIgnoreFailure

        public java.lang.Object doCommandIgnoreFailure​(IMAPFolder.ProtocolCommand cmd)
                                        throws jakarta.mail.MessagingException
        Throws:
        jakarta.mail.MessagingException

      • releaseStoreProtocol

        protected void releaseStoreProtocol​(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 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:
        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