i2p.susi.webmail.pop3

## Class POP3MailBox

- java.lang.Object
- - i2p.susi.webmail.pop3.POP3MailBox

- All Implemented Interfaces:
    NewMailListener

      public class POP3MailBox
      extends Object
      implements NewMailListener

  POP3 client for retrieving email from POP3 servers over I2P. Supports standard POP3 commands, background checking, and delayed deletion. Optimized for high-latency I2P connections with pipelining and idle timeout management.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `POP3MailBox.FetchRequest` Request for fetching email data with UIDL and header options.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `POP3MailBox(String host, int port, String user, String pass)` Does not connect.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) boolean` | `blockingConnectToServer()` Connect to pop3 server if not connected.
    `void` | `close()` Close without waiting for response.
    `(package private) void` | `close(boolean shouldWait)` Close and optionally wait for response.
    `boolean` | `connectToServer(NewMailListener nml)` Connect to pop3 server if not connected.
    `(package private) void` | `deletePending(boolean noWait)` Delete all pending deletions at once.
    `void` | `destroy()` Close without waiting for response, and remove any delayed tasks and resources.
    `void` | `foundNewMail(boolean yes)` Relay from the checker to the webmail session object, which relays to MailCache, which will fetch the mail from us in a big circle
    `void` | `getBodies(Collection<POP3MailBox.FetchRequest> requests)` Fetch headers and/or bodies.
    `Buffer` | `getBody(String uidl, Buffer buffer)` Fetch the body.
    `Buffer` | `getHeader(String uidl)` Fetch the header.
    `(package private) long` | `getLastActivity()` Timestamp.
    `(package private) long` | `getLastChecked()` Timestamp.
    `(package private) Object` | `getLock()` For helper threads to lock
    `int` | `getNumMails()` Warning - forces a connection.
    `int` | `getSize(String uidl)` Get cached size of a message (via previous LIST command).
    `Collection<String>` | `getUIDLs()` Only if connected.
    `(package private) boolean` | `hasQueuedDeletions()` Do we have UIDLs to delete?
    `(package private) boolean` | `isConnected()` Is the connection is still alive
    `String` | `lastError()`
    `void` | `queueForDeletion(Collection<String> uidls)` Queue for later deletion.
    `void` | `queueForDeletion(String uidl)` Queue for later deletion.
    `void` | `setNewMailListener(NewMailListener nml)` Relay from the checker to the webmail session object, which relays to MailCache, which will fetch the mail from us in a big circle

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### POP3MailBox

          public POP3MailBox(String host,
                             int port,
                             String user,
                             String pass)

      Does not connect. Caller must call connectToServer() if desired.
      Parameters:
        `host` -
        `port` -
        `user` -
        `pass` -

  - ### Method Detail

    - #### blockingConnectToServer

          boolean blockingConnectToServer()

      Connect to pop3 server if not connected. Does nothing if already connected. Blocking. This will NOT call any configured NewMailListener. After the callback is executed, the information on new mails, if any, is available via getNumMails(), getUIDLs(), and getSize(). The connection to the server will remain open, so that new emails may be retrieved via getHeader(), getBody(), and getBodies(). Failure info is available via lastError().
      Returns:
        true if connected

    - #### close

          public void close()

      Close without waiting for response. Deletes all queued deletions.

    - #### close

          void close(boolean shouldWait)

      Close and optionally wait for response. Deletes all queued deletions.

    - #### connectToServer

          public boolean connectToServer(NewMailListener nml)

      Connect to pop3 server if not connected. Checks mail if already connected. Non-Blocking unless an action already in progress. This will NOT call any configured NewMailListener, only the one passed in. It will be called with the value true if the connect was successful, false if not. Call getNumMails() to see if there really was any new mail. After the callback is executed, the information on new mails, if any, is available via getNumMails(), getUIDLs(), and getSize(). The connection to the server will remain open, so that new emails may be retrieved via getHeader(), getBody(), and getBodies(). Failure info is available via lastError().
      Returns:
        true if nml will be called back, false on failure and nml will NOT be called back

    - #### deletePending

          void deletePending(boolean noWait)

      Delete all pending deletions at once. If previously connected, leaves connected. If not previously connected, closes connection when done.
      Parameters:
        `noWait` - fire-and-forget mode, only if connected

    - #### destroy

          public void destroy()

      Close without waiting for response, and remove any delayed tasks and resources.

    - #### foundNewMail

          public void foundNewMail(boolean yes)

      Relay from the checker to the webmail session object, which relays to MailCache, which will fetch the mail from us in a big circle
      Specified by:
        `foundNewMail` in interface `NewMailListener`

    - #### getBodies

          public void getBodies(Collection<POP3MailBox.FetchRequest> requests)

      Fetch headers and/or bodies. Does not cache. ReadBuffer objects are inserted into the requests. No total time limit.

    - #### getBody

          public Buffer getBody(String uidl,
                                Buffer buffer)

      Fetch the body. Does not cache.
      Parameters:
        `uidl` -
      Returns:
        the buffer containing body data or null

    - #### getHeader

          public Buffer getHeader(String uidl)

      Fetch the header. Does not cache.
      Parameters:
        `uidl` -
      Returns:
        Byte buffer containing header data or null

    - #### getLastActivity

          long getLastActivity()

      Timestamp.

    - #### getLastChecked

          long getLastChecked()

      Timestamp. When we last successfully got the UIDL list.

    - #### getLock

          Object getLock()

      For helper threads to lock

    - #### getNumMails

          public int getNumMails()

      Warning - forces a connection.
      Returns:
        The amount of e-mails available.

    - #### getSize

          public int getSize(String uidl)

      Get cached size of a message (via previous LIST command).
      Parameters:
        `uidl` -
      Returns:
        Message size in bytes or 0 if not found

    - #### getUIDLs

          public Collection<String> getUIDLs()

      Only if connected. Does not force a connect. If not connected, returns null.
      Returns:
        A new array of the available UIDLs. No particular order.

    - #### hasQueuedDeletions

          boolean hasQueuedDeletions()

      Do we have UIDLs to delete?

    - #### isConnected

          boolean isConnected()

      Is the connection is still alive
      Returns:
        true or false

    - #### lastError

          public String lastError()

      Returns:
        The most recent error message. Probably not terminated with a newline.

    - #### queueForDeletion

          public void queueForDeletion(Collection<String> uidls)

      Queue for later deletion. Non-blocking.

    - #### queueForDeletion

          public void queueForDeletion(String uidl)

      Queue for later deletion. Non-blocking.

    - #### setNewMailListener

          public void setNewMailListener(NewMailListener nml)

      Relay from the checker to the webmail session object, which relays to MailCache, which will fetch the mail from us in a big circle