gnu.inet.pop3
Class POP3Connection

java.lang.Object
  extended by 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.

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  LineInputStream in
          The socket input stream.
protected static java.lang.String LIST
           
static java.util.logging.Logger logger
          The logger used for POP3 protocol traces.
protected static java.lang.String NOOP
           
protected static int OK
           
protected  CRLFOutputStream out
          The socket output stream.
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  java.lang.String response
          The last response received from the server.
protected static java.lang.String RETR
           
protected static java.lang.String RSET
           
protected  java.net.Socket socket
          The socket used to communicate with the server.
protected static java.lang.String STAT
           
protected static java.lang.String STLS
           
protected  byte[] timestamp
          The APOP timestamp, if sent by the server on connection.
protected static java.lang.String TOP
           
protected static java.lang.String UIDL
           
protected static java.lang.String USER
           
 
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)
          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.
POP3Connection(java.lang.String hostname, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm, boolean init)
          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.
protected  javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.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(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.
 
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

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

logger

public static final java.util.logging.Logger logger
The logger used for POP3 protocol traces.


socket

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


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.


timestamp

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

Constructor Detail

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
Throws:
java.net.UnknownHostException
java.io.IOException

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)
Throws:
java.net.UnknownHostException
java.io.IOException

POP3Connection

public POP3Connection(java.lang.String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout)
               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
Throws:
java.net.UnknownHostException
java.io.IOException

POP3Connection

public POP3Connection(java.lang.String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      javax.net.ssl.TrustManager tm)
               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
secure - if true, create a POP3S connection
tm - a trust manager used to check SSL certificates, or null to use the default
Throws:
java.net.UnknownHostException
java.io.IOException

POP3Connection

public POP3Connection(java.lang.String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      javax.net.ssl.TrustManager tm,
                      boolean init)
               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
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
Throws:
java.net.UnknownHostException
java.io.IOException
Method Detail

init

public void init()
          throws java.io.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.

Throws:
java.io.IOException

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 uidl()
                   throws java.io.IOException
Returns a map of message number to UID pairs. Message numbers are Integers, UIDs are Strings.

Throws:
java.io.IOException

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.

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


© Copyright 2003 The Free Software Foundation, all rights reserved