IMAP
Date: 2016-06-23

org.apache.commons.net.imap

## Class IMAP

- java.lang.Object
- - org.apache.commons.net.SocketClient
  - - org.apache.commons.net.imap.IMAP

- Direct Known Subclasses:
    IMAPClient

      public class IMAP
      extends SocketClient

  The IMAP class provides the basic the functionality necessary to implement your own IMAP client.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `IMAP.IMAPChunkListener` Implement this interface and register it via `setChunkListener(IMAPChunkListener)` in order to get access to multi-line partial command responses.
    `static class` | `IMAP.IMAPState`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.lang.String` | `__DEFAULT_ENCODING` The default control socket ecoding.
    `protected java.io.BufferedWriter` | `__writer`
    `protected java.io.BufferedReader` | `_reader`
    `static int` | `DEFAULT_PORT` The default IMAP port (RFC 3501).
    `static IMAP.IMAPChunkListener` | `TRUE_CHUNK_LISTENER` Implementation of IMAPChunkListener that returns `true` but otherwise does nothing.

    - ### Fields inherited from class org.apache.commons.net.SocketClient

      `_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IMAP()` The default IMAPClient constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `_connectAction_()` Performs connection initialization and sets state to `IMAP.IMAPState.NOT_AUTH_STATE`.
    `void` | `disconnect()` Disconnects the client from the server, and sets the state to `DISCONNECTED_STATE` .
    `boolean` | `doCommand(IMAPCommand command)` Sends a command to the server and return whether successful.
    `boolean` | `doCommand(IMAPCommand command, java.lang.String args)` Sends a command and arguments to the server and return whether successful.
    `protected void` | `fireReplyReceived(int replyCode, java.lang.String ignored)` Overrides `SocketClient.fireReplyReceived(int, String)` so as to avoid creating the reply string if there are no listeners to invoke.
    `protected java.lang.String` | `generateCommandID()` Generates a new command ID (tag) for a command.
    `java.lang.String` | `getReplyString()` Returns the reply to the last command sent to the server.
    `java.lang.String[]` | `getReplyStrings()` Returns an array of lines received as a reply to the last command sent to the server.
    `IMAP.IMAPState` | `getState()` Returns the current IMAP client state.
    `int` | `sendCommand(IMAPCommand command)` Sends a command with no arguments to the server and returns the reply code.
    `int` | `sendCommand(IMAPCommand command, java.lang.String args)` Sends a command and arguments to the server and returns the reply code.
    `int` | `sendCommand(java.lang.String command)` Sends a command with no arguments to the server and returns the reply code.
    `int` | `sendCommand(java.lang.String command, java.lang.String args)` Sends a command an arguments to the server and returns the reply code.
    `int` | `sendData(java.lang.String command)` Sends data to the server and returns the reply code.
    `void` | `setChunkListener(IMAP.IMAPChunkListener listener)` Sets the current chunk listener.
    `protected void` | `setState(IMAP.IMAPState state)` Sets IMAP client state.

    - ### Methods inherited from class org.apache.commons.net.SocketClient

      `addProtocolCommandListener, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, getCharset, getCharsetName, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote`

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

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

- - ### Field Detail

    - #### DEFAULT_PORT

          public static final int DEFAULT_PORT

      The default IMAP port (RFC 3501).
      See Also:
        Constant Field Values

    - #### __DEFAULT_ENCODING

          protected static final java.lang.String __DEFAULT_ENCODING

      The default control socket ecoding.
      See Also:
        Constant Field Values

    - #### __writer

          protected java.io.BufferedWriter __writer

    - #### _reader

          protected java.io.BufferedReader _reader

    - #### TRUE_CHUNK_LISTENER

          public static final IMAP.IMAPChunkListener TRUE_CHUNK_LISTENER

      Implementation of IMAPChunkListener that returns `true` but otherwise does nothing.

      This is intended for use with a suitable ProtocolCommandListener. If the IMAP response contains multiple-line data, the protocol listener will be called for each multi-line chunk. The accumulated reply data will be cleared after calling the listener. If the response is very long, this can significantly reduce memory requirements. The listener will also start receiving response data earlier, as it does not have to wait for the entire response to be read.

      The ProtocolCommandListener must be prepared to accept partial responses. This should not be a problem for listeners that just log the input.

      Since:
        3.4
      See Also:
        `setChunkListener(IMAPChunkListener)`

  - ### Constructor Detail

    - #### IMAP

          public IMAP()

      The default IMAPClient constructor. Initializes the state to `DISCONNECTED_STATE`.

  - ### Method Detail

    - #### fireReplyReceived

          protected void fireReplyReceived(int replyCode,
                               java.lang.String ignored)

      Overrides `SocketClient.fireReplyReceived(int, String)` so as to avoid creating the reply string if there are no listeners to invoke.
      Overrides:
        `fireReplyReceived` in class `SocketClient`
      Parameters:
        `replyCode` - passed to the listeners
        `ignored` - the string is only created if there are listeners defined.
      Since:
        3.4
      See Also:
        `getReplyString()`

    - #### _connectAction_

          protected void _connectAction_()
                                  throws java.io.IOException

      Performs connection initialization and sets state to `IMAP.IMAPState.NOT_AUTH_STATE`.
      Overrides:
        `_connectAction_` in class `SocketClient`
      Throws:
        `java.io.IOException` - (SocketException) if a problem occurs with the socket

    - #### setState

          protected void setState(IMAP.IMAPState state)

      Sets IMAP client state. This must be one of the `_STATE` constants.
      Parameters:
        `state` - The new state.

    - #### getState

          public IMAP.IMAPState getState()

      Returns the current IMAP client state.
      Returns:
        The current IMAP client state.

    - #### disconnect

          public void disconnect()
                          throws java.io.IOException

      Disconnects the client from the server, and sets the state to `DISCONNECTED_STATE` . The reply text information from the last issued command is voided to allow garbage collection of the memory used to store that information.
      Overrides:
        `disconnect` in class `SocketClient`
      Throws:
        `java.io.IOException` - If there is an error in disconnecting.

    - #### sendCommand

          public int sendCommand(java.lang.String command,
                        java.lang.String args)
                          throws java.io.IOException

      Sends a command an arguments to the server and returns the reply code.
      Parameters:
        `command` - The IMAP command to send.
        `args` - The command arguments.
      Returns:
        The server reply code (see IMAPReply).
      Throws:
        `java.io.IOException` - on error

    - #### sendCommand

          public int sendCommand(java.lang.String command)
                          throws java.io.IOException

      Sends a command with no arguments to the server and returns the reply code.
      Parameters:
        `command` - The IMAP command to send.
      Returns:
        The server reply code (see IMAPReply).
      Throws:
        `java.io.IOException` - on error

    - #### sendCommand

          public int sendCommand(IMAPCommand command,
                        java.lang.String args)
                          throws java.io.IOException

      Sends a command and arguments to the server and returns the reply code.
      Parameters:
        `command` - The IMAP command to send (one of the IMAPCommand constants).
        `args` - The command arguments.
      Returns:
        The server reply code (see IMAPReply).
      Throws:
        `java.io.IOException` - on error

    - #### doCommand

          public boolean doCommand(IMAPCommand command,
                          java.lang.String args)
                            throws java.io.IOException

      Sends a command and arguments to the server and return whether successful.
      Parameters:
        `command` - The IMAP command to send (one of the IMAPCommand constants).
        `args` - The command arguments.
      Returns:
        `true` if the command was successful
      Throws:
        `java.io.IOException` - on error

    - #### sendCommand

          public int sendCommand(IMAPCommand command)
                          throws java.io.IOException

      Sends a command with no arguments to the server and returns the reply code.
      Parameters:
        `command` - The IMAP command to send (one of the IMAPCommand constants).
      Returns:
        The server reply code (see IMAPReply).
      Throws:
        `java.io.IOException` - on error

    - #### doCommand

          public boolean doCommand(IMAPCommand command)
                            throws java.io.IOException

      Sends a command to the server and return whether successful.
      Parameters:
        `command` - The IMAP command to send (one of the IMAPCommand constants).
      Returns:
        `true` if the command was successful
      Throws:
        `java.io.IOException` - on error

    - #### sendData

          public int sendData(java.lang.String command)
                       throws java.io.IOException

      Sends data to the server and returns the reply code.
      Parameters:
        `command` - The IMAP command to send.
      Returns:
        The server reply code (see IMAPReply).
      Throws:
        `java.io.IOException` - on error

    - #### getReplyStrings

          public java.lang.String[] getReplyStrings()

      Returns an array of lines received as a reply to the last command sent to the server. The lines have end of lines truncated.
      Returns:
        The last server response.

    - #### getReplyString

          public java.lang.String getReplyString()

      Returns the reply to the last command sent to the server. The value is a single string containing all the reply lines including newlines.
      Returns:
        The last server response.

    - #### setChunkListener

          public void setChunkListener(IMAP.IMAPChunkListener listener)

      Sets the current chunk listener. If a listener is registered and the implementation returns true, then any registered `PrintCommandListener` instances will be invoked with the partial response and a status of `IMAPReply.PARTIAL` to indicate that the final reply code is not yet known.
      Parameters:
        `listener` - the class to use, or `null` to disable
      Since:
        3.4
      See Also:
        `TRUE_CHUNK_LISTENER`

    - #### generateCommandID

          protected java.lang.String generateCommandID()

      Generates a new command ID (tag) for a command.
      Returns:
        a new command ID (tag) for an IMAP command.