com.sun.mail.imap.protocol

## Class IMAPProtocol

- java.lang.Object
- - com.sun.mail.iap.Protocol
  - - com.sun.mail.imap.protocol.IMAPProtocol

- Direct Known Subclasses:
    GmailProtocol

      public class IMAPProtocol
      extends Protocol

  This class extends the iap.Protocol object and implements IMAP semantics. In general, there is a method corresponding to each IMAP protocol command. The typical implementation issues the appropriate protocol command, collects all responses, processes those responses that are specific to this command and then dispatches the rest (the unsolicited ones) to the dispatcher using the `notifyResponseHandlers(r)`.
  Author:
    John Mani, Bill Shannon

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Set<String>` | `enabled`
    `protected String[]` | `searchCharsets`
    `protected SearchSequence` | `searchSequence`

    - ### Fields inherited from class com.sun.mail.iap.Protocol

      `host, logger, prefix, props, quote, traceLogger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IMAPProtocol(InputStream in, PrintStream out, Properties props, boolean debug)` Constructor for debugging.
    `IMAPProtocol(String name, String host, int port, Properties props, boolean isSSL, MailLogger logger)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(String mbox, Flags f, Date d, Literal data)` APPEND Command.
    `AppendUID` | `appenduid(String mbox, Flags f, Date d, Literal data)` APPEND Command, return uid from APPENDUID response code.
    `AppendUID` | `appenduid(String mbox, Flags f, Date d, Literal data, boolean uid)`
    `void` | `authlogin(String u, String p)` The AUTHENTICATE command with AUTH=LOGIN authenticate scheme
    `void` | `authntlm(String authzid, String u, String p)` The AUTHENTICATE command with AUTH=NTLM authentication scheme.
    `void` | `authoauth2(String u, String p)` The AUTHENTICATE command with AUTH=XOAUTH2 authentication scheme.
    `void` | `authplain(String authzid, String u, String p)` The AUTHENTICATE command with AUTH=PLAIN authentication scheme.
    `void` | `capability()` CAPABILITY command.
    `void` | `check()` CHECK Command.
    `void` | `close()` CLOSE Command.
    `void` | `compress()` COMPRESS Command.
    `void` | `copy(int start, int end, String mbox)` COPY command.
    `void` | `copy(MessageSet[] msgsets, String mbox)` COPY command.
    `CopyUID` | `copyuid(int start, int end, String mbox)` COPY command, return uid from COPYUID response code.
    `CopyUID` | `copyuid(MessageSet[] msgsets, String mbox)` COPY command, return uid from COPYUID response code.
    `void` | `create(String mbox)` CREATE Command.
    `protected String` | `createFlagList(Flags flags)` Creates an IMAP flag_list from the given Flags object.
    `void` | `delete(String mbox)` DELETE Command.
    `void` | `deleteACL(String mbox, String user)` DELETEACL Command.
    `void` | `disconnect()` Close socket connection.
    `protected ListInfo[]` | `doList(String cmd, String ref, String pat)` Execute the specified LIST-like command (e.g., "LIST" or "LSUB"), using the reference and pattern.
    `void` | `enable(String cap)` ENABLE Command.
    `MailboxInfo` | `examine(String mbox)` EXAMINE Command.
    `MailboxInfo` | `examine(String mbox, ResyncData rd)` EXAMINE Command with QRESYNC data.
    `void` | `expunge()` EXPUNGE Command.
    `Response[]` | `fetch(int start, int end, String what)`
    `Response[]` | `fetch(int msg, String what)`
    `Response[]` | `fetch(MessageSet[] msgsets, String what)`
    `BODY` | `fetchBody(int msgno, String section)` Fetch given BODY section.
    `protected BODY` | `fetchBody(int msgno, String section, boolean peek)`
    `BODY` | `fetchBody(int msgno, String section, int start, int size)` Partial FETCH of given BODY section.
    `protected BODY` | `fetchBody(int msgno, String section, int start, int size, boolean peek, ByteArray ba)`
    `BODY` | `fetchBody(int msgno, String section, int start, int size, ByteArray ba)` Partial FETCH of given BODY section.
    `BODYSTRUCTURE` | `fetchBodyStructure(int msgno)` Fetch the BODYSTRUCTURE of the specified message.
    `Flags` | `fetchFlags(int msgno)` Fetch the FLAGS for the given message.
    `MODSEQ` | `fetchMODSEQ(int msgno)` Fetch the IMAP MODSEQ for the given message.
    `RFC822DATA` | `fetchRFC822(int msgno, String what)` Fetch the specified RFC822 Data item.
    `protected BODY` | `fetchSectionBody(int msgno, String section, String body)` Fetch the given body section of the given message, using the body string "body".
    `void` | `fetchSequenceNumber(long uid)` Get the sequence number for the given UID.
    `void` | `fetchSequenceNumbers(long[] uids)` Get the sequence numbers for UIDs specified in the array.
    `long[]` | `fetchSequenceNumbers(long start, long end)` Get the sequence numbers for UIDs ranging from start till end.
    `UID` | `fetchUID(int msgno)` Fetch the IMAP UID for the given message.
    `ACL[]` | `getACL(String mbox)` GETACL Command.
    `Map<String,String>` | `getCapabilities()` Return the map of capabilities returned by the server.
    `protected CopyUID` | `getCopyUID(Response[] rr)` If the response contains a COPYUID response code, extract it and return a CopyUID object with the information.
    `FetchItem[]` | `getFetchItems()` Return an array of FetchItem objects describing the FETCH items supported by this protocol.
    `String` | `getProxyAuthUser()` Get the user name used with the PROXYAUTH command.
    `Quota[]` | `getQuota(String root)` GETQUOTA Command.
    `Quota[]` | `getQuotaRoot(String mbox)` GETQUOTAROOT Command.
    `protected ByteArray` | `getResponseBuffer()` Return a buffer to read a response into.
    `protected SearchSequence` | `getSearchSequence()` Get the SearchSequence object.
    `boolean` | `hasCapability(String c)` Check whether the given capability is supported by this server.
    `Map<String,String>` | `id(Map<String,String> clientParams)` ID Command.
    `void` | `id(String guid)` Deprecated. As of JavaMail 1.5.1, replaced by `id(Map<String,String>)`
    `void` | `idleAbort()` Abort an IDLE command.
    `void` | `idleStart()` IDLE Command.
    `boolean` | `isAuthenticated()` Returns `true` if the connection has been authenticated, either due to a successful login, or due to a PREAUTH greeting response.
    `boolean` | `isEnabled(String cap)` Is the capability/extension enabled?
    `boolean` | `isREV1()` Returns `true` if this is an IMAP4rev1 server
    `ListInfo[]` | `list(String ref, String pattern)` LIST Command.
    `Rights[]` | `listRights(String mbox, String user)` LISTRIGHTS Command.
    `void` | `login(String u, String p)` LOGIN Command.
    `void` | `logout()` LOGOUT Command.
    `ListInfo[]` | `lsub(String ref, String pattern)` LSUB Command.
    `void` | `move(int start, int end, String mbox)` MOVE command.
    `void` | `move(MessageSet[] msgsets, String mbox)` MOVE command.
    `CopyUID` | `moveuid(int start, int end, String mbox)` MOVE Command, return uid from COPYUID response code.
    `CopyUID` | `moveuid(MessageSet[] msgsets, String mbox)` MOVE Command, return uid from COPYUID response code.
    `Rights` | `myRights(String mbox)` MYRIGHTS Command.
    `Namespaces` | `namespace()` NAMESPACE Command.
    `void` | `noop()` The NOOP command.
    `protected void` | `parseCapabilities(Response r)` Parse the capabilities from a CAPABILITY response or from a CAPABILITY response code attached to (e.g.) an OK response.
    `BODY` | `peekBody(int msgno, String section)` Fetch given BODY section, without marking the message as SEEN.
    `BODY` | `peekBody(int msgno, String section, int start, int size)` Partial FETCH of given BODY section, without setting SEEN flag.
    `BODY` | `peekBody(int msgno, String section, int start, int size, ByteArray ba)` Partial FETCH of given BODY section, without setting SEEN flag.
    `protected void` | `processGreeting(Response r)` Check the greeting when first connecting; look for PREAUTH response.
    `boolean` | `processIdleResponse(Response r)` Process a response returned by readIdleResponse().
    `void` | `proxyauth(String u)` PROXYAUTH Command.
    `Response` | `readIdleResponse()` While an IDLE command is in progress, read a response sent from the server.
    `Response` | `readResponse()` Read a response from the server.
    `void` | `rename(String o, String n)` RENAME Command.
    `void` | `sasllogin(String[] allowed, String realm, String authzid, String u, String p)` SASL-based login.
    `int[]` | `search(MessageSet[] msgsets, SearchTerm term)` Issue the given search criterion on the specified message sets.
    `int[]` | `search(SearchTerm term)` Issue the given search criterion on all messages in this folder.
    `MailboxInfo` | `select(String mbox)` SELECT Command.
    `MailboxInfo` | `select(String mbox, ResyncData rd)` SELECT Command with QRESYNC data.
    `void` | `setACL(String mbox, char modifier, ACL acl)` SETACL Command.
    `protected void` | `setCapabilities(Response r)` If the response contains a CAPABILITY response code, extract it and save the capabilities.
    `void` | `setQuota(Quota quota)` SETQUOTA Command.
    `int[]` | `sort(SortTerm[] term, SearchTerm sterm)` Sort messages in the folder according to the specified sort criteria.
    `void` | `startTLS()` STARTTLS Command.
    `Status` | `status(String mbox, String[] items)` STATUS Command.
    `void` | `storeFlags(int msg, Flags flags, boolean set)` Set the specified flags on this message.
    `void` | `storeFlags(int start, int end, Flags flags, boolean set)`
    `void` | `storeFlags(MessageSet[] msgsets, Flags flags, boolean set)`
    `void` | `subscribe(String mbox)` SUBSCRIBE Command.
    `protected boolean` | `supportsNonSyncLiterals()` Returns whether this Protocol supports non-synchronizing literals.
    `void` | `uidexpunge(UIDSet[] set)` UID EXPUNGE Command.
    `int[]` | `uidfetchChangedSince(long start, long end, long modseq)` Get the sequence numbers for messages changed since the given modseq and with UIDs ranging from start till end.
    `void` | `unauthenticate()` UNAUTHENTICATE Command.
    `void` | `unselect()` UNSELECT Command.
    `void` | `unsubscribe(String mbox)` UNSUBSCRIBE Command.

    - ### Methods inherited from class com.sun.mail.iap.Protocol

      `addResponseHandler, command, finalize, getChannel, getInetAddress, getInputStream, getLocalHost, getOutputStream, getTimestamp, handleResult, hasResponse, isSSL, isTracing, notifyResponseHandlers, removeResponseHandler, resumeTracing, simpleCommand, startCompression, startTLS, suspendTracing, writeCommand`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### searchSequence

          protected SearchSequence searchSequence

    - #### searchCharsets

          protected String[] searchCharsets

    - #### enabled

          protected Set<String> enabled

  - ### Constructor Detail

    - #### IMAPProtocol

          public IMAPProtocol(String name,
                      String host,
                      int port,
                      Properties props,
                      boolean isSSL,
                      MailLogger logger)
                       throws IOException,
                              ProtocolException

      Constructor. Opens a connection to the given host at given port.
      Parameters:
        `name` - the protocol name
        `host` - host to connect to
        `port` - port number to connect to
        `props` - Properties object used by this protocol
        `isSSL` - true if SSL should be used
        `logger` - the MailLogger to use for debug output
      Throws:
        `IOException` - for I/O errors
        `ProtocolException` - for protocol failures

    - #### IMAPProtocol

          public IMAPProtocol(InputStream in,
                      PrintStream out,
                      Properties props,
                      boolean debug)
                       throws IOException

      Constructor for debugging.
      Parameters:
        `in` - the InputStream from which to read
        `out` - the PrintStream to which to write
        `props` - Properties object used by this protocol
        `debug` - true to enable debugging output
      Throws:
        `IOException` - for I/O errors

  - ### Method Detail

    - #### getFetchItems

          public FetchItem[] getFetchItems()

      Return an array of FetchItem objects describing the FETCH items supported by this protocol. Subclasses may override this method to combine their FetchItems with the FetchItems returned by the superclass.
      Returns:
        an array of FetchItem objects
      Since:
        JavaMail 1.4.6

    - #### capability

          public void capability()
                          throws ProtocolException

      CAPABILITY command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.1.1"

    - #### setCapabilities

          protected void setCapabilities(Response r)

      If the response contains a CAPABILITY response code, extract it and save the capabilities.
      Parameters:
        `r` - the response

    - #### parseCapabilities

          protected void parseCapabilities(Response r)

      Parse the capabilities from a CAPABILITY response or from a CAPABILITY response code attached to (e.g.) an OK response.
      Parameters:
        `r` - the CAPABILITY response

    - #### processGreeting

          protected void processGreeting(Response r)
                                  throws ProtocolException

      Check the greeting when first connecting; look for PREAUTH response.
      Overrides:
        `processGreeting` in class `Protocol`
      Parameters:
        `r` - the greeting response
      Throws:
        `ProtocolException` - for protocol failures

    - #### isAuthenticated

          public boolean isAuthenticated()

      Returns `true` if the connection has been authenticated, either due to a successful login, or due to a PREAUTH greeting response.
      Returns:
        true if the connection has been authenticated

    - #### isREV1

          public boolean isREV1()

      Returns `true` if this is an IMAP4rev1 server
      Returns:
        true if this is an IMAP4rev1 server

    - #### supportsNonSyncLiterals

          protected boolean supportsNonSyncLiterals()

      Returns whether this Protocol supports non-synchronizing literals.
      Overrides:
        `supportsNonSyncLiterals` in class `Protocol`
      Returns:
        true if non-synchronizing literals are supported

    - #### readResponse

          public Response readResponse()
                                throws IOException,
                                       ProtocolException

      Read a response from the server.
      Overrides:
        `readResponse` in class `Protocol`
      Returns:
        the response
      Throws:
        `IOException` - for I/O errors
        `ProtocolException` - for protocol failures

    - #### hasCapability

          public boolean hasCapability(String c)

      Check whether the given capability is supported by this server. Returns `true` if so, otherwise returns false.
      Parameters:
        `c` - the capability name
      Returns:
        true if the server has the capability

    - #### getCapabilities

          public Map<String,String> getCapabilities()

      Return the map of capabilities returned by the server.
      Returns:
        the Map of capabilities
      Since:
        JavaMail 1.4.1

    - #### disconnect

          public void disconnect()

      Close socket connection. This method just makes the Protocol.disconnect() method public.
      Overrides:
        `disconnect` in class `Protocol`

    - #### noop

          public void noop()
                    throws ProtocolException

      The NOOP command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.1.2"

    - #### logout

          public void logout()
                      throws ProtocolException

      LOGOUT Command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.1.3"

    - #### login

          public void login(String u,
                   String p)
                     throws ProtocolException

      LOGIN Command.
      Parameters:
        `u` - the username
        `p` - the password
      Throws:
        `ProtocolException` - as thrown by `Protocol.handleResult(com.sun.mail.iap.Response)`.
      See Also:
        "RFC2060, section 6.2.2"

    - #### authlogin

          public void authlogin(String u,
                       String p)
                         throws ProtocolException

      The AUTHENTICATE command with AUTH=LOGIN authenticate scheme
      Parameters:
        `u` - the username
        `p` - the password
      Throws:
        `ProtocolException` - as thrown by `Protocol.handleResult(com.sun.mail.iap.Response)`.
      See Also:
        "RFC2060, section 6.2.1"

    - #### authplain

          public void authplain(String authzid,
                       String u,
                       String p)
                         throws ProtocolException

      The AUTHENTICATE command with AUTH=PLAIN authentication scheme. This is based heavly on the `authlogin(java.lang.String, java.lang.String)` method.
      Parameters:
        `authzid` - the authorization id
        `u` - the username
        `p` - the password
      Throws:
        `ProtocolException` - as thrown by `Protocol.handleResult(com.sun.mail.iap.Response)`.
      Since:
        JavaMail 1.3.2
      See Also:
        "RFC3501, section 6.2.2", "RFC2595, section 6"

    - #### authntlm

          public void authntlm(String authzid,
                      String u,
                      String p)
                        throws ProtocolException

      The AUTHENTICATE command with AUTH=NTLM authentication scheme. This is based heavly on the `authlogin(java.lang.String, java.lang.String)` method.
      Parameters:
        `authzid` - the authorization id
        `u` - the username
        `p` - the password
      Throws:
        `ProtocolException` - as thrown by `Protocol.handleResult(com.sun.mail.iap.Response)`.
      Since:
        JavaMail 1.4.3
      See Also:
        "RFC3501, section 6.2.2", "RFC2595, section 6"

    - #### authoauth2

          public void authoauth2(String u,
                        String p)
                          throws ProtocolException

      The AUTHENTICATE command with AUTH=XOAUTH2 authentication scheme. This is based heavly on the `authlogin(java.lang.String, java.lang.String)` method.
      Parameters:
        `u` - the username
        `p` - the password
      Throws:
        `ProtocolException` - as thrown by `Protocol.handleResult(com.sun.mail.iap.Response)`.
      Since:
        JavaMail 1.5.5
      See Also:
        "RFC3501, section 6.2.2", "RFC2595, section 6"

    - #### sasllogin

          public void sasllogin(String[] allowed,
                       String realm,
                       String authzid,
                       String u,
                       String p)
                         throws ProtocolException

      SASL-based login.
      Parameters:
        `allowed` - the SASL mechanisms we're allowed to use
        `realm` - the SASL realm
        `authzid` - the authorization id
        `u` - the username
        `p` - the password
      Throws:
        `ProtocolException` - for protocol failures

    - #### proxyauth

          public void proxyauth(String u)
                         throws ProtocolException

      PROXYAUTH Command.
      Parameters:
        `u` - the PROXYAUTH user name
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "Netscape/iPlanet/SunONE Messaging Server extension"

    - #### getProxyAuthUser

          public String getProxyAuthUser()

      Get the user name used with the PROXYAUTH command. Returns null if PROXYAUTH was not used.
      Returns:
        the PROXYAUTH user name
      Since:
        JavaMail 1.5.1

    - #### unauthenticate

          public void unauthenticate()
                              throws ProtocolException

      UNAUTHENTICATE Command.
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1
      See Also:
        "Netscape/iPlanet/SunONE Messaging Server extension"

    - #### id

          @Deprecated
          public void id(String guid)
                  throws ProtocolException

      Deprecated. As of JavaMail 1.5.1, replaced by `id(Map<String,String>)`
      ID Command, for Yahoo! Mail IMAP server.
      Parameters:
        `guid` - the GUID
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.4.4

    - #### startTLS

          public void startTLS()
                        throws ProtocolException

      STARTTLS Command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC3501, section 6.2.1"

    - #### compress

          public void compress()
                        throws ProtocolException

      COMPRESS Command. Only supports DEFLATE.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC 4978"

    - #### select

          public MailboxInfo select(String mbox)
                             throws ProtocolException

      SELECT Command.
      Parameters:
        `mbox` - the mailbox name
      Returns:
        MailboxInfo if successful
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.1"

    - #### select

          public MailboxInfo select(String mbox,
                           ResyncData rd)
                             throws ProtocolException

      SELECT Command with QRESYNC data.
      Parameters:
        `mbox` - the mailbox name
        `rd` - the ResyncData
      Returns:
        MailboxInfo if successful
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1
      See Also:
        "RFC2060, section 6.3.1", "RFC5162, section 3.1"

    - #### examine

          public MailboxInfo examine(String mbox)
                              throws ProtocolException

      EXAMINE Command.
      Parameters:
        `mbox` - the mailbox name
      Returns:
        MailboxInfo if successful
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.2"

    - #### examine

          public MailboxInfo examine(String mbox,
                            ResyncData rd)
                              throws ProtocolException

      EXAMINE Command with QRESYNC data.
      Parameters:
        `mbox` - the mailbox name
        `rd` - the ResyncData
      Returns:
        MailboxInfo if successful
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1
      See Also:
        "RFC2060, section 6.3.2", "RFC5162, section 3.1"

    - #### enable

          public void enable(String cap)
                      throws ProtocolException

      ENABLE Command.
      Parameters:
        `cap` - the name of the capability to enable
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1
      See Also:
        "RFC 5161"

    - #### isEnabled

          public boolean isEnabled(String cap)

      Is the capability/extension enabled?
      Parameters:
        `cap` - the capability name
      Returns:
        true if enabled
      Since:
        JavaMail 1.5.1
      See Also:
        "RFC 5161"

    - #### unselect

          public void unselect()
                        throws ProtocolException

      UNSELECT Command.
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.4.4
      See Also:
        "RFC 3691"

    - #### status

          public Status status(String mbox,
                      String[] items)
                        throws ProtocolException

      STATUS Command.
      Parameters:
        `mbox` - the mailbox
        `items` - the STATUS items to request
      Returns:
        STATUS results
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.10"

    - #### create

          public void create(String mbox)
                      throws ProtocolException

      CREATE Command.
      Parameters:
        `mbox` - the mailbox to create
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.3"

    - #### delete

          public void delete(String mbox)
                      throws ProtocolException

      DELETE Command.
      Parameters:
        `mbox` - the mailbox to delete
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.4"

    - #### rename

          public void rename(String o,
                    String n)
                      throws ProtocolException

      RENAME Command.
      Parameters:
        `o` - old mailbox name
        `n` - new mailbox name
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.5"

    - #### subscribe

          public void subscribe(String mbox)
                         throws ProtocolException

      SUBSCRIBE Command.
      Parameters:
        `mbox` - the mailbox
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.6"

    - #### unsubscribe

          public void unsubscribe(String mbox)
                           throws ProtocolException

      UNSUBSCRIBE Command.
      Parameters:
        `mbox` - the mailbox
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.7"

    - #### list

          public ListInfo[] list(String ref,
                        String pattern)
                          throws ProtocolException

      LIST Command.
      Parameters:
        `ref` - reference string
        `pattern` - pattern to list
      Returns:
        LIST results
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.8"

    - #### lsub

          public ListInfo[] lsub(String ref,
                        String pattern)
                          throws ProtocolException

      LSUB Command.
      Parameters:
        `ref` - reference string
        `pattern` - pattern to list
      Returns:
        LSUB results
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.9"

    - #### doList

          protected ListInfo[] doList(String cmd,
                          String ref,
                          String pat)
                               throws ProtocolException

      Execute the specified LIST-like command (e.g., "LIST" or "LSUB"), using the reference and pattern.
      Parameters:
        `cmd` - the list command
        `ref` - the reference string
        `pat` - the pattern
      Returns:
        array of ListInfo results
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.4.6

    - #### append

          public void append(String mbox,
                    Flags f,
                    Date d,
                    Literal data)
                      throws ProtocolException

      APPEND Command.
      Parameters:
        `mbox` - the mailbox
        `f` - the message Flags
        `d` - the message date
        `data` - the message data
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.11"

    - #### appenduid

          public AppendUID appenduid(String mbox,
                            Flags f,
                            Date d,
                            Literal data)
                              throws ProtocolException

      APPEND Command, return uid from APPENDUID response code.
      Parameters:
        `mbox` - the mailbox
        `f` - the message Flags
        `d` - the message date
        `data` - the message data
      Returns:
        APPENDUID data
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.3.11"

    - #### appenduid

          public AppendUID appenduid(String mbox,
                            Flags f,
                            Date d,
                            Literal data,
                            boolean uid)
                              throws ProtocolException

      Throws:
        `ProtocolException`

    - #### check

          public void check()
                     throws ProtocolException

      CHECK Command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.4.1"

    - #### close

          public void close()
                     throws ProtocolException

      CLOSE Command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.4.2"

    - #### expunge

          public void expunge()
                       throws ProtocolException

      EXPUNGE Command.
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2060, section 6.4.3"

    - #### uidexpunge

          public void uidexpunge(UIDSet[] set)
                          throws ProtocolException

      UID EXPUNGE Command.
      Parameters:
        `set` - UIDs to expunge
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC4315, section 2"

    - #### fetchBodyStructure

          public BODYSTRUCTURE fetchBodyStructure(int msgno)
                                           throws ProtocolException

      Fetch the BODYSTRUCTURE of the specified message.
      Parameters:
        `msgno` - the message number
      Returns:
        the BODYSTRUCTURE item
      Throws:
        `ProtocolException` - for protocol failures

    - #### peekBody

          public BODY peekBody(int msgno,
                      String section)
                        throws ProtocolException

      Fetch given BODY section, without marking the message as SEEN.
      Parameters:
        `msgno` - the message number
        `section` - the body section
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchBody

          public BODY fetchBody(int msgno,
                       String section)
                         throws ProtocolException

      Fetch given BODY section.
      Parameters:
        `msgno` - the message number
        `section` - the body section
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchBody

          protected BODY fetchBody(int msgno,
                       String section,
                       boolean peek)
                            throws ProtocolException

      Throws:
        `ProtocolException`

    - #### peekBody

          public BODY peekBody(int msgno,
                      String section,
                      int start,
                      int size)
                        throws ProtocolException

      Partial FETCH of given BODY section, without setting SEEN flag.
      Parameters:
        `msgno` - the message number
        `section` - the body section
        `start` - starting byte count
        `size` - number of bytes to fetch
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchBody

          public BODY fetchBody(int msgno,
                       String section,
                       int start,
                       int size)
                         throws ProtocolException

      Partial FETCH of given BODY section.
      Parameters:
        `msgno` - the message number
        `section` - the body section
        `start` - starting byte count
        `size` - number of bytes to fetch
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### peekBody

          public BODY peekBody(int msgno,
                      String section,
                      int start,
                      int size,
                      ByteArray ba)
                        throws ProtocolException

      Partial FETCH of given BODY section, without setting SEEN flag.
      Parameters:
        `msgno` - the message number
        `section` - the body section
        `start` - starting byte count
        `size` - number of bytes to fetch
        `ba` - the buffer into which to read the response
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchBody

          public BODY fetchBody(int msgno,
                       String section,
                       int start,
                       int size,
                       ByteArray ba)
                         throws ProtocolException

      Partial FETCH of given BODY section.
      Parameters:
        `msgno` - the message number
        `section` - the body section
        `start` - starting byte count
        `size` - number of bytes to fetch
        `ba` - the buffer into which to read the response
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchBody

          protected BODY fetchBody(int msgno,
                       String section,
                       int start,
                       int size,
                       boolean peek,
                       ByteArray ba)
                            throws ProtocolException

      Throws:
        `ProtocolException`

    - #### fetchSectionBody

          protected BODY fetchSectionBody(int msgno,
                              String section,
                              String body)
                                   throws ProtocolException

      Fetch the given body section of the given message, using the body string "body".
      Parameters:
        `msgno` - the message number
        `section` - the body section
        `body` - the body string
      Returns:
        the BODY item
      Throws:
        `ProtocolException` - for protocol failures

    - #### getResponseBuffer

          protected ByteArray getResponseBuffer()

      Return a buffer to read a response into. The buffer is provided by fetchBody and is used only once.
      Overrides:
        `getResponseBuffer` in class `Protocol`
      Returns:
        the buffer to use

    - #### fetchRFC822

          public RFC822DATA fetchRFC822(int msgno,
                               String what)
                                 throws ProtocolException

      Fetch the specified RFC822 Data item. 'what' names the item to be fetched. 'what' can be `null` to fetch the whole message.
      Parameters:
        `msgno` - the message number
        `what` - the item to fetch
      Returns:
        the RFC822DATA item
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchFlags

          public Flags fetchFlags(int msgno)
                           throws ProtocolException

      Fetch the FLAGS for the given message.
      Parameters:
        `msgno` - the message number
      Returns:
        the Flags
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchUID

          public UID fetchUID(int msgno)
                       throws ProtocolException

      Fetch the IMAP UID for the given message.
      Parameters:
        `msgno` - the message number
      Returns:
        the UID
      Throws:
        `ProtocolException` - for protocol failures

    - #### fetchMODSEQ

          public MODSEQ fetchMODSEQ(int msgno)
                             throws ProtocolException

      Fetch the IMAP MODSEQ for the given message.
      Parameters:
        `msgno` - the message number
      Returns:
        the MODSEQ
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1

    - #### fetchSequenceNumber

          public void fetchSequenceNumber(long uid)
                                   throws ProtocolException

      Get the sequence number for the given UID. Nothing is returned; the FETCH UID response must be handled by the reponse handler, along with any possible EXPUNGE responses, to ensure that the UID is matched with the correct sequence number.
      Parameters:
        `uid` - the UID
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.3

    - #### fetchSequenceNumbers

          public long[] fetchSequenceNumbers(long start,
                                    long end)
                                      throws ProtocolException

      Get the sequence numbers for UIDs ranging from start till end. Since the range may be large and sparse, an array of the UIDs actually found is returned. The caller must map these to messages after the FETCH UID responses have been handled by the reponse handler, along with any possible EXPUNGE responses, to ensure that the UIDs are matched with the correct sequence numbers.
      Parameters:
        `start` - first UID
        `end` - last UID
      Returns:
        array of sequence numbers
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.3

    - #### fetchSequenceNumbers

          public void fetchSequenceNumbers(long[] uids)
                                    throws ProtocolException

      Get the sequence numbers for UIDs specified in the array. Nothing is returned. The caller must map the UIDs to messages after the FETCH UID responses have been handled by the reponse handler, along with any possible EXPUNGE responses, to ensure that the UIDs are matched with the correct sequence numbers.
      Parameters:
        `uids` - the UIDs
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.3

    - #### uidfetchChangedSince

          public int[] uidfetchChangedSince(long start,
                                   long end,
                                   long modseq)
                                     throws ProtocolException

      Get the sequence numbers for messages changed since the given modseq and with UIDs ranging from start till end. Also, prefetch the flags for the returned messages.
      Parameters:
        `start` - first UID
        `end` - last UID
        `modseq` - the MODSEQ
      Returns:
        array of sequence numbers
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1
      See Also:
        "RFC 4551"

    - #### fetch

          public Response[] fetch(MessageSet[] msgsets,
                         String what)
                           throws ProtocolException

      Throws:
        `ProtocolException`

    - #### fetch

          public Response[] fetch(int start,
                         int end,
                         String what)
                           throws ProtocolException

      Throws:
        `ProtocolException`

    - #### fetch

          public Response[] fetch(int msg,
                         String what)
                           throws ProtocolException

      Throws:
        `ProtocolException`

    - #### copy

          public void copy(MessageSet[] msgsets,
                  String mbox)
                    throws ProtocolException

      COPY command.
      Parameters:
        `msgsets` - the messages to copy
        `mbox` - the mailbox to copy them to
      Throws:
        `ProtocolException` - for protocol failures

    - #### copy

          public void copy(int start,
                  int end,
                  String mbox)
                    throws ProtocolException

      COPY command.
      Parameters:
        `start` - start message number
        `end` - end message number
        `mbox` - the mailbox to copy them to
      Throws:
        `ProtocolException` - for protocol failures

    - #### copyuid

          public CopyUID copyuid(MessageSet[] msgsets,
                        String mbox)
                          throws ProtocolException

      COPY command, return uid from COPYUID response code.
      Parameters:
        `msgsets` - the messages to copy
        `mbox` - the mailbox to copy them to
      Returns:
        COPYUID response data
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC 4315, section 3"

    - #### copyuid

          public CopyUID copyuid(int start,
                        int end,
                        String mbox)
                          throws ProtocolException

      COPY command, return uid from COPYUID response code.
      Parameters:
        `start` - start message number
        `end` - end message number
        `mbox` - the mailbox to copy them to
      Returns:
        COPYUID response data
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC 4315, section 3"

    - #### move

          public void move(MessageSet[] msgsets,
                  String mbox)
                    throws ProtocolException

      MOVE command.
      Parameters:
        `msgsets` - the messages to move
        `mbox` - the mailbox to move them to
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.4
      See Also:
        "RFC 6851"

    - #### move

          public void move(int start,
                  int end,
                  String mbox)
                    throws ProtocolException

      MOVE command.
      Parameters:
        `start` - start message number
        `end` - end message number
        `mbox` - the mailbox to move them to
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.4
      See Also:
        "RFC 6851"

    - #### moveuid

          public CopyUID moveuid(MessageSet[] msgsets,
                        String mbox)
                          throws ProtocolException

      MOVE Command, return uid from COPYUID response code.
      Parameters:
        `msgsets` - the messages to move
        `mbox` - the mailbox to move them to
      Returns:
        COPYUID response data
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.4
      See Also:
        "RFC 6851", "RFC 4315, section 3"

    - #### moveuid

          public CopyUID moveuid(int start,
                        int end,
                        String mbox)
                          throws ProtocolException

      MOVE Command, return uid from COPYUID response code.
      Parameters:
        `start` - start message number
        `end` - end message number
        `mbox` - the mailbox to move them to
      Returns:
        COPYUID response data
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.4
      See Also:
        "RFC 6851", "RFC 4315, section 3"

    - #### getCopyUID

          protected CopyUID getCopyUID(Response[] rr)

      If the response contains a COPYUID response code, extract it and return a CopyUID object with the information.
      Parameters:
        `rr` - the responses to examine
      Returns:
        the COPYUID response code data, or null if not found
      Since:
        JavaMail 1.5.4

    - #### storeFlags

          public void storeFlags(MessageSet[] msgsets,
                        Flags flags,
                        boolean set)
                          throws ProtocolException

      Throws:
        `ProtocolException`

    - #### storeFlags

          public void storeFlags(int start,
                        int end,
                        Flags flags,
                        boolean set)
                          throws ProtocolException

      Throws:
        `ProtocolException`

    - #### storeFlags

          public void storeFlags(int msg,
                        Flags flags,
                        boolean set)
                          throws ProtocolException

      Set the specified flags on this message.
      Parameters:
        `msg` - the message number
        `flags` - the flags
        `set` - true to set, false to clear
      Throws:
        `ProtocolException` - for protocol failures

    - #### createFlagList

          protected String createFlagList(Flags flags)

      Creates an IMAP flag_list from the given Flags object.
      Parameters:
        `flags` - the flags
      Returns:
        the IMAP flag_list
      Since:
        JavaMail 1.5.4

    - #### search

          public int[] search(MessageSet[] msgsets,
                     SearchTerm term)
                       throws ProtocolException,
                              SearchException

      Issue the given search criterion on the specified message sets. Returns array of matching sequence numbers. An empty array is returned if no matches are found.
      Parameters:
        `msgsets` - array of MessageSets
        `term` - SearchTerm
      Returns:
        array of matching sequence numbers.
      Throws:
        `ProtocolException` - for protocol failures
        `SearchException` - for search failures

    - #### search

          public int[] search(SearchTerm term)
                       throws ProtocolException,
                              SearchException

      Issue the given search criterion on all messages in this folder. Returns array of matching sequence numbers. An empty array is returned if no matches are found.
      Parameters:
        `term` - SearchTerm
      Returns:
        array of matching sequence numbers.
      Throws:
        `ProtocolException` - for protocol failures
        `SearchException` - for search failures

    - #### getSearchSequence

          protected SearchSequence getSearchSequence()

      Get the SearchSequence object. The SearchSequence object instance is saved in the searchSequence field. Subclasses of IMAPProtocol may override this method to return a subclass of SearchSequence, in order to add support for product-specific search terms.
      Returns:
        the SearchSequence
      Since:
        JavaMail 1.4.6

    - #### sort

          public int[] sort(SortTerm[] term,
                   SearchTerm sterm)
                     throws ProtocolException,
                            SearchException

      Sort messages in the folder according to the specified sort criteria. If the search term is not null, limit the sort to only the messages that match the search term. Returns an array of sorted sequence numbers. An empty array is returned if no matches are found.
      Parameters:
        `term` - sort criteria
        `sterm` - SearchTerm
      Returns:
        array of matching sequence numbers.
      Throws:
        `ProtocolException` - for protocol failures
        `SearchException` - for search failures
      Since:
        JavaMail 1.4.4
      See Also:
        "RFC 5256"

    - #### namespace

          public Namespaces namespace()
                               throws ProtocolException

      NAMESPACE Command.
      Returns:
        the namespaces
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2342"

    - #### getQuotaRoot

          public Quota[] getQuotaRoot(String mbox)
                               throws ProtocolException

      GETQUOTAROOT Command. Returns an array of Quota objects, representing the quotas for this mailbox and, indirectly, the quotaroots for this mailbox.
      Parameters:
        `mbox` - the mailbox
      Returns:
        array of Quota objects
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2087"

    - #### getQuota

          public Quota[] getQuota(String root)
                           throws ProtocolException

      GETQUOTA Command. Returns an array of Quota objects, representing the quotas for this quotaroot.
      Parameters:
        `root` - the quotaroot
      Returns:
        the quotas
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2087"

    - #### setQuota

          public void setQuota(Quota quota)
                        throws ProtocolException

      SETQUOTA Command. Set the indicated quota on the corresponding quotaroot.
      Parameters:
        `quota` - the quota to set
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2087"

    - #### setACL

          public void setACL(String mbox,
                    char modifier,
                    ACL acl)
                      throws ProtocolException

      SETACL Command.
      Parameters:
        `mbox` - the mailbox
        `modifier` - the ACL modifier
        `acl` - the ACL
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2086"

    - #### deleteACL

          public void deleteACL(String mbox,
                       String user)
                         throws ProtocolException

      DELETEACL Command.
      Parameters:
        `mbox` - the mailbox
        `user` - the user
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2086"

    - #### getACL

          public ACL[] getACL(String mbox)
                       throws ProtocolException

      GETACL Command.
      Parameters:
        `mbox` - the mailbox
      Returns:
        the ACL array
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2086"

    - #### listRights

          public Rights[] listRights(String mbox,
                            String user)
                              throws ProtocolException

      LISTRIGHTS Command.
      Parameters:
        `mbox` - the mailbox
        `user` - the user rights to return
      Returns:
        the rights array
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2086"

    - #### myRights

          public Rights myRights(String mbox)
                          throws ProtocolException

      MYRIGHTS Command.
      Parameters:
        `mbox` - the mailbox
      Returns:
        the rights
      Throws:
        `ProtocolException` - for protocol failures
      See Also:
        "RFC2086"

    - #### idleStart

          public void idleStart()
                         throws ProtocolException

      IDLE Command.

      If the server supports the IDLE command extension, the IDLE command is issued and this method blocks until a response has been received. Once the first response has been received, the IDLE command is terminated and all responses are collected and handled and this method returns.

      Note that while this method is blocked waiting for a response, no other threads may issue any commands to the server that would use this same connection.

      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.4.1
      See Also:
        "RFC2177"

    - #### readIdleResponse

          public Response readIdleResponse()

      While an IDLE command is in progress, read a response sent from the server. The response is read with no locks held so that when the read blocks waiting for the response from the server it's not holding locks that would prevent other threads from interrupting the IDLE command.
      Returns:
        the response
      Since:
        JavaMail 1.4.1

    - #### processIdleResponse

          public boolean processIdleResponse(Response r)
                                      throws ProtocolException

      Process a response returned by readIdleResponse(). This method will be called with appropriate locks held so that the processing of the response is safe.
      Parameters:
        `r` - the response
      Returns:
        true if IDLE is done
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.4.1

    - #### idleAbort

          public void idleAbort()

      Abort an IDLE command. While one thread is blocked in readIdleResponse(), another thread will use this method to abort the IDLE command, which will cause the server to send the closing tag for the IDLE command, which readIdleResponse() and processIdleResponse() will see and terminate the IDLE state.
      Since:
        JavaMail 1.4.1

    - #### id

          public Map<String,String> id(Map<String,String> clientParams)
                                throws ProtocolException

      ID Command.
      Parameters:
        `clientParams` - map of names and values
      Returns:
        map of names and values from server
      Throws:
        `ProtocolException` - for protocol failures
      Since:
        JavaMail 1.5.1
      See Also:
        "RFC 2971"

Copyright © 2016 Oracle. All rights reserved.