gnu.inet.pop3

Class POP3Connection

java.lang.Object

gnu.inet.pop3.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

Fields

Modifier and Type	Field and Description
protected static java.lang.String	APOP
protected static java.lang.String	AUTH
protected static java.lang.String	CAPA
static int	DEFAULT_PORT The default POP3 port.
static int	DEFAULT_SSL_PORT The default POP3S port.
protected static java.lang.String	DELE
protected static int	ERR
protected static java.lang.String	LIST
protected static java.lang.String	NOOP
protected static int	OK
protected static java.lang.String	PASS
static java.util.logging.Level	POP3_TRACE The network trace level.
protected static java.lang.String	QUIT
protected static int	READY
protected static java.lang.String	RETR
protected static java.lang.String	RSET
protected static java.lang.String	STAT
protected static java.lang.String	STLS
protected static java.lang.String	TOP
protected static java.lang.String	UIDL
protected static java.lang.String	USER

Constructor Summary

Constructors

Constructor and Description
POP3Connection(java.lang.String hostname) Creates a new connection to the server.
POP3Connection(java.lang.String hostname, int port) Creates a new connection to the server.
POP3Connection(java.lang.String hostname, int port, int connectionTimeout, int timeout) Creates a new connection to the server.
POP3Connection(java.lang.String hostname, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm) Creates a new connection to the server.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	apop(java.lang.String username, java.lang.String password) Authenticate the specified user using the APOP MD5-based method.
boolean	auth(java.lang.String mechanism, java.lang.String username, java.lang.String password) Authenticates the connection using the specified SASL mechanism, username, and password.
java.util.List<java.lang.String>	capa() Returns a list of capabilities supported by the POP3 server.
void	dele(int msgnum) Marks the specified message as deleted.
java.util.logging.Logger	getLogger() Returns the logger used by this connection for debug output.
protected int	getResponse() Parse the response from the server.
protected javax.net.ssl.SSLSocketFactory	getSSLSocketFactory(javax.net.ssl.TrustManager tm) Returns a configured SSLSocketFactory to use in creating new SSL sockets.
int	list(int msgnum) Returns the size of the specified message.
boolean	login(java.lang.String username, java.lang.String password) Authenticate the user using the basic USER and PASS handshake.
void	noop() Does nothing.
boolean	quit() Closes the connection.
java.io.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(java.lang.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(javax.net.ssl.TrustManager tm) Attempts to start TLS on the specified connection.
java.io.InputStream	top(int msgnum) Returns just the headers of the specified message as an input stream.
java.util.Map<java.lang.Integer,java.lang.String>	uidl() Returns a map of message number to UID pairs.
java.lang.String	uidl(int msgnum) Returns a unique identifier for the specified message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POP3_TRACE

public static final java.util.logging.Level POP3_TRACE

The network trace level.

DEFAULT_PORT

public static final int DEFAULT_PORT

The default POP3 port.

See Also:

Constant Field Values

DEFAULT_SSL_PORT

public static final int DEFAULT_SSL_PORT

The default POP3S port.

See Also:

Constant Field Values

STAT

protected static final java.lang.String STAT

See Also:

Constant Field Values

LIST

protected static final java.lang.String LIST

See Also:

Constant Field Values

RETR

protected static final java.lang.String RETR

See Also:

Constant Field Values

DELE

protected static final java.lang.String DELE

See Also:

Constant Field Values

NOOP

protected static final java.lang.String NOOP

See Also:

Constant Field Values

RSET

protected static final java.lang.String RSET

See Also:

Constant Field Values

QUIT

protected static final java.lang.String QUIT

See Also:

Constant Field Values

TOP

protected static final java.lang.String TOP

See Also:

Constant Field Values

UIDL

protected static final java.lang.String UIDL

See Also:

Constant Field Values

USER

protected static final java.lang.String USER

See Also:

Constant Field Values

PASS

protected static final java.lang.String PASS

See Also:

Constant Field Values

APOP

protected static final java.lang.String APOP

See Also:

Constant Field Values

CAPA

protected static final java.lang.String CAPA

See Also:

Constant Field Values

STLS

protected static final java.lang.String STLS

See Also:

Constant Field Values

AUTH

protected static final java.lang.String AUTH

See Also:

Constant Field Values

OK

protected static final int OK

See Also:

Constant Field Values

ERR

protected static final int ERR

See Also:

Constant Field Values

READY

protected static final int READY

See Also:

Constant Field Values

Constructor Detail

POP3Connection

public POP3Connection(java.lang.String hostname)

Creates a new connection to the server.

Parameters:

hostname - the hostname of the server to connect to

POP3Connection

public POP3Connection(java.lang.String hostname,
              int port)

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(java.lang.String hostname,
              int port,
              int connectionTimeout,
              int timeout)

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(java.lang.String hostname,
              int port,
              int connectionTimeout,
              int timeout,
              boolean secure,
              javax.net.ssl.TrustManager tm)

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

Method Detail

getLogger

public java.util.logging.Logger getLogger()

Returns the logger used by this connection for debug output.

auth

public boolean auth(java.lang.String mechanism,
           java.lang.String username,
           java.lang.String password)
             throws java.io.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

Throws:

java.io.IOException

apop

public boolean apop(java.lang.String username,
           java.lang.String password)
             throws java.io.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

Throws:

java.io.IOException

login

public boolean login(java.lang.String username,
            java.lang.String password)
              throws java.io.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

Throws:

java.io.IOException

getSSLSocketFactory

protected javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
                                                      throws java.security.GeneralSecurityException

Returns a configured SSLSocketFactory to use in creating new SSL sockets.

Parameters:

tm - an optional trust manager to use

Throws:

java.security.GeneralSecurityException

stls

public boolean stls()
             throws java.io.IOException

Attempts to start TLS on the specified connection. See RFC 2595 for details

Returns:

true if successful, false otherwise

Throws:

java.io.IOException

stls

public boolean stls(javax.net.ssl.TrustManager tm)
             throws java.io.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

Throws:

java.io.IOException

stat

public int stat()
         throws java.io.IOException

Returns the number of messages in the maildrop.

Throws:

java.io.IOException

list

public int list(int msgnum)
         throws java.io.IOException

Returns the size of the specified message.

Parameters:

msgnum - the message number

Throws:

java.io.IOException

retr

public java.io.InputStream retr(int msgnum)
                         throws java.io.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

Throws:

java.io.IOException

dele

public void dele(int msgnum)
          throws java.io.IOException

Marks the specified message as deleted.

Parameters:

msgnum - the message number

Throws:

java.io.IOException

noop

public void noop()
          throws java.io.IOException

Does nothing. This can be used to keep the connection alive.

Throws:

java.io.IOException

rset

public void rset()
          throws java.io.IOException

If any messages have been marked as deleted, they are unmarked.

Throws:

java.io.IOException

quit

public boolean quit()
             throws java.io.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

Throws:

java.io.IOException

top

public java.io.InputStream top(int msgnum)
                        throws java.io.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

Throws:

java.io.IOException

uidl

public java.lang.String uidl(int msgnum)
                      throws java.io.IOException

Returns a unique identifier for the specified message.

Parameters:

msgnum - the message number

Throws:

java.io.IOException

uidl

public java.util.Map<java.lang.Integer,java.lang.String> uidl()
                                                       throws java.io.IOException

Returns a map of message number to UID pairs.

Throws:

java.io.IOException

capa

public java.util.List<java.lang.String> capa()
                                      throws java.io.IOException

Returns a list of capabilities supported by the POP3 server. If the server does not support POP3 extensions, returns null.

Throws:

java.io.IOException

send

protected void send(java.lang.String command)
             throws java.io.IOException

Send the command to the server.

Throws:

java.io.IOException

getResponse

protected int getResponse()
                   throws java.io.IOException

Parse the response from the server.

Throws:

java.io.IOException