POP3Connection (gnu-classpath-ext-inetlib 1.1.1 API)

java.lang.Object
- gnu.inet.pop3.POP3Connection

```
public class POP3Connection
extends 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

Fields
Modifier and Type	Field and Description
`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 LineInputStream`	`in` The socket input stream.
`protected static String`	`LIST`
`static Logger`	`logger` The logger used for POP3 protocol traces.
`protected static String`	`NOOP`
`protected static int`	`OK`
`protected CRLFOutputStream`	`out` The socket output stream.
`protected static String`	`PASS`
`static Level`	`POP3_TRACE` The network trace level.
`protected static String`	`QUIT`
`protected static int`	`READY`
`protected String`	`response` The last response received from the server.
`protected static String`	`RETR`
`protected static String`	`RSET`
`protected Socket`	`socket` The socket used to communicate with the server.
`protected static String`	`STAT`
`protected static String`	`STLS`
`protected byte[]`	`timestamp` The APOP timestamp, if sent by the server on connection.
`protected static String`	`TOP`
`protected static String`	`UIDL`
`protected static String`	`USER`

Constructor Summary

Constructors
Constructor and Description
`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.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - logger
```
public static final Logger logger
```
    The logger used for POP3 protocol traces.
  - POP3_TRACE
```
public static final 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 String STAT
```
    See Also:
    
    Constant Field Values
  - LIST
```
protected static final String LIST
```
    See Also:
    
    Constant Field Values
  - RETR
```
protected static final String RETR
```
    See Also:
    
    Constant Field Values
  - DELE
```
protected static final String DELE
```
    See Also:
    
    Constant Field Values
  - NOOP
```
protected static final String NOOP
```
    See Also:
    
    Constant Field Values
  - RSET
```
protected static final String RSET
```
    See Also:
    
    Constant Field Values
  - QUIT
```
protected static final String QUIT
```
    See Also:
    
    Constant Field Values
  - TOP
```
protected static final String TOP
```
    See Also:
    
    Constant Field Values
  - UIDL
```
protected static final String UIDL
```
    See Also:
    
    Constant Field Values
  - USER
```
protected static final String USER
```
    See Also:
    
    Constant Field Values
  - PASS
```
protected static final String PASS
```
    See Also:
    
    Constant Field Values
  - APOP
```
protected static final String APOP
```
    See Also:
    
    Constant Field Values
  - CAPA
```
protected static final String CAPA
```
    See Also:
    
    Constant Field Values
  - STLS
```
protected static final String STLS
```
    See Also:
    
    Constant Field Values
  - AUTH
```
protected static final 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
  - socket
```
protected 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 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(String hostname)
               throws UnknownHostException,
                      IOException
```
    Creates a new connection to the server.
    
    Parameters:
    
    hostname - the hostname of the server to connect to
    
    Throws:
    
    UnknownHostException
    
    IOException
  - 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)
    
    Throws:
    
    UnknownHostException
    
    IOException
  - 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
    
    Throws:
    
    UnknownHostException
    
    IOException
  - 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
    
    Throws:
    
    UnknownHostException
    
    IOException
- Method Detail
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    GeneralSecurityException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - stat
```
public int stat()
         throws IOException
```
    Returns the number of messages in the maildrop.
    
    Throws:
    
    IOException
  - list
```
public int list(int msgnum)
         throws IOException
```
    Returns the size of the specified message.
    
    Parameters:
    
    msgnum - the message number
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - dele
```
public void dele(int msgnum)
          throws IOException
```
    Marks the specified message as deleted.
    
    Parameters:
    
    msgnum - the message number
    
    Throws:
    
    IOException
  - noop
```
public void noop()
          throws IOException
```
    Does nothing. This can be used to keep the connection alive.
    
    Throws:
    
    IOException
  - rset
```
public void rset()
          throws IOException
```
    If any messages have been marked as deleted, they are unmarked.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - uidl
```
public String uidl(int msgnum)
            throws IOException
```
    Returns a unique identifier for the specified message.
    
    Parameters:
    
    msgnum - the message number
    
    Throws:
    
    IOException
  - uidl
```
public Map uidl()
         throws IOException
```
    Returns a map of message number to UID pairs. Message numbers are Integers, UIDs are Strings.
    
    Throws:
    
    IOException
  - 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.
    
    Throws:
    
    IOException
  - send
```
protected void send(String command)
             throws IOException
```
    Send the command to the server.
    
    Throws:
    
    IOException
  - getResponse
```
protected int getResponse()
                   throws IOException
```
    Parse the response from the server.
    
    Throws:
    
    IOException

Class POP3Connection

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

POP3_TRACE

DEFAULT_PORT

STAT

LIST

RETR

DELE

NOOP

RSET

QUIT

TOP

UIDL

USER

PASS

APOP

CAPA

STLS

AUTH

OK

ERR

READY

socket

in

out

response

timestamp

Constructor Detail

POP3Connection

POP3Connection

POP3Connection

POP3Connection

Method Detail

auth

apop

login

getSSLSocketFactory

stls

stls

stat

list

retr

dele

noop

rset

quit

top

uidl

uidl

capa

send

getResponse