com.jscape.inet.pop

## Class Pop

- java.lang.Object
- - com.jscape.inet.pop.Pop

- All Implemented Interfaces:
    java.io.Serializable, java.lang.AutoCloseable
  Direct Known Subclasses:
    PopSsh, PopSsl

      public class Pop
      extends java.lang.Object
      implements java.lang.AutoCloseable, java.io.Serializable

  Implements the basic functionality of a POP3 client.

  Example Usage:

       // new instance with hostname, username and password
       Pop pop = new Pop("pop3.myserver.com","jsmith","secret");
       try
       {
         // connect to POP3 server
         pop.connect();
          // get messages
         Enumeration e = pop.getMessages();
         while(e.hasMoreElements()) {
           EmailMessage em = (EmailMessage)e.nextElement();
         }
          // disconnect
         pop.disconnect();
       }
       catch(Exception e)
       {
         System.out.println(e);
       }

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Pop.Authentication`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `AUTH_APOP` APOP authentication.
    `static int` | `AUTH_LOGIN` Standard username/password authentication.
    `static int` | `AUTH_PASS` Deprecated. replaced by AUTH_LOGIN variable for consistency
    `static int` | `AUTH_XOAUTH2`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Pop()` Constructs a new Pop instance.
    `Pop(java.lang.String hostname, java.lang.String username, java.lang.String password)` Constructs a new Pop instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPopListener(PopListener listener)` Adds Pop event listener.
    `void` | `clearProxySettings()` Clears proxy server values.
    `void` | `close()`
    `Pop` | `connect()` Connects to POP3 server and performs login.
    `void` | `deleteMessage(int msg)` Deletes message from POP3 server.
    `void` | `disconnect()` Disconnects from POP3 server.
    `int` | `getAuthMode()` Gets the authentication mode used when logging into POP3 server.
    `int` | `getConnectTimeout()` Gets the timeout used when opening a POP3 server connection.
    `java.io.PrintStream` | `getDebugStream()` Gets PrintStream used in reporting debug statements.
    `java.lang.String` | `getHostname()` Gets the hostname of the POP3 server.
    `EmailMessage` | `getMessage(int msg)` Gets message from POP3 server.
    `int` | `getMessageCount()` Gets number of messages currently in POP3 mailbox.
    `PopMessageReader` | `getMessageReader(int msg)` Gets a reader that may be used to read message.
    `java.util.Enumeration` | `getMessages()` Gets all available messages in mailbox from POP3 server.
    `int` | `getMessageSize(int msg)` Gets size of message in bytes from POP3 server.
    `int` | `getPort()` Gets the port of the POP3 server.
    `int` | `getReadTimeout()` Gets the timeout used when reading responses from POP server.
    `int` | `getTimeout()` Deprecated. Replaced by getConnectTimeout and getReadTimeout
    `java.lang.String` | `getTop(int msg, int lines)` Gets summary of message from POP3 server.
    `java.lang.String` | `getUid(int msg)` Gets unique message id for a message on POP3 server.
    `java.lang.String` | `getUsername()` Gets the username to be used in authentication to POP3 server.
    `boolean` | `isConnected()` Checks if client is connected to POP3 server.
    `boolean` | `isDebug()` Gets debug level of POP3 session.
    `boolean` | `isDelete()` Checks whether to delete messages automatically after retrieval.
    `java.lang.String` | `issueCommand(java.lang.String command)` Issues a command to POP3 server and reads response.
    `java.lang.String` | `issueCommand(java.lang.String command, boolean readResponse)` Issues a command to POP3 server and optionally reads response.
    `java.lang.String` | `issueCommandMultiLine(java.lang.String command)` Issues a command to POP3 server and reads a multi-line response.
    `void` | `removePopListener(PopListener listener)` Removes specified Pop event listener.
    `Pop` | `setAuthentication(Pop.Authentication authentication)`
    `void` | `setAuthMode(int mode)` Sets the authentication mode used when logging into POP3 server.
    `void` | `setConnectTimeout(int timeout)` Sets the timeout for opening a POP3 server connection.
    `void` | `setDebug(boolean debug)` Sets debugging state.
    `void` | `setDebugStream(java.io.PrintStream debugStream)` Sets PrintStream used in reporting debug statements.
    `void` | `setDelete(boolean delete)` Defines whether to delete messages automatically after retrieval.
    `void` | `setHostname(java.lang.String hostname)` Sets the hostname of the POP3 server.
    `void` | `setPassword(java.lang.String password)` Sets the password to be used in authentication to POP3 server.
    `void` | `setPort(int port)` Sets the port of the POP3 server.
    `void` | `setProxyAuthentication(java.lang.String proxyUsername, java.lang.String proxyPassword)` Sets the username and password to use when for authentication with proxy server.
    `void` | `setProxyHost(java.lang.String proxyHostname, int proxyPort)` Sets the proxy hostname and port for this connection.
    `void` | `setProxyType(java.lang.String proxyType)` Sets the proxy type will be used for this connection.
    `void` | `setReadTimeout(int timeout)` Sets the timeout for reading responses from POP server.
    `void` | `setTimeout(int timeout)` Deprecated. Replaced by setConnectTimeout and setReadTimeout
    `void` | `setUsername(java.lang.String username)` Sets the username to be used in authentication to POP3 server.

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

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

- - ### Field Detail

    - #### AUTH_PASS

          public static final int AUTH_PASS

      Deprecated. replaced by AUTH_LOGIN variable for consistency
      Standard username/password authentication. Use with `setAuthMode` method.
      See Also:
        Constant Field Values

    - #### AUTH_LOGIN

          public static final int AUTH_LOGIN

      Standard username/password authentication. Use with `setAuthMode` method.
      See Also:
        Constant Field Values

    - #### AUTH_APOP

          public static final int AUTH_APOP

      APOP authentication. Use with `setAuthMode` method.
      See Also:
        Constant Field Values

    - #### AUTH_XOAUTH2

          public static final int AUTH_XOAUTH2

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Pop

          public Pop()

      Constructs a new Pop instance.

    - #### Pop

          public Pop(java.lang.String hostname,
                     java.lang.String username,
                     java.lang.String password)

      Constructs a new Pop instance. Sets hostname, username and password for POP3 connection.
      Parameters:
        `hostname` - the hostname of POP3 server
        `username` - the username of POP3 user
        `password` - the password of POP3 user

  - ### Method Detail

    - #### setAuthentication

          public Pop setAuthentication(Pop.Authentication authentication)

    - #### setAuthMode

          public void setAuthMode(int mode)

      Sets the authentication mode used when logging into POP3 server. Possible values are Pop.AUTH_LOGIN for username/password authentication or Pop.AUTH_APOP for APOP authentication.
      Parameters:
        `mode` - authentication mode

    - #### getAuthMode

          public int getAuthMode()

      Gets the authentication mode used when logging into POP3 server. Possible values are Pop.AUTH_LOGIN for username/password authentication or Pop.AUTH_APOP for APOP authentication.
      Returns:
        authentication mode

    - #### setConnectTimeout

          public void setConnectTimeout(int timeout)

      Sets the timeout for opening a POP3 server connection.

      Default is 30 seconds.
      Parameters:
        `timeout` - the timeout in milliseconds

    - #### getConnectTimeout

          public int getConnectTimeout()

      Gets the timeout used when opening a POP3 server connection.

      Default is 30 seconds.
      Returns:
        timeout server connection.

    - #### isConnected

          public boolean isConnected()

      Checks if client is connected to POP3 server.
      Returns:
        connection status

    - #### setDebug

          public void setDebug(boolean debug)

      Sets debugging state. All debug statements are reported to debug stream. Default debug stream is System.out
      Parameters:
        `debug` - `true` to turn debugging on
      See Also:
        `setDebugStream(java.io.PrintStream)`

    - #### isDebug

          public boolean isDebug()

      Gets debug level of POP3 session. Debug messages are sent to debug stream. Defaul debug stream is System.out
      Returns:
        `true` if debugging is on
      See Also:
        `setDebugStream(java.io.PrintStream)`

    - #### setDebugStream

          public void setDebugStream(java.io.PrintStream debugStream)

      Sets PrintStream used in reporting debug statements. Default PrintStream is System.out
      Parameters:
        `debugStream` - the PrintStream to send debug statements to
      See Also:
        `PrintStream`

    - #### getDebugStream

          public java.io.PrintStream getDebugStream()

      Gets PrintStream used in reporting debug statements. Default PrintStream is System.out
      Returns:
        the PrintStream used for debugging
      See Also:
        `PrintStream`

    - #### setDelete

          public void setDelete(boolean delete)

      Defines whether to delete messages automatically after retrieval. Default is `false`.
      Parameters:
        `delete` - `true` to delete automatically

    - #### isDelete

          public boolean isDelete()

      Checks whether to delete messages automatically after retrieval. Default is `false`.
      Returns:
        `true` if should delete automatically

    - #### setHostname

          public void setHostname(java.lang.String hostname)

      Sets the hostname of the POP3 server.
      Parameters:
        `hostname` - the hostname of POP3 server

    - #### getHostname

          public java.lang.String getHostname()

      Gets the hostname of the POP3 server.
      Returns:
        hostname

    - #### getMessage

          public EmailMessage getMessage(int msg)
                                  throws PopException

      Gets message from POP3 server. Message id is always one (1) based, first message id beginning with 1, second with 2 and so on.
      Parameters:
        `msg` - message id of message
      Returns:
        the email message with supplied message id
      Throws:
        `PopException` - if I/O or POP3 related error occurs
      See Also:
        `EmailMessage`

    - #### getMessageCount

          public int getMessageCount()
                              throws PopException

      Gets number of messages currently in POP3 mailbox.
      Returns:
        the total number of messages in POP3 account mailbox
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### getMessageReader

          public PopMessageReader getMessageReader(int msg)
                                            throws PopException

      Gets a reader that may be used to read message. Once this method is invoked you MAY NOT invoke any other methods until you have fully read the message. Failure to comply will result in a corrupt POP session. PopMessageProgressEvent and PopMessageEvent events will not be fired when using this method.
      Parameters:
        `msg` - the message id of message
      Returns:
        a PopMessageReader
      Throws:
        `PopException` - if an I/O or POP3 related error occurs.
      See Also:
        `PopMessageReader`

    - #### getMessageSize

          public int getMessageSize(int msg)
                             throws PopException

      Gets size of message in bytes from POP3 server. Message id is always one (1) based, first message id beginning with 1, second with 2 and so on.
      Parameters:
        `msg` - message id of message
      Returns:
        the size of email message in bytes
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### getMessages

          public java.util.Enumeration getMessages()
                                            throws PopException

      Gets all available messages in mailbox from POP3 server.
      Returns:
        an Enumeration of EmailMessage
      Throws:
        `PopException` - if I/O or POP3 related error occurs
      See Also:
        `EmailMessage`

    - #### setPassword

          public void setPassword(java.lang.String password)

      Sets the password to be used in authentication to POP3 server.
      Parameters:
        `password` - the password of POP3 user

    - #### setPort

          public void setPort(int port)

      Sets the port of the POP3 server. Default value is 110.
      Parameters:
        `port` - the port of POP3 server

    - #### getPort

          public int getPort()

      Gets the port of the POP3 server. Default value is 110.
      Returns:
        port

    - #### setReadTimeout

          public void setReadTimeout(int timeout)

      Sets the timeout for reading responses from POP server. Default is 30 seconds.
      Parameters:
        `timeout` - the timeout in milliseconds

    - #### getReadTimeout

          public int getReadTimeout()

      Gets the timeout used when reading responses from POP server. Default is 30 seconds.
      Returns:
        reading from server timeout.

    - #### setTimeout

          public void setTimeout(int timeout)

      Deprecated. Replaced by setConnectTimeout and setReadTimeout
      Sets the timeout for opening a POP3 server connection and reading responses from POP server. Default is 30 seconds.
      Parameters:
        `timeout` - the timeout in milliseconds
      See Also:
        `setConnectTimeout(int)`, `setReadTimeout(int)`

    - #### getTimeout

          public int getTimeout()

      Deprecated. Replaced by getConnectTimeout and getReadTimeout
      Gets the timeout used when opening a POP3 server connection and reading responses from POP server. Default is 30 seconds.
      Returns:
        timeout
      See Also:
        `getConnectTimeout()`, `getReadTimeout()`

    - #### getTop

          public java.lang.String getTop(int msg,
                                         int lines)
                                  throws PopException

      Gets summary of message from POP3 server. Used primary to peek at a message without downloading entire contents. Message id is always one (1) based, first message id beginning with 1, second with 2 and so on.
      Parameters:
        `msg` - message id
        `lines` - number of lines to retrieve
      Returns:
        portion of message
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### getUid

          public java.lang.String getUid(int msg)
                                  throws PopException

      Gets unique message id for a message on POP3 server.
      Parameters:
        `msg` - the message number to get the unique message id for. Message number is always (1) based, first message number is 1, second is 2 and so on.
      Returns:
        a unique message id
      Throws:
        `PopException` - if an I/O or POP3 related error occurs

    - #### setUsername

          public void setUsername(java.lang.String username)

      Sets the username to be used in authentication to POP3 server.
      Parameters:
        `username` - the username of POP3 user

    - #### getUsername

          public java.lang.String getUsername()

      Gets the username to be used in authentication to POP3 server.
      Returns:
        username

    - #### setProxyAuthentication

          public void setProxyAuthentication(java.lang.String proxyUsername,
                                             java.lang.String proxyPassword)

      Sets the username and password to use when for authentication with proxy server. To clear these settings invoke the `#clearProxySettings` method.
      Parameters:
        `proxyUsername` - the proxy username
        `proxyPassword` - the proxy password
      See Also:
        `clearProxySettings()`

    - #### setProxyHost

          public void setProxyHost(java.lang.String proxyHostname,
                                   int proxyPort)

      Sets the proxy hostname and port for this connection. To clear these settings invoke the `#clearProxySettings` method.
      Parameters:
        `proxyHostname` - the hostname or ip address of the proxy server
        `proxyPort` - the port of the proxy server
      See Also:
        `clearProxySettings()`

    - #### setProxyType

          public void setProxyType(java.lang.String proxyType)

      Sets the proxy type will be used for this connection.
      Parameters:
        `proxyType` - The proxy type. Valid values: HTTP, SOCKS5

    - #### clearProxySettings

          public void clearProxySettings()

      Clears proxy server values.

    - #### addPopListener

          public void addPopListener(PopListener listener)

      Adds Pop event listener.
      Parameters:
        `listener` - a PopListener
      See Also:
        `PopListener`

    - #### connect

          public Pop connect()
                      throws PopException

      Connects to POP3 server and performs login.
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### deleteMessage

          public void deleteMessage(int msg)
                             throws PopException

      Deletes message from POP3 server.
      Parameters:
        `msg` - message id of message
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### disconnect

          public void disconnect()
                          throws PopException

      Disconnects from POP3 server. Issues QUIT command to POP3 server.
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### close

          public void close()
                     throws java.lang.Exception

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.lang.Exception`

    - #### issueCommand

          public java.lang.String issueCommand(java.lang.String command)
                                        throws PopException

      Issues a command to POP3 server and reads response.
      Parameters:
        `command` - a POP3 command
      Returns:
        POP3 server response
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### issueCommand

          public java.lang.String issueCommand(java.lang.String command,
                                               boolean readResponse)
                                        throws PopException

      Issues a command to POP3 server and optionally reads response.
      Parameters:
        `command` - a POP3 command
        `readResponse` - `true` if should read response `false` otherwise
      Returns:
        POP3 server response
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### issueCommandMultiLine

          public java.lang.String issueCommandMultiLine(java.lang.String command)
                                                 throws PopException

      Issues a command to POP3 server and reads a multi-line response. This command should only be used for known POP3 commands that issue a known multi-line response such as LIST and TOP.
      Parameters:
        `command` - a POP3 command
      Returns:
        POP3 server response
      Throws:
        `PopException` - if I/O or POP3 related error occurs

    - #### removePopListener

          public void removePopListener(PopListener listener)

      Removes specified Pop event listener.
      Parameters:
        `listener` - the PopListener to remove
      See Also:
        `PopListener`

Copyright © JSCAPE LLC. 1999-2021. All Rights Reserved