POP3Client
Date: 2016-06-23

org.apache.commons.net.pop3

## Class POP3Client

- java.lang.Object
- - org.apache.commons.net.SocketClient
  - - org.apache.commons.net.pop3.POP3
    - - org.apache.commons.net.pop3.POP3Client

- Direct Known Subclasses:
    POP3SClient

      public class POP3Client
      extends POP3

  The POP3Client class implements the client side of the Internet POP3 Protocol defined in RFC 1939. All commands are supported, including the APOP command which requires MD5 encryption. See RFC 1939 for more details on the POP3 protocol.

  Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a `MalformedServerReplyException` , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as lenient as possible.

  See Also:
    `POP3MessageInfo`, `DotTerminatedMessageReader`, `MalformedServerReplyException`

- - ### Field Summary

    - ### Fields inherited from class org.apache.commons.net.pop3.POP3

      `_commandSupport_, AUTHORIZATION_STATE, DEFAULT_PORT, DISCONNECTED_STATE, TRANSACTION_STATE, UPDATE_STATE`

    - ### 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
    `POP3Client()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `capa()` Send a CAPA command to the POP3 server.
    `boolean` | `deleteMessage(int messageId)` Delete a message from the POP3 server.
    `POP3MessageInfo` | `listMessage(int messageId)` List an individual message.
    `POP3MessageInfo[]` | `listMessages()` List all messages.
    `POP3MessageInfo` | `listUniqueIdentifier(int messageId)` List the unique identifier for a message.
    `POP3MessageInfo[]` | `listUniqueIdentifiers()` List the unique identifiers for all messages.
    `boolean` | `login(java.lang.String username, java.lang.String password)` Login to the POP3 server with the given username and password.
    `boolean` | `login(java.lang.String username, java.lang.String timestamp, java.lang.String secret)` Login to the POP3 server with the given username and authentication information.
    `boolean` | `logout()` Logout of the POP3 server.
    `boolean` | `noop()` Send a NOOP command to the POP3 server.
    `boolean` | `reset()` Reset the POP3 session.
    `java.io.Reader` | `retrieveMessage(int messageId)` Retrieve a message from the POP3 server.
    `java.io.Reader` | `retrieveMessageTop(int messageId, int numLines)` Retrieve only the specified top number of lines of a message from the POP3 server.
    `POP3MessageInfo` | `status()` Get the mailbox status.

    - ### Methods inherited from class org.apache.commons.net.pop3.POP3

      `_connectAction_, disconnect, getAdditionalReply, getCommandSupport, getReplyString, getReplyStrings, getState, removeProtocolCommandistener, sendCommand, sendCommand, sendCommand, sendCommand, setState`

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

      `addProtocolCommandListener, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCharset, getCharsetName, 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`

- - ### Constructor Detail

    - #### POP3Client

          public POP3Client()

  - ### Method Detail

    - #### capa

          public boolean capa()
                       throws java.io.IOException

      Send a CAPA command to the POP3 server.
      Returns:
        True if the command was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the CAPA command.
      Since:
        3.1 (was previously in ExtendedPOP3Client)

    - #### login

          public boolean login(java.lang.String username,
                      java.lang.String password)
                        throws java.io.IOException

      Login to the POP3 server with the given username and password. You must first connect to the server with `connect` before attempting to login. A login attempt is only valid if the client is in the `AUTHORIZATION_STATE` . After logging in, the client enters the `TRANSACTION_STATE` .
      Parameters:
        `username` - The account name being logged in to.
        `password` - The plain text password of the account.
      Returns:
        True if the login attempt was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of logging in.

    - #### login

          public boolean login(java.lang.String username,
                      java.lang.String timestamp,
                      java.lang.String secret)
                        throws java.io.IOException,
                               java.security.NoSuchAlgorithmException

      Login to the POP3 server with the given username and authentication information. Use this method when connecting to a server requiring authentication using the APOP command. Because the timestamp produced in the greeting banner varies from server to server, it is not possible to consistently extract the information. Therefore, after connecting to the server, you must call `getReplyString` and parse out the timestamp information yourself.

      You must first connect to the server with `connect` before attempting to login. A login attempt is only valid if the client is in the `AUTHORIZATION_STATE` . After logging in, the client enters the `TRANSACTION_STATE` . After connecting, you must parse out the server specific information to use as a timestamp, and pass that information to this method. The secret is a shared secret known to you and the server. See RFC 1939 for more details regarding the APOP command.

      Parameters:
        `username` - The account name being logged in to.
        `timestamp` - The timestamp string to combine with the secret.
        `secret` - The shared secret which produces the MD5 digest when combined with the timestamp.
      Returns:
        True if the login attempt was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of logging in.
        `java.security.NoSuchAlgorithmException` - If the MD5 encryption algorithm cannot be instantiated by the Java runtime system.

    - #### logout

          public boolean logout()
                         throws java.io.IOException

      Logout of the POP3 server. To fully disconnect from the server you must call `disconnect` . A logout attempt is valid in any state. If the client is in the `TRANSACTION_STATE` , it enters the `UPDATE_STATE` on a successful logout.
      Returns:
        True if the logout attempt was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of logging out.

    - #### noop

          public boolean noop()
                       throws java.io.IOException

      Send a NOOP command to the POP3 server. This is useful for keeping a connection alive since most POP3 servers will timeout after 10 minutes of inactivity. A noop attempt will only succeed if the client is in the `TRANSACTION_STATE` .
      Returns:
        True if the noop attempt was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the NOOP command.

    - #### deleteMessage

          public boolean deleteMessage(int messageId)
                                throws java.io.IOException

      Delete a message from the POP3 server. The message is only marked for deletion by the server. If you decide to unmark the message, you must issuse a `reset` command. Messages marked for deletion are only deleted by the server on `logout` . A delete attempt can only succeed if the client is in the `TRANSACTION_STATE` .
      Parameters:
        `messageId` - The message number to delete.
      Returns:
        True if the deletion attempt was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the delete command.

    - #### reset

          public boolean reset()
                        throws java.io.IOException

      Reset the POP3 session. This is useful for undoing any message deletions that may have been performed. A reset attempt can only succeed if the client is in the `TRANSACTION_STATE` .
      Returns:
        True if the reset attempt was successful, false if not.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the reset command.

    - #### status

          public POP3MessageInfo status()
                                 throws java.io.IOException

      Get the mailbox status. A status attempt can only succeed if the client is in the `TRANSACTION_STATE` . Returns a POP3MessageInfo instance containing the number of messages in the mailbox and the total size of the messages in bytes. Returns null if the status the attempt fails.
      Returns:
        A POP3MessageInfo instance containing the number of messages in the mailbox and the total size of the messages in bytes. Returns null if the status the attempt fails.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the status command.

    - #### listMessage

          public POP3MessageInfo listMessage(int messageId)
                                      throws java.io.IOException

      List an individual message. A list attempt can only succeed if the client is in the `TRANSACTION_STATE` . Returns a POP3MessageInfo instance containing the number of the listed message and the size of the message in bytes. Returns null if the list attempt fails (e.g., if the specified message number does not exist).
      Parameters:
        `messageId` - The number of the message list.
      Returns:
        A POP3MessageInfo instance containing the number of the listed message and the size of the message in bytes. Returns null if the list attempt fails.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the list command.

    - #### listMessages

          public POP3MessageInfo[] listMessages()
                                         throws java.io.IOException

      List all messages. A list attempt can only succeed if the client is in the `TRANSACTION_STATE` . Returns an array of POP3MessageInfo instances, each containing the number of a message and its size in bytes. If there are no messages, this method returns a zero length array. If the list attempt fails, it returns null.
      Returns:
        An array of POP3MessageInfo instances representing all messages in the order they appear in the mailbox, each containing the number of a message and its size in bytes. If there are no messages, this method returns a zero length array. If the list attempt fails, it returns null.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the list command.

    - #### listUniqueIdentifier

          public POP3MessageInfo listUniqueIdentifier(int messageId)
                                               throws java.io.IOException

      List the unique identifier for a message. A list attempt can only succeed if the client is in the `TRANSACTION_STATE` . Returns a POP3MessageInfo instance containing the number of the listed message and the unique identifier for that message. Returns null if the list attempt fails (e.g., if the specified message number does not exist).
      Parameters:
        `messageId` - The number of the message list.
      Returns:
        A POP3MessageInfo instance containing the number of the listed message and the unique identifier for that message. Returns null if the list attempt fails.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the list unique identifier command.

    - #### listUniqueIdentifiers

          public POP3MessageInfo[] listUniqueIdentifiers()
                                                  throws java.io.IOException

      List the unique identifiers for all messages. A list attempt can only succeed if the client is in the `TRANSACTION_STATE` . Returns an array of POP3MessageInfo instances, each containing the number of a message and its unique identifier. If there are no messages, this method returns a zero length array. If the list attempt fails, it returns null.
      Returns:
        An array of POP3MessageInfo instances representing all messages in the order they appear in the mailbox, each containing the number of a message and its unique identifier If there are no messages, this method returns a zero length array. If the list attempt fails, it returns null.
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the list unique identifier command.

    - #### retrieveMessage

          public java.io.Reader retrieveMessage(int messageId)
                                         throws java.io.IOException

      Retrieve a message from the POP3 server. A retrieve message attempt can only succeed if the client is in the `TRANSACTION_STATE`

      You must not issue any commands to the POP3 server (i.e., call any other methods) until you finish reading the message from the returned BufferedReader instance. The POP3 protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader actually reads directly from the POP3 connection. After the end of message has been reached, new commands can be executed and their replies read. If you do not follow these requirements, your program will not work properly.

      Parameters:
        `messageId` - The number of the message to fetch.
      Returns:
        A DotTerminatedMessageReader instance from which the entire message can be read. This can safely be cast to a `BufferedReader` in order to use the `BufferedReader#readLine()` method. Returns null if the retrieval attempt fails (e.g., if the specified message number does not exist).
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the retrieve message command.

    - #### retrieveMessageTop

          public java.io.Reader retrieveMessageTop(int messageId,
                                          int numLines)
                                            throws java.io.IOException

      Retrieve only the specified top number of lines of a message from the POP3 server. A retrieve top lines attempt can only succeed if the client is in the `TRANSACTION_STATE`

      You must not issue any commands to the POP3 server (i.e., call any other methods) until you finish reading the message from the returned BufferedReader instance. The POP3 protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader actually reads directly from the POP3 connection. After the end of message has been reached, new commands can be executed and their replies read. If you do not follow these requirements, your program will not work properly.

      Parameters:
        `messageId` - The number of the message to fetch.
        `numLines` - The top number of lines to fetch. This must be >= 0.
      Returns:
        A DotTerminatedMessageReader instance from which the specified top number of lines of the message can be read. This can safely be cast to a `BufferedReader` in order to use the `BufferedReader#readLine()` method. Returns null if the retrieval attempt fails (e.g., if the specified message number does not exist).
      Throws:
        `java.io.IOException` - If a network I/O error occurs in the process of sending the top command.