de.trantor.mail
Class InboxClient

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

Direct Known Subclasses:

ImapClient, Pop3Client

public abstract class InboxClient

extends java.lang.Object

This class provides an abstraction for the various protocols that are used to access a mailbox (currently POP3 and IMAP). The first thing an application should do is create an instance of a concrete protocol using the getInstance() method. After a session has been established using the open() method on this instance, 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:

Pop3Client, ImapClient

Field Summary

protected Connection

connection Holds the socket used for communication with the server.

Constructor Summary

protected

InboxClient(Connection connection) Initializes the Connection object belonging to this InboxClient.

Method Summary

abstract void	close() Ends the mailbox session.
boolean	connected() Returns true, if the client is currently connected to an SMTP server.
boolean	getDebug() Queries the current value of the debugging flag.
abstract Message	getHeaders(int index) Retrieves a message's headers from the mailbox.
abstract Message	getMessage(int index) Retrieves a message from the mailbox.
abstract int	getMessageCount() Queries the number of messages currently available in the mailbox.
abstract int	getSize(int index) Queries the size of a message.
abstract java.lang.String	getUniqueId(int index) Queries the unique ID of a message as assigned by the server that holds the mailbox.
abstract void	open(java.lang.String host, int port, boolean ssl, java.lang.String user, java.lang.String pass) Opens a mailbox session.
void	open(java.lang.String host, java.lang.String user, java.lang.String pass) Opens a mailbox session.
abstract void	removeMessage(int index) Removes a message from the mailbox.
void	setDebug(boolean debug) Controls the output of debugging information to standard output.

Methods inherited from class java.lang.Object

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

Field Detail

connection

protected Connection connection

Holds the socket used for communication with the server.

Constructor Detail

InboxClient

protected InboxClient(Connection connection)

Initializes the Connection object belonging to this InboxClient. This constructor is never called directly, but from descendant classes instead.

Method Detail

open

public void open(java.lang.String host,
                 java.lang.String user,
                 java.lang.String pass)
          throws java.lang.Exception,
                 java.io.IOException,
                 MailException

Opens a mailbox session. In addition to the remote host's name, username and password have to be specified in order to get access to the mailbox. The well-known port is used, and an insecure (non-SSL) connection is opened.

java.lang.Exception

java.io.IOException

MailException

See Also:

open(String, int, boolean, String, String), close(), connected()

open

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

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.

java.lang.Exception

java.io.IOException

MailException

See Also:

open(String, String, String), close(), connected()

close

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

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.

java.io.IOException

MailException

See Also:

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

connected

public boolean connected()

Returns true, if the client is currently connected to an SMTP server.

See Also:

open(java.lang.String, java.lang.String, java.lang.String), close()

getMessageCount

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

Queries the number of messages currently available in the mailbox.

java.io.IOException

MailException

See Also:

getMessage(int), getHeaders(int), removeMessage(int)

getMessage

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

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.

java.io.IOException

MailException

See Also:

getMessageCount(), getHeaders(int)

getHeaders

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

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.

java.io.IOException

MailException

See Also:

getMessageCount(), getMessage(int)

getUniqueId

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

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.

java.io.IOException

MailException

See Also:

getMessageCount()

getSize

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

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.

java.io.IOException

MailException

See Also:

getMessageCount()

removeMessage

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

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.

java.io.IOException

MailException

See Also:

getMessageCount()

setDebug

public void setDebug(boolean debug)

Controls the output of debugging information to standard output. Set it to true to see all protocol information exchanged.

See Also:

getDebug()

getDebug

public boolean getDebug()

Queries the current value of the debugging flag.

See Also:

setDebug(boolean)