gnu.inet.pop3

Class POP3Connection


public class POP3Connection
extends java.lang.Object

A POP3 client connection. This implements the entire POP3 specification as detailed in RFC 1939, with the exception of the no-arg LIST and UIDL commands (use STAT followed by multiple LIST and/or UIDL instead) and TOP with a specified number of content lines. It also implements the POP3 extension mechanism CAPA, documented in RFC 2449, as well as the STLS command to initiate TLS over POP3 documented in RFC 2595 and the AUTH command in RFC 1734.

Field Summary

protected static String
APOP
protected static String
AUTH
protected static String
CAPA
static int
DEFAULT_PORT
The default POP3 port.
protected static String
DELE
protected static int
ERR
protected static String
LIST
protected static String
NOOP
protected static int
OK
protected static String
PASS
static Level
POP3_TRACE
The network trace level.
protected static String
QUIT
protected static int
READY
protected static String
RETR
protected static String
RSET
protected static String
STAT
protected static String
STLS
protected static String
TOP
protected static String
UIDL
protected static String
USER
protected LineInputStream
in
The socket input stream.
Logger
logger
The logger used for POP3 protocol traces.
protected CRLFOutputStream
out
The socket output stream.
protected String
response
The last response received from the server.
protected Socket
socket
The socket used to communicate with the server.
protected byte[]
timestamp
The APOP timestamp, if sent by the server on connection.

Constructor Summary

POP3Connection(String hostname)
Creates a new connection to the server.
POP3Connection(String hostname, int port)
Creates a new connection to the server.
POP3Connection(String hostname, int port, int connectionTimeout, int timeout)
Creates a new connection to the server.
POP3Connection(String hostname, int port, int connectionTimeout, int timeout, boolean secure, TrustManager tm)
Creates a new connection to the server.
POP3Connection(String hostname, int port, int connectionTimeout, int timeout, boolean secure, TrustManager tm, boolean init)
Creates a new connection to the server.

Method Summary

boolean
apop(String username, String password)
Authenticate the specified user using the APOP MD5-based method.
boolean
auth(String mechanism, String username, String password)
Authenticates the connection using the specified SASL mechanism, username, and password.
List
capa()
Returns a list of capabilities supported by the POP3 server.
void
dele(int msgnum)
Marks the specified message as deleted.
protected int
getResponse()
Parse the response from the server.
protected SSLSocketFactory
getSSLSocketFactory(TrustManager tm)
Returns a configured SSLSocketFactory to use in creating new SSL sockets.
void
init()
Initialises the connection.
int
list(int msgnum)
Returns the size of the specified message.
boolean
login(String username, String password)
Authenticate the user using the basic USER and PASS handshake.
void
noop()
Does nothing.
boolean
quit()
Closes the connection.
InputStream
retr(int msgnum)
Returns an input stream containing the entire message.
void
rset()
If any messages have been marked as deleted, they are unmarked.
protected void
send(String command)
Send the command to the server.
int
stat()
Returns the number of messages in the maildrop.
boolean
stls()
Attempts to start TLS on the specified connection.
boolean
stls(TrustManager tm)
Attempts to start TLS on the specified connection.
InputStream
top(int msgnum)
Returns just the headers of the specified message as an input stream.
Map
uidl()
Returns a map of message number to UID pairs.
String
uidl(int msgnum)
Returns a unique identifier for the specified message.

Field Details

APOP

protected static final String APOP

AUTH

protected static final String AUTH

CAPA

protected static final String CAPA

DEFAULT_PORT

public static final int DEFAULT_PORT
The default POP3 port.
Field Value:
110

DELE

protected static final String DELE

ERR

protected static final int ERR
Field Value:
1

LIST

protected static final String LIST

NOOP

protected static final String NOOP

OK

protected static final int OK
Field Value:
0

PASS

protected static final String PASS

POP3_TRACE

public static final Level POP3_TRACE
The network trace level.

QUIT

protected static final String QUIT

READY

protected static final int READY
Field Value:
2

RETR

protected static final String RETR

RSET

protected static final String RSET

STAT

protected static final String STAT

STLS

protected static final String STLS

TOP

protected static final String TOP

UIDL

protected static final String UIDL

USER

protected static final String USER

in

protected LineInputStream in
The socket input stream.

logger

public final Logger logger
The logger used for POP3 protocol traces.

out

protected CRLFOutputStream out
The socket output stream.

response

protected String response
The last response received from the server. The status code (+OK or -ERR) is stripped from the line.

socket

protected Socket socket
The socket used to communicate with the server.

timestamp

protected byte[] timestamp
The APOP timestamp, if sent by the server on connection. Otherwise null.

Constructor Details

POP3Connection

public POP3Connection(String hostname)
            throws UnknownHostException,
                   IOException
Creates a new connection to the server.
Parameters:
hostname - the hostname of the server to connect to

POP3Connection

