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.

Version:
$Revision: 1.14 $ $Date: 2004/08/07 14:39:46 $

Author:
Chris Burdess

Field Summary

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.
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
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
protected boolean
debug
If true, print debugging information.
protected LineInputStream
in
The socket input stream.
protected CRLFOutputStream
out
The socket output stream.
protected java.lang.String
response
The last response received from the server.
protected java.net.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(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, boolean debug)
Creates a new connection to the server.

Method Summary

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
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.
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
uidl()
Returns a map of message number to UID pairs.
java.lang.String
uidl(int msgnum)
Returns a unique identifier for the specified message.

Field Details

APOP

protected static final java.lang.String APOP

Field Value:
"APOP"


AUTH

protected static final java.lang.String AUTH

Field Value:
"AUTH"


CAPA

protected static final java.lang.String CAPA

Field Value:
"CAPA"


DEFAULT_PORT

public static final int DEFAULT_PORT
The default POP3 port.

Field Value:
110


DELE

protected static final java.lang.String DELE

Field Value:
"DELE"


ERR

protected static final int ERR

Field Value:
1


LIST

protected static final java.lang.String LIST

Field Value:
"LIST"


NOOP

protected static final java.lang.String NOOP

Field Value:
"NOOP"


OK

protected static final int OK

Field Value:
0


PASS

protected static final java.lang.String PASS

Field Value:
"PASS"


QUIT

protected static final java.lang.String QUIT

Field Value:
"QUIT"


READY

protected static final int READY

Field Value:
2


RETR

protected static final java.lang.String RETR

Field Value:
"RETR"


RSET

protected static final java.lang.String RSET

Field Value:
"RSET"


STAT

protected static final java.lang.String STAT

Field Value:
"STAT"


STLS

protected static final java.lang.String STLS

Field Value:
"STLS"


TOP

protected static final java.lang.String TOP

Field Value:
"TOP"


UIDL

protected static final java.lang.String UIDL

Field Value:
"UIDL"


USER

protected static final java.lang.String USER

Field Value:
"USER"


debug

protected boolean debug
If true, print debugging information.


in

protected LineInputStream in
The socket input stream.


out

protected CRLFOutputStream out
The socket output stream.


response

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


socket

protected java.net.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(java.lang.String hostname)
            throws java.net.UnknownHostException,
                   java.io.IOException
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)
            throws java.net.UnknownHostException,
                   java.io.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(java.lang.String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean debug)
            throws java.net.UnknownHostException,
                   java.io.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
debug - print debugging information

Method Details

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


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


capa

public java.util.List 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.


dele

public void dele(int msgnum)
            throws java.io.IOException
Marks the specified message as deleted.

Parameters:
msgnum - the message number


getResponse

protected int getResponse()
            throws java.io.IOException
Parse the response from the server. If debug is true, the response is logged.


list

public int list(int msgnum)
            throws java.io.IOException
Returns the size of the specified message.

Parameters:
msgnum - the message number


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


noop

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


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


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


rset

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


send

protected void send(java.lang.String command)
            throws java.io.IOException
Send the command to the server. If debug is true, the command is logged.


stat

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


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


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


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


uidl

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


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


© Copyright 2003 The Free Software Foundation, all rights reserved