de.trantor.mail
Class Pop3Client

java.lang.Object
  |
  +--de.trantor.mail.InboxClient
        |
        +--de.trantor.mail.Pop3Client

public class Pop3Client

extends InboxClient

Encapsulates the POP3 protocol as specified in RFC 1939. This class provides a simple interface to a POP3 mailbox. After a session has been established using the open() method, the number of available messages can be queried by calling the getMessageCount() method, and arbitrary messages or their headers can be retrieved from the mailbox using getMessage() or getHeaders(), respectively. Deleting messages is possible using removeMessage(). Each session should be terminated by a call to the close() method.

Note that all message numbering follows the usual Java conventions for vectors. Thus message indices must be numbers ranging from 0 to getMessageCount() - 1, regardless of what the conventions for the actual protocols are. Implementors of new concrete protocol classes have to keep that in mind, too, of course.

See Also:

SmtpClient, ImapClient, Message

Field Summary

Fields inherited from class de.trantor.mail.InboxClient

connection

Constructor Summary

Pop3Client()
Constructs an instance of the POP3 client.

Pop3Client(Connection connection)
Constructs an instance of the POP3 client with a given Connection instance.

Method Summary

void	close() Ends the mailbox session.
Message	getHeaders(int index) Retrieves a message's headers from the mailbox.
Message	getMessage(int index) Retrieves a message from the mailbox.
Message	getMessage(int index, int maxLines) Retrieves a message from the POP3 mailbox.
int	getMessageCount() Queries the number of messages currently available in the mailbox.
int	getSize(int index) Queries the size of a message.
java.lang.String	getUniqueId(int index) Queries the unique ID of a message as assigned by the server that holds the mailbox.
void	open(java.lang.String host, int port, boolean ssl, java.lang.String user, java.lang.String pass) Opens a mailbox session.
void	removeMessage(int index) Removes a message from the mailbox.

Methods inherited from class de.trantor.mail.InboxClient

connected, getDebug, open, setDebug

Methods inherited from class java.lang.Object

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

Constructor Detail

Pop3Client

public Pop3Client()

Constructs an instance of the POP3 client.

Pop3Client

public Pop3Client(Connection connection)

Constructs an instance of the POP3 client with a given Connection instance.

Method Detail

open

public void open(java.lang.String host,
                 int port,
                 boolean ssl,
                 java.lang.String user,
                 java.lang.String pass)
          throws java.io.IOException,
                 MailException

Description copied from class: InboxClient

Opens a mailbox session. In addition to the remote host's name, the port and the comnnection type (SSL or simple TCP), the username and password have to be specified in order to get access to the mailbox. Note that you can pass a zero port number to use the well known port for the protocol.

Specified by:

open in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.open(String, String, String), InboxClient.close(), InboxClient.connected()

close

public void close()
           throws java.io.IOException,
                  MailException

Description copied from class: InboxClient

Ends the mailbox session. This method should be called after access to the server, in order to close the underlying socket connection and thus free resources.

Specified by:

close in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.open(java.lang.String, java.lang.String, java.lang.String), InboxClient.connected()

getMessageCount

public int getMessageCount()
                    throws java.io.IOException,
                           MailException

Description copied from class: InboxClient

Queries the number of messages currently available in the mailbox.

Specified by:

getMessageCount in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.getMessage(int), InboxClient.getHeaders(int), InboxClient.removeMessage(int)

getMessage

public Message getMessage(int index,
                          int maxLines)
                   throws java.io.IOException,
                          MailException

Retrieves a message from the POP3 mailbox. The method retrieves the message with the given index from the POP3 server. It will only receive up to "maxLines" lines. To retrieve the headers only, pass 0. To retrieve the complete message regardless of its length, pass -1 for this parameter. Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.

java.io.IOException

MailException

See Also:

getMessageCount(), getHeaders(int), getMessage(int)

getMessage

public Message getMessage(int index)
                   throws java.io.IOException,
                          MailException

Description copied from class: InboxClient

Retrieves a message from the mailbox. The method retrieves the message with the given index from the server. Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.

Specified by:

getMessage in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.getMessageCount(), InboxClient.getHeaders(int)

getHeaders

public Message getHeaders(int index)
                   throws java.io.IOException,
                          MailException

Description copied from class: InboxClient

Retrieves a message's headers from the mailbox. The method retrieves the headers of the message with the given index from the server. It does not retrieve any body lines, so this message is a good means to get a quick catalog of the messages available in a mailbox. Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.

Specified by:

getHeaders in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.getMessageCount(), InboxClient.getMessage(int)

removeMessage

public void removeMessage(int index)
                   throws java.io.IOException,
                          MailException

Description copied from class: InboxClient

Removes a message from the mailbox. The method deletes the message with the given index from the mailbox. When deleting messages, two things have to be noted:

• The messages might not be immediately deleted from the server. For POP3, this usually happens when the session is closed. It is not possible to retrieve or otherwise access a deleted message any longer, though.
• Because the message is not deleted immediatly, the indices of other messages in the box don't change until the session is closed. So if you delete message #0 of two messages, there's still a message #1 in the mailbox.

Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.

Specified by:

removeMessage in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.getMessageCount()

getUniqueId

public java.lang.String getUniqueId(int index)
                             throws java.io.IOException,
                                    MailException

Description copied from class: InboxClient

Queries the unique ID of a message as assigned by the server that holds the mailbox. This is not the "Message-ID" field of the message header, it is a value used by the server to uniqely identify messages stored in the mailbox. The server guarantees that no two messages stored in the mailbox will ever have the same ID value. So this value can be used to find out which messages have already been downloaded and which ones have not.

Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.

Specified by:

getUniqueId in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.getMessageCount()

getSize

public int getSize(int index)
            throws java.io.IOException,
                   MailException

Description copied from class: InboxClient

Queries the size of a message. This method queries the size of the given message in bytes.

Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.

Specified by:

getSize in class InboxClient

java.io.IOException

MailException

See Also:

InboxClient.getMessageCount()