org.apache.commons.net.pop3
public class POP3Client extends POP3
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
Method Summary | |
---|---|
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(String username, String password)
Login to the POP3 server with the given username and password. |
boolean | login(String username, String timestamp, 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. |
Reader | retrieveMessage(int messageId)
Retrieve a message from the POP3 server. |
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. |
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: IOException If a network I/O error occurs in the process of sending the delete command.
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: IOException If a network I/O error occurs in the process of sending the list command.
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: IOException If a network I/O error occurs in the process of sending the list command.
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: IOException If a network I/O error occurs in the process of sending the list unique identifier command.
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: IOException If a network I/O error occurs in the process of sending the list unique identifier command.
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: IOException If a network I/O error occurs in the process of logging in.
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: 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.
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: IOException If a network I/O error occurs in the process of logging out.
TRANSACTION_STATE
.
Returns: 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.
TRANSACTION_STATE
.
Returns: 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.
TRANSACTION_STATE
. Returns a DotTerminatedMessageReader instance
from which the entire message can be read.
Returns null if the retrieval attempt fails (e.g., if the specified
message number does not exist).
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 Reader instance. The POP3 protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned Reader 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. 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.
TRANSACTION_STATE
. Returns a DotTerminatedMessageReader instance
from which the specified top number of lines of the message can be
read.
Returns null if the retrieval attempt fails (e.g., if the specified
message number does not exist).
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 Reader instance. The POP3 protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned Reader 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. 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.
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: IOException If a network I/O error occurs in the process of sending the status command.