org.apache.commons.net.pop3.POP3Client Maven / Gradle / Ivy
Show all versions of commons-net Show documentation
/*
* 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
* {@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.
* @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
* {@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
* {@link org.apache.commons.net.pop3.POP3#getReplyString getReplyString }
* and parse out the timestamp information yourself.
*
* 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
* {@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
* {@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 {@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
* {@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
* {@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
* {@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
* {@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 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
* {@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
* {@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 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
* {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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.
*
* @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
* {@link org.apache.commons.net.pop3.POP3#TRANSACTION_STATE 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.
*
* @param messageId The number of the message to fetch.
* @param numLines The top number of lines to fetch. This must be >= 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);
}
}