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.
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.
|
static 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.
|
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.
|
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.
|
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.
|
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.
DELE
protected static final String DELE
ERR
protected static final int ERR
LIST
protected static final String LIST
NOOP
protected static final String NOOP
OK
protected static final int OK
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
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
logger
public static final Logger logger
The logger used for POP3 protocol traces.
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.
POP3Connection
public POP3Connection(String hostname)
throws UnknownHostException,
IOException
Creates a new connection to the server.
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.
hostname
- the hostname of the server to connect toport
- 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.
hostname
- the hostname of the server to connect toport
- the port to connect to(if <=0, use default POP3 port)connectionTimeout
- the connection timeout, in millisecondstimeout
- 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.
hostname
- the hostname of the server to connect toport
- the port to connect to(if <=0, use default POP3 port)connectionTimeout
- the connection timeout, in millisecondstimeout
- the I/O timeout, in millisecondssecure
- if true, create a POP3S connectiontm
- a trust manager used to check SSL certificates, or null to
use the default
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.
username
- the user to authenticatepassword
- 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.
mechanism
- a SASL authentication mechanism, e.g. LOGIN, PLAIN,
CRAM-MD5, GSSAPIusername
- the authentication principalpassword
- the authentication credentials
- 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.
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.
tm
- an optional trust manager to use
list
public int list(int msgnum)
throws IOException
Returns the size of the specified message.
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.
username
- the user to authenticatepassword
- 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.
- 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.
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
- 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
tm
- the custom trust manager to use
- 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.
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.
msgnum
- the message number
© Copyright 2003 The Free Software Foundation,
all rights reserved