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.


Field Summary
protected  Connection connection
          Holds the socket used for communication with the server.
 
Constructor Summary
protected InboxClient()
          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()
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.
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.
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.
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.
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.
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.
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.

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.

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: Message numbering follows the usual Java conventions for vectors. Thus the index must be a number ranging from 0 to getMessageCount() - 1.
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)