Package 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
`protected java.util.Set<java.lang.String>` `enabled`
`protected java.lang.String[]` `searchCharsets`
`protected SearchSequence` `searchSequence`

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

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

### Constructor Summary

Constructors
`IMAPProtocol​(java.io.InputStream in, java.io.PrintStream out, java.util.Properties props, boolean debug)` Constructor for debugging.
`IMAPProtocol​(java.lang.String name, java.lang.String host, int port, java.util.Properties props, boolean isSSL, MailLogger logger)` Constructor.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `append​(java.lang.String mbox, Flags f, java.util.Date d, Literal data)` APPEND Command.
`AppendUID` `appenduid​(java.lang.String mbox, Flags f, java.util.Date d, Literal data)` APPEND Command, return uid from APPENDUID response code.
`AppendUID` `appenduid​(java.lang.String mbox, Flags f, java.util.Date d, Literal data, boolean uid)`
`void` `authlogin​(java.lang.String u, java.lang.String p)` The AUTHENTICATE command with AUTH=LOGIN authenticate scheme
`void` `authntlm​(java.lang.String authzid, java.lang.String u, java.lang.String p)` The AUTHENTICATE command with AUTH=NTLM authentication scheme.
`void` `authoauth2​(java.lang.String u, java.lang.String p)` The AUTHENTICATE command with AUTH=XOAUTH2 authentication scheme.
`void` `authplain​(java.lang.String authzid, java.lang.String u, java.lang.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, java.lang.String mbox)` COPY command.
`void` `copy​(MessageSet[] msgsets, java.lang.String mbox)` COPY command.
`CopyUID` `copyuid​(int start, int end, java.lang.String mbox)` COPY command, return uid from COPYUID response code.
`CopyUID` `copyuid​(MessageSet[] msgsets, java.lang.String mbox)` COPY command, return uid from COPYUID response code.
`void` `create​(java.lang.String mbox)` CREATE Command.
`protected java.lang.String` `createFlagList​(Flags flags)` Creates an IMAP flag_list from the given Flags object.
`void` `delete​(java.lang.String mbox)` DELETE Command.
`void` `deleteACL​(java.lang.String mbox, java.lang.String user)` DELETEACL Command.
`void` `disconnect()` Close socket connection.
`protected ListInfo[]` `doList​(java.lang.String cmd, java.lang.String ref, java.lang.String pat)` Execute the specified LIST-like command (e.g., "LIST" or "LSUB"), using the reference and pattern.
`void` `enable​(java.lang.String cap)` ENABLE Command.
`MailboxInfo` `examine​(java.lang.String mbox)` EXAMINE Command.
`MailboxInfo` `examine​(java.lang.String mbox, ResyncData rd)` EXAMINE Command with QRESYNC data.
`void` `expunge()` EXPUNGE Command.
`Response[]` `fetch​(int start, int end, java.lang.String what)`
`Response[]` `fetch​(int msg, java.lang.String what)`
`Response[]` `fetch​(MessageSet[] msgsets, java.lang.String what)`
`BODY` `fetchBody​(int msgno, java.lang.String section)` Fetch given BODY section.
`protected BODY` `fetchBody​(int msgno, java.lang.String section, boolean peek)`
`BODY` `fetchBody​(int msgno, java.lang.String section, int start, int size)` Partial FETCH of given BODY section.
`protected BODY` `fetchBody​(int msgno, java.lang.String section, int start, int size, boolean peek, ByteArray ba)`
`BODY` `fetchBody​(int msgno, java.lang.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, java.lang.String what)` Fetch the specified RFC822 Data item.
`protected BODY` `fetchSectionBody​(int msgno, java.lang.String section, java.lang.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​(java.lang.String mbox)` GETACL Command.
`java.util.Map<java.lang.String,​java.lang.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.
`java.lang.String` `getProxyAuthUser()` Get the user name used with the PROXYAUTH command.
`Quota[]` `getQuota​(java.lang.String root)` GETQUOTA Command.
`Quota[]` `getQuotaRoot​(java.lang.String mbox)` GETQUOTAROOT Command.
`protected ByteArray` `getResponseBuffer()` Return a buffer to read a response into.
`protected SearchSequence` `getSearchSequence()` Get the SearchSequence object.
`void` `handleCapabilityResponse​(Response[] r)` Handle any untagged CAPABILITY response in the Response array.
`protected void` `handleLoginResult​(Response r)` Handle the result response for a LOGIN or AUTHENTICATE command.
`boolean` `hasCapability​(java.lang.String c)` Check whether the given capability is supported by this server.
`void` `id​(java.lang.String guid)` Deprecated. As of JavaMail 1.5.1, replaced by `id(Map<String,String>)`
`java.util.Map<java.lang.String,​java.lang.String>` `id​(java.util.Map<java.lang.String,​java.lang.String> clientParams)` ID Command.
`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​(java.lang.String cap)` Is the capability/extension enabled?
`boolean` `isREV1()` Returns `true` if this is an IMAP4rev1 server
`ListInfo[]` `list​(java.lang.String ref, java.lang.String pattern)` LIST Command.
`Rights[]` `listRights​(java.lang.String mbox, java.lang.String user)` LISTRIGHTS Command.
`void` `login​(java.lang.String u, java.lang.String p)` LOGIN Command.
`void` `logout()` LOGOUT Command.
`ListInfo[]` `lsub​(java.lang.String ref, java.lang.String pattern)` LSUB Command.
`void` `move​(int start, int end, java.lang.String mbox)` MOVE command.
`void` `move​(MessageSet[] msgsets, java.lang.String mbox)` MOVE command.
`CopyUID` `moveuid​(int start, int end, java.lang.String mbox)` MOVE Command, return uid from COPYUID response code.
`CopyUID` `moveuid​(MessageSet[] msgsets, java.lang.String mbox)` MOVE Command, return uid from COPYUID response code.
`Rights` `myRights​(java.lang.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, java.lang.String section)` Fetch given BODY section, without marking the message as SEEN.
`BODY` `peekBody​(int msgno, java.lang.String section, int start, int size)` Partial FETCH of given BODY section, without setting SEEN flag.
`BODY` `peekBody​(int msgno, java.lang.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​(java.lang.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​(java.lang.String o, java.lang.String n)` RENAME Command.
`void` `sasllogin​(java.lang.String[] allowed, java.lang.String realm, java.lang.String authzid, java.lang.String u, java.lang.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​(java.lang.String mbox)` SELECT Command.
`MailboxInfo` `select​(java.lang.String mbox, ResyncData rd)` SELECT Command with QRESYNC data.
`void` `setACL​(java.lang.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​(java.lang.String mbox, java.lang.String[] items)` STATUS Command.
`void` `storeFlags​(int start, int end, Flags flags, boolean set)`
`void` `storeFlags​(int msg, Flags flags, boolean set)` Set the specified flags on this message.
`void` `storeFlags​(MessageSet[] msgsets, Flags flags, boolean set)`
`void` `subscribe​(java.lang.String mbox)` SUBSCRIBE Command.
`protected boolean` `supportsNonSyncLiterals()` Returns whether this Protocol supports non-synchronizing literals.
`boolean` `supportsUtf8()` Does the server support UTF-8?
`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​(java.lang.String mbox)` UNSUBSCRIBE Command.
`protected void` `writeMailboxName​(Argument args, java.lang.String name)` Encode a mailbox name appropriately depending on whether or not the server supports UTF-8, and add the encoded name to the Argument.

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

`addResponseHandler, command, finalize, getChannel, getInetAddress, getInputStream, getLocalHost, getLocalSocketAddress, 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 java.lang.String[] searchCharsets

#### enabled

    protected java.util.Set<java.lang.String> enabled

### Constructor Detail

#### IMAPProtocol

    public IMAPProtocol​(java.lang.String name,
                        java.lang.String host,
                        int port,
                        java.util.Properties props,
                        boolean isSSL,
                        MailLogger logger)
                 throws java.io.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:
  `java.io.IOException` - for I/O errors
  `ProtocolException` - for protocol failures

#### IMAPProtocol

    public IMAPProtocol​(java.io.InputStream in,
                        java.io.PrintStream out,
                        java.util.Properties props,
                        boolean debug)
                 throws java.io.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:
  `java.io.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"

#### handleCapabilityResponse

    public void handleCapabilityResponse​(Response[] r)

Handle any untagged CAPABILITY response in the Response array.

Parameters:
  `r` - the responses

#### 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 java.io.IOException,
                                 ProtocolException

Read a response from the server.

Overrides:
  `readResponse` in class `Protocol`
Returns:
  the response
Throws:
  `java.io.IOException` - for I/O errors
  `ProtocolException` - for protocol failures

#### hasCapability

    public boolean hasCapability​(java.lang.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 java.util.Map<java.lang.String,​java.lang.String> getCapabilities()

Return the map of capabilities returned by the server.

Returns:
  the Map of capabilities
Since:
  JavaMail 1.4.1

#### supportsUtf8

    public boolean supportsUtf8()

Does the server support UTF-8?

Overrides:
  `supportsUtf8` in class `Protocol`
Returns:
  true if the server supports UTF-8
Since:
  JavaMail 1.6.0

#### 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​(java.lang.String u,
                      java.lang.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​(java.lang.String u,
                          java.lang.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​(java.lang.String authzid,
                          java.lang.String u,
                          java.lang.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​(java.lang.String authzid,
                         java.lang.String u,
                         java.lang.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​(java.lang.String u,
                           java.lang.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​(java.lang.String[] allowed,
                          java.lang.String realm,
                          java.lang.String authzid,
                          java.lang.String u,
                          java.lang.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

#### handleLoginResult

    protected void handleLoginResult​(Response r)
                              throws ProtocolException

Handle the result response for a LOGIN or AUTHENTICATE command. Look for IMAP login REFERRAL.

Parameters:
  `r` - the response
Throws:
  `ProtocolException` - for protocol failures
Since:
  JavaMail 1.5.5

#### proxyauth

    public void proxyauth​(java.lang.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 java.lang.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​(java.lang.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"

#### writeMailboxName

    protected void writeMailboxName​(Argument args,
                                    java.lang.String name)

Encode a mailbox name appropriately depending on whether or not the server supports UTF-8, and add the encoded name to the Argument.

Parameters:
  `args` - the arguments
  `name` - the name to encode
Since:
  JavaMail 1.6.0

#### select

    public MailboxInfo select​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String mbox,
                         java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String o,
                       java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String ref,
                           java.lang.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​(java.lang.String ref,
                           java.lang.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​(java.lang.String cmd,
                                java.lang.String ref,
                                java.lang.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​(java.lang.String mbox,
                       Flags f,
                       java.util.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​(java.lang.String mbox,
                               Flags f,
                               java.util.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​(java.lang.String mbox,
                               Flags f,
                               java.util.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,
                         java.lang.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,
                          java.lang.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,
                             java.lang.String section,
                             boolean peek)
                      throws ProtocolException

Throws:
  `ProtocolException`

#### peekBody

    public BODY peekBody​(int msgno,
                         java.lang.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,
                          java.lang.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,
                         java.lang.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,
                          java.lang.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,
                             java.lang.String section,
                             int start,
                             int size,
                             boolean peek,
                             ByteArray ba)
                      throws ProtocolException

Throws:
  `ProtocolException`

#### fetchSectionBody

    protected BODY fetchSectionBody​(int msgno,
                                    java.lang.String section,
                                    java.lang.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,
                                  java.lang.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,
                            java.lang.String what)
                     throws ProtocolException

Throws:
  `ProtocolException`

#### fetch

    public Response[] fetch​(int start,
                            int end,
                            java.lang.String what)
                     throws ProtocolException

Throws:
  `ProtocolException`

#### fetch

    public Response[] fetch​(int msg,
                            java.lang.String what)
                     throws ProtocolException

Throws:
  `ProtocolException`

#### copy

    public void copy​(MessageSet[] msgsets,
                     java.lang.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,
                     java.lang.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,
                           java.lang.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,
                           java.lang.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,
                     java.lang.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,
                     java.lang.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,
                           java.lang.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,
                           java.lang.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 java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String mbox,
                          java.lang.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​(java.lang.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​(java.lang.String mbox,
                               java.lang.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​(java.lang.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 java.util.Map<java.lang.String,​java.lang.String> id​(java.util.Map<java.lang.String,​java.lang.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"