/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.net.pop3;

import java.io.IOException;
import java.io.Reader;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ListIterator;
import java.util.StringTokenizer;

import org.apache.commons.net.io.DotTerminatedMessageReader;

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/***
 * 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.
 * <p>
 * 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
 * {@link org.apache.commons.net.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 POP3MessageInfo
 * @see org.apache.commons.net.io.DotTerminatedMessageReader
 * @see org.apache.commons.net.MalformedServerReplyException
 ***/

public class POP3Client extends POP3
{

    private static POP3MessageInfo __parseStatus(String line)
    {
        int num, size;
        StringTokenizer tokenizer;

        tokenizer = new StringTokenizer(line);

        if (!tokenizer.hasMoreElements()) {
            return null;
        }

        num = size = 0;

        try
        {
            num = Integer.parseInt(tokenizer.nextToken());

            if (!tokenizer.hasMoreElements()) {
                return null;
            }

            size = Integer.parseInt(tokenizer.nextToken());
        }
        catch (NumberFormatException e)
        {
            return null;
        }

        return new POP3MessageInfo(num, size);
    }

    private static POP3MessageInfo __parseUID(String line)
    {
        int num;
        StringTokenizer tokenizer;

        tokenizer = new StringTokenizer(line);

        if (!tokenizer.hasMoreElements()) {
            return null;
        }

        num = 0;

        try
        {
            num = Integer.parseInt(tokenizer.nextToken());

            if (!tokenizer.hasMoreElements()) {
                return null;
            }

            line = tokenizer.nextToken();
        }
        catch (NumberFormatException e)
        {
            return null;
        }

        return new POP3MessageInfo(num, line);
    }

    
Send a CAPA command to the POP3 server.
Throws:
IOException – If a network I/O error occurs in the process of
       sending the CAPA command.
Returns:
True if the command was successful, false if not.
Since:
3.1 (was previously in ExtendedPOP3Client)/***
     * Send a CAPA command to the POP3 server.
     * @return True if the command was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process of
     *        sending the CAPA command.
     * @since 3.1 (was previously in ExtendedPOP3Client)
     ***/
    public boolean capa() throws IOException
    {
        if (sendCommand(POP3Command.CAPA) == POP3Reply.OK) {
            getAdditionalReply();
            return true;
        }
        return false;

    }

    
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 . 
Params:
username –  The account name being logged in to.
password –  The plain text password of the account.
Throws:
IOException – If a network I/O error occurs in the process of
           logging in.
Returns:
True if the login attempt was successful, false if not./***
     * Login to the POP3 server with the given username and password.  You
     * must first connect to the server with
     * {@link org.apache.commons.net.SocketClient#connect  connect }
     * before attempting to login.  A login attempt is only valid if
     * the client is in the
     * {@link org.apache.commons.net.pop3.POP3#AUTHORIZATION_STATE AUTHORIZATION_STATE }
     * .  After logging in, the client enters the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * .
     *
     * @param username  The account name being logged in to.
     * @param password  The plain text password of the account.
     * @return True if the login attempt was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process of
     *            logging in.
     ***/
    public boolean login(String username, String password) throws IOException
    {
        if (getState() != AUTHORIZATION_STATE) {
            return false;
        }

        if (sendCommand(POP3Command.USER, username) != POP3Reply.OK) {
            return false;
        }

        if (sendCommand(POP3Command.PASS, password) != POP3Reply.OK) {
            return false;
        }

        setState(TRANSACTION_STATE);

        return true;
    }


    
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. 
Params:
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.
Throws:
IOException – If a network I/O error occurs in the process of
           logging in.
NoSuchAlgorithmException – If the MD5 encryption algorithm
     cannot be instantiated by the Java runtime system.
Returns:
True if the login attempt was successful, false if not./***
     * 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
     * {@link org.apache.commons.net.pop3.POP3#getReplyString getReplyString }
     *  and parse out the timestamp information yourself.
     * <p>
     * You must first connect to the server with
     * {@link org.apache.commons.net.SocketClient#connect  connect }
     * before attempting to login.  A login attempt is only valid if
     * the client is in the
     * {@link org.apache.commons.net.pop3.POP3#AUTHORIZATION_STATE AUTHORIZATION_STATE }
     * .  After logging in, the client enters the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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.
     *
     * @param username  The account name being logged in to.
     * @param timestamp  The timestamp string to combine with the secret.
     * @param secret  The shared secret which produces the MD5 digest when
     *        combined with the timestamp.
     * @return True if the login attempt was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process of
     *            logging in.
     * @throws NoSuchAlgorithmException If the MD5 encryption algorithm
     *      cannot be instantiated by the Java runtime system.
     ***/
    public boolean login(String username, String timestamp, String secret)
    throws IOException, NoSuchAlgorithmException
    {
        int i;
        byte[] digest;
        StringBuilder buffer, digestBuffer;
        MessageDigest md5;

        if (getState() != AUTHORIZATION_STATE) {
            return false;
        }

        md5 = MessageDigest.getInstance("MD5");
        timestamp += secret;
        digest = md5.digest(timestamp.getBytes(getCharset()));
        digestBuffer = new StringBuilder(128);

        for (i = 0; i < digest.length; i++) {
            int digit = digest[i] & 0xff;
            if (digit <= 15) { // Add leading zero if necessary (NET-351)
                digestBuffer.append("0");
            }
            digestBuffer.append(Integer.toHexString(digit));
        }

        buffer = new StringBuilder(256);
        buffer.append(username);
        buffer.append(' ');
        buffer.append(digestBuffer.toString());

        if (sendCommand(POP3Command.APOP, buffer.toString()) != POP3Reply.OK) {
            return false;
        }

        setState(TRANSACTION_STATE);

        return true;
    }


    
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. 
Throws:
IOException – If a network I/O error occurs in the process
          of logging out.
Returns:
True if the logout attempt was successful, false if not./***
     * Logout of the POP3 server.  To fully disconnect from the server
     * you must call
     * {@link org.apache.commons.net.pop3.POP3#disconnect  disconnect }.
     * A logout attempt is valid in any state.  If
     * the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * , it enters the
     * {@link org.apache.commons.net.pop3.POP3#UPDATE_STATE UPDATE_STATE }
     *  on a successful logout.
     *
     * @return True if the logout attempt was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process
     *           of logging out.
     ***/
    public boolean logout() throws IOException
    {
        if (getState() == TRANSACTION_STATE) {
            setState(UPDATE_STATE);
        }
        sendCommand(POP3Command.QUIT);
        return (_replyCode == POP3Reply.OK);
    }


    
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 . 
Throws:
IOException – If a network I/O error occurs in the process of
       sending the NOOP command.
Returns:
True if the noop attempt was successful, false if not./***
     * 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
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * .
     *
     * @return True if the noop attempt was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process of
     *        sending the NOOP command.
     ***/
    public boolean noop() throws IOException
    {
        if (getState() == TRANSACTION_STATE) {
            return (sendCommand(POP3Command.NOOP) == POP3Reply.OK);
        }
        return false;
    }


    
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 . 
Params:
messageId –  The message number to delete.
Throws:
IOException – If a network I/O error occurs in the process of
          sending the delete command.
Returns:
True if the deletion attempt was successful, false if not./***
     * 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 {@link #reset  reset } command.  Messages marked
     * for deletion are only deleted by the server on
     * {@link #logout  logout }.
     * A delete attempt can only succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * .
     *
     * @param messageId  The message number to delete.
     * @return True if the deletion attempt was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process of
     *           sending the delete command.
     ***/
    public boolean deleteMessage(int messageId) throws IOException
    {
        if (getState() == TRANSACTION_STATE) {
            return (sendCommand(POP3Command.DELE, Integer.toString(messageId))
                    == POP3Reply.OK);
        }
        return false;
    }


    
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 . 
Throws:
IOException – If a network I/O error occurs in the process of
     sending the reset command.
Returns:
True if the reset attempt was successful, false if not./***
     * 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
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * .
     *
     * @return True if the reset attempt was successful, false if not.
     * @throws IOException If a network I/O error occurs in the process of
     *      sending the reset command.
     ***/
    public boolean reset() throws IOException
    {
        if (getState() == TRANSACTION_STATE) {
            return (sendCommand(POP3Command.RSET) == POP3Reply.OK);
        }
        return false;
    }

    
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. 
Throws:
IOException – If a network I/O error occurs in the process of
      sending the status command.
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./***
     * Get the mailbox status.  A status attempt can only
     * succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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.
     *
     * @return 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 IOException If a network I/O error occurs in the process of
     *       sending the status command.
     ***/
    public POP3MessageInfo status() throws IOException
    {
        if (getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.STAT) != POP3Reply.OK) {
            return null;
        }
        return __parseStatus(_lastReplyLine.substring(3));
    }


    
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). 
Params:
messageId –  The number of the message list.
Throws:
IOException – If a network I/O error occurs in the process of
        sending the list command.
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./***
     * List an individual message.  A list attempt can only
     * succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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).
     *
     * @param messageId  The number of the message list.
     * @return 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 IOException If a network I/O error occurs in the process of
     *         sending the list command.
     ***/
    public POP3MessageInfo listMessage(int messageId) throws IOException
    {
        if (getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.LIST, Integer.toString(messageId))
                != POP3Reply.OK) {
            return null;
        }
        return __parseStatus(_lastReplyLine.substring(3));
    }


    
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. 
Throws:
IOException – If a network I/O error occurs in the process of
    sending the list command.
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./***
     * List all messages.  A list attempt can only
     * succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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.
     *
     * @return 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 IOException If a network I/O error occurs in the process of
     *     sending the list command.
     ***/
    public POP3MessageInfo[] listMessages() throws IOException
    {
        if (getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.LIST) != POP3Reply.OK) {
            return null;
        }
        getAdditionalReply();

        // This could be a zero length array if no messages present
        POP3MessageInfo[] messages = new POP3MessageInfo[_replyLines.size() - 2]; // skip first and last lines

        ListIterator<String> en = _replyLines.listIterator(1); // Skip first line

        // Fetch lines.
        for (int line = 0; line < messages.length; line++) {
            messages[line] = __parseStatus(en.next());
        }

        return messages;
    }

    
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). 
Params:
messageId –  The number of the message list.
Throws:
IOException – If a network I/O error occurs in the process of
       sending the list unique identifier command.
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./***
     * List the unique identifier for a message.  A list attempt can only
     * succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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).
     *
     * @param messageId  The number of the message list.
     * @return 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 IOException If a network I/O error occurs in the process of
     *        sending the list unique identifier command.
     ***/
    public POP3MessageInfo listUniqueIdentifier(int messageId)
    throws IOException
    {
        if (getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.UIDL, Integer.toString(messageId))
                != POP3Reply.OK) {
            return null;
        }
        return __parseUID(_lastReplyLine.substring(3));
    }


    
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. 
Throws:
IOException – If a network I/O error occurs in the process of
    sending the list unique identifier command.
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./***
     * List the unique identifiers for all messages.  A list attempt can only
     * succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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.
     *
     * @return 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 IOException If a network I/O error occurs in the process of
     *     sending the list unique identifier command.
     ***/
    public POP3MessageInfo[] listUniqueIdentifiers() throws IOException
    {
        if (getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.UIDL) != POP3Reply.OK) {
            return null;
        }
        getAdditionalReply();

        // This could be a zero length array if no messages present
        POP3MessageInfo[] messages = new POP3MessageInfo[_replyLines.size() - 2]; // skip first and last lines

        ListIterator<String> en = _replyLines.listIterator(1); // skip first line

        // Fetch lines.
        for (int line = 0; line < messages.length; line++) {
            messages[line] = __parseUID(en.next());
        }

        return messages;
    }


    
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.
Params:
messageId –  The number of the message to fetch.
Throws:
IOException – If a network I/O error occurs in the process of
       sending the retrieve message command.
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)./**
     * Retrieve a message from the POP3 server.  A retrieve message attempt
     * can only succeed if the client is in the
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * <p>
     * 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.
     *
     * @param messageId  The number of the message to fetch.
     * @return A DotTerminatedMessageReader instance
     * from which the entire message can be read.
     * This can safely be cast to a {@link java.io.BufferedReader BufferedReader} in order to
     * use the {@link java.io.BufferedReader#readLine() BufferedReader#readLine()} method.
     * Returns null if the retrieval attempt fails  (e.g., if the specified
     * message number does not exist).
     * @throws IOException If a network I/O error occurs in the process of
     *        sending the retrieve message command.
     */
    public Reader retrieveMessage(int messageId) throws IOException
    {
        if (getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.RETR, Integer.toString(messageId)) != POP3Reply.OK) {
            return null;
        }

        return new DotTerminatedMessageReader(_reader);
    }


    
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.
Params:
messageId –  The number of the message to fetch.
numLines –  The top number of lines to fetch. This must be >= 0.
Throws:
IOException – If a network I/O error occurs in the process of
      sending the top command.
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)./**
     * 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
     * {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE TRANSACTION_STATE }
     * <p>
     * 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.
     *
     * @param messageId  The number of the message to fetch.
     * @param numLines  The top number of lines to fetch. This must be &gt;= 0.
     * @return  A DotTerminatedMessageReader instance
     * from which the specified top number of lines of the message can be
     * read.
     * This can safely be cast to a {@link java.io.BufferedReader BufferedReader} in order to
     * use the {@link java.io.BufferedReader#readLine() BufferedReader#readLine()} method.
     * Returns null if the retrieval attempt fails  (e.g., if the specified
     * message number does not exist).
     * @throws IOException If a network I/O error occurs in the process of
     *       sending the top command.
     */
    public Reader retrieveMessageTop(int messageId, int numLines)
    throws IOException
    {
        if (numLines < 0 || getState() != TRANSACTION_STATE) {
            return null;
        }
        if (sendCommand(POP3Command.TOP, Integer.toString(messageId) + " " +
                        Integer.toString(numLines)) != POP3Reply.OK) {
            return null;
        }

        return new DotTerminatedMessageReader(_reader);
    }


}