public POP3Connection(String hostname,
                      int port)
            throws UnknownHostException,
                   IOException
Creates a new connection to the server.
Parameters:
hostname - the hostname of the server to connect to
port - the port to connect to(if <=0, use default POP3 port)

POP3Connection

public POP3Connection(String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout)
            throws UnknownHostException,
                   IOException
Creates a new connection to the server.
Parameters:
hostname - the hostname of the server to connect to
port - the port to connect to(if <=0, use default POP3 port)
connectionTimeout - the connection timeout, in milliseconds
timeout - the I/O timeout, in milliseconds

POP3Connection

public POP3Connection(String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      TrustManager tm)
            throws UnknownHostException,
                   IOException
Creates a new connection to the server.
Parameters:
hostname - the hostname of the server to connect to
port - the port to connect to(if <=0, use default POP3 port)
connectionTimeout - the connection timeout, in milliseconds
timeout - the I/O timeout, in milliseconds
secure - if true, create a POP3S connection
tm - a trust manager used to check SSL certificates, or null to use the default

POP3Connection

public POP3Connection(String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      TrustManager tm,
                      boolean init)
            throws UnknownHostException,
                   IOException
Creates a new connection to the server.
Parameters:
hostname - the hostname of the server to connect to
port - the port to connect to(if <=0, use default POP3 port)
connectionTimeout - the connection timeout, in milliseconds
timeout - the I/O timeout, in milliseconds
secure - if true, create a POP3S connection
tm - a trust manager used to check SSL certificates, or null to use the default
init - initialise the connection

Method Details

apop

public boolean apop(String username,
                    String password)
            throws IOException
Authenticate the specified user using the APOP MD5-based method. This does not transmit the password in the clear, but doesn't provide any transport-level privacy features either.
Parameters:
username - the user to authenticate
password - the user's password

auth

public boolean auth(String mechanism,
                    String username,
                    String password)
            throws IOException
Authenticates the connection using the specified SASL mechanism, username, and password.
Parameters:
mechanism - a SASL authentication mechanism, e.g. LOGIN, PLAIN, CRAM-MD5, GSSAPI
username - the authentication principal
password - the authentication credentials
Returns:
true if authentication was successful, false otherwise

capa

public List capa()
            throws IOException
Returns a list of capabilities supported by the POP3 server. If the server does not support POP3 extensions, returns null.

dele

public void dele(int msgnum)
            throws IOException
Marks the specified message as deleted.
Parameters:
msgnum - the message number

getResponse

protected int getResponse()
            throws IOException
Parse the response from the server.

getSSLSocketFactory

protected SSLSocketFactory getSSLSocketFactory(TrustManager tm)
            throws GeneralSecurityException
Returns a configured SSLSocketFactory to use in creating new SSL sockets.
Parameters:
tm - an optional trust manager to use

init

public void init()
            throws IOException
Initialises the connection. Unless the init parameter was provided with the value false, do not call this method. Otherwise call it only once after e.g. configuring logging.

list

public int list(int msgnum)
            throws IOException
Returns the size of the specified message.
Parameters:
msgnum - the message number

login

public boolean login(String username,
                     String password)
            throws IOException
Authenticate the user using the basic USER and PASS handshake. It is recommended to use a more secure authentication method such as the auth or apop method if the server understands them.
Parameters:
username - the user to authenticate
password - the user's password

noop

public void noop()
            throws IOException
Does nothing. This can be used to keep the connection alive.

quit

public boolean quit()
            throws IOException
Closes the connection. No further commands may be issued on this connection after this method has been called.
Returns:
true if all deleted messages were successfully removed, false otherwise

retr

public InputStream retr(int msgnum)
            throws IOException
Returns an input stream containing the entire message. This input stream must be read in its entirety before further commands can be issued on this connection.
Parameters:
msgnum - the message number

rset

public void rset()
            throws IOException
If any messages have been marked as deleted, they are unmarked.

send

protected void send(String command)
            throws IOException
Send the command to the server.

stat

public int stat()
            throws IOException
Returns the number of messages in the maildrop.

stls

public boolean stls()
            throws IOException
Attempts to start TLS on the specified connection. See RFC 2595 for details
Returns:
true if successful, false otherwise

stls

public boolean stls(TrustManager tm)
            throws IOException
Attempts to start TLS on the specified connection. See RFC 2595 for details
Parameters:
tm - the custom trust manager to use
Returns:
true if successful, false otherwise

top

public InputStream top(int msgnum)
            throws IOException
Returns just the headers of the specified message as an input stream. The stream must be read in its entirety before further commands can be issued.
Parameters:
msgnum - the message number

uidl

public Map uidl()
            throws IOException
Returns a map of message number to UID pairs. Message numbers are Integers, UIDs are Strings.

uidl

public String uidl(int msgnum)
            throws IOException
Returns a unique identifier for the specified message.
Parameters:
msgnum - the message number