Class Protocol


  • class Protocol
    extends java.lang.Object
    This class provides a POP3 connection and implements the POP3 protocol requests. APOP support courtesy of "chamness".
    • Constructor Summary

      Constructors 
      Constructor Description
      Protocol​(java.lang.String host, int port, MailLogger logger, java.util.Properties props, java.lang.String prefix, boolean isSSL)
      Open a connection to the POP3 server.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void batchCommandContinue​(java.lang.String command)  
      private void batchCommandEnd()  
      private void batchCommandStart​(java.lang.String command)  
      (package private) java.io.InputStream capa()
      Get server capabilities using CAPA command specified by RFC 2449.
      private static java.io.IOException cleanupAndThrow​(java.net.Socket socket, java.io.IOException ife)  
      (package private) void close()
      Close the connection without sending any commands.
      (package private) boolean dele​(int msg)
      Delete (permanently) the specified message.
      protected void finalize()  
      private boolean getBoolProp​(java.util.Properties props, java.lang.String prop)
      Get the value of a boolean property.
      (package private) java.util.Map<java.lang.String,​java.lang.String> getCapabilities()
      Return the map of capabilities returned by the server.
      private java.lang.String getDigest​(java.lang.String password)
      Gets the APOP message digest.
      (package private) boolean hasCapability​(java.lang.String c)
      Check whether the given capability is supported by this server.
      private void initStreams()  
      private static boolean isRecoverable​(java.lang.Throwable t)  
      (package private) boolean isSSL()
      Is this connection using SSL?
      private void issueCommand​(java.lang.String cmd)
      Send the specified command.
      protected boolean isTracing()
      Is protocol tracing enabled?
      (package private) java.io.InputStream list()
      Return the size of all messages using the LIST command.
      (package private) int list​(int msg)
      Return the size of the message using the LIST command.
      (package private) java.lang.String login​(java.lang.String user, java.lang.String password)
      Login to the server, using the USER and PASS commands.
      private Response multilineCommand​(java.lang.String cmd, int size)
      Issue a POP3 command that expects a multi-line response.
      private void multilineCommandEnd()  
      private void multilineCommandStart​(java.lang.String command)  
      (package private) boolean noop()
      Do a NOOP.
      (package private) boolean quit()
      Close down the connection, sending the QUIT command.
      private java.io.InputStream readMultilineResponse​(int size)
      Read the response to a multiline command after the command response.
      private Response readResponse()
      Read the response to a command.
      private void resumeTracing()
      Resume protocol tracing, if it was enabled to begin with.
      (package private) java.io.InputStream retr​(int msg, int size)
      Retrieve the specified message.
      (package private) boolean retr​(int msg, java.io.OutputStream os)
      Retrieve the specified message and stream the content to the specified OutputStream.
      (package private) boolean rset()
      Do an RSET.
      (package private) void setCapabilities​(java.io.InputStream in)
      Parse the capabilities from a CAPA response.
      private Response simpleCommand​(java.lang.String cmd)
      Issue a simple POP3 command and return the response.
      private void simpleCommandEnd()  
      private void simpleCommandStart​(java.lang.String command)  
      (package private) Status stat()
      Return the total number of messages and mailbox size, using the STAT command.
      (package private) boolean stls()
      Start TLS using STLS command specified by RFC 2595.
      private void suspendTracing()
      Temporarily turn off protocol tracing, e.g., to prevent tracing the authentication sequence, including the password.
      private static java.lang.String toHex​(byte[] bytes)
      Convert a byte array to a string of hex digits representing the bytes.
      (package private) java.io.InputStream top​(int msg, int n)
      Return the message header and the first n lines of the message.
      (package private) java.lang.String uidl​(int msg)
      Return the UIDL string for the message.
      (package private) boolean uidl​(java.lang.String[] uids)
      Return the UIDL strings for all messages.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • socket

        private java.net.Socket socket
      • host

        private java.lang.String host
      • props

        private java.util.Properties props
      • prefix

        private java.lang.String prefix
      • input

        private java.io.BufferedReader input
      • output

        private java.io.PrintWriter output
      • apopChallenge

        private java.lang.String apopChallenge
      • capabilities

        private java.util.Map<java.lang.String,​java.lang.String> capabilities
      • pipelining

        private boolean pipelining
      • noauthdebug

        private boolean noauthdebug
      • traceSuspended

        private boolean traceSuspended
      • digits

        private static char[] digits
    • Constructor Detail

      • Protocol

        Protocol​(java.lang.String host,
                 int port,
                 MailLogger logger,
                 java.util.Properties props,
                 java.lang.String prefix,
                 boolean isSSL)
          throws java.io.IOException
        Open a connection to the POP3 server.
        Throws:
        java.io.IOException
    • Method Detail

      • cleanupAndThrow

        private static java.io.IOException cleanupAndThrow​(java.net.Socket socket,
                                                           java.io.IOException ife)
      • isRecoverable

        private static boolean isRecoverable​(java.lang.Throwable t)
      • getBoolProp

        private final boolean getBoolProp​(java.util.Properties props,
                                          java.lang.String prop)
        Get the value of a boolean property. Print out the value if logging is enabled.
      • initStreams

        private void initStreams()
                          throws java.io.IOException
        Throws:
        java.io.IOException
      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable
      • setCapabilities

        void setCapabilities​(java.io.InputStream in)
        Parse the capabilities from a CAPA response.
      • hasCapability

        boolean hasCapability​(java.lang.String c)
        Check whether the given capability is supported by this server. Returns true if so, otherwise returns false.
      • getCapabilities

        java.util.Map<java.lang.String,​java.lang.String> getCapabilities()
        Return the map of capabilities returned by the server.
      • login

        java.lang.String login​(java.lang.String user,
                               java.lang.String password)
                        throws java.io.IOException
        Login to the server, using the USER and PASS commands.
        Throws:
        java.io.IOException
      • getDigest

        private java.lang.String getDigest​(java.lang.String password)
        Gets the APOP message digest. From RFC 1939: The 'digest' parameter is calculated by applying the MD5 algorithm [RFC1321] to a string consisting of the timestamp (including angle-brackets) followed by a shared secret. The 'digest' parameter itself is a 16-octet value which is sent in hexadecimal format, using lower-case ASCII characters.
        Parameters:
        password - The APOP password
        Returns:
        The APOP digest or an empty string if an error occurs.
      • toHex

        private static java.lang.String toHex​(byte[] bytes)
        Convert a byte array to a string of hex digits representing the bytes.
      • quit

        boolean quit()
              throws java.io.IOException
        Close down the connection, sending the QUIT command.
        Throws:
        java.io.IOException
      • close

        void close()
        Close the connection without sending any commands.
      • stat

        Status stat()
             throws java.io.IOException
        Return the total number of messages and mailbox size, using the STAT command.
        Throws:
        java.io.IOException
      • list

        int list​(int msg)
          throws java.io.IOException
        Return the size of the message using the LIST command.
        Throws:
        java.io.IOException
      • list

        java.io.InputStream list()
                          throws java.io.IOException
        Return the size of all messages using the LIST command.
        Throws:
        java.io.IOException
      • retr

        java.io.InputStream retr​(int msg,
                                 int size)
                          throws java.io.IOException
        Retrieve the specified message. Given an estimate of the message's size we can be more efficient, preallocating the array and returning a SharedInputStream to allow us to share the array.
        Throws:
        java.io.IOException
      • retr

        boolean retr​(int msg,
                     java.io.OutputStream os)
              throws java.io.IOException
        Retrieve the specified message and stream the content to the specified OutputStream. Return true on success.
        Throws:
        java.io.IOException
      • top

        java.io.InputStream top​(int msg,
                                int n)
                         throws java.io.IOException
        Return the message header and the first n lines of the message.
        Throws:
        java.io.IOException
      • dele

        boolean dele​(int msg)
              throws java.io.IOException
        Delete (permanently) the specified message.
        Throws:
        java.io.IOException
      • uidl

        java.lang.String uidl​(int msg)
                       throws java.io.IOException
        Return the UIDL string for the message.
        Throws:
        java.io.IOException
      • uidl

        boolean uidl​(java.lang.String[] uids)
              throws java.io.IOException
        Return the UIDL strings for all messages. The UID for msg #N is returned in uids[N-1].
        Throws:
        java.io.IOException
      • noop

        boolean noop()
              throws java.io.IOException
        Do a NOOP.
        Throws:
        java.io.IOException
      • rset

        boolean rset()
              throws java.io.IOException
        Do an RSET.
        Throws:
        java.io.IOException
      • stls

        boolean stls()
              throws java.io.IOException
        Start TLS using STLS command specified by RFC 2595. If already using SSL, this is a nop and the STLS command is not issued.
        Throws:
        java.io.IOException
      • isSSL

        boolean isSSL()
        Is this connection using SSL?
      • capa

        java.io.InputStream capa()
                          throws java.io.IOException
        Get server capabilities using CAPA command specified by RFC 2449. Returns null if not supported.
        Throws:
        java.io.IOException
      • simpleCommand

        private Response simpleCommand​(java.lang.String cmd)
                                throws java.io.IOException
        Issue a simple POP3 command and return the response.
        Throws:
        java.io.IOException
      • issueCommand

        private void issueCommand​(java.lang.String cmd)
                           throws java.io.IOException
        Send the specified command.
        Throws:
        java.io.IOException
      • readResponse

        private Response readResponse()
                               throws java.io.IOException
        Read the response to a command.
        Throws:
        java.io.IOException
      • multilineCommand

        private Response multilineCommand​(java.lang.String cmd,
                                          int size)
                                   throws java.io.IOException
        Issue a POP3 command that expects a multi-line response. size is an estimate of the response size.
        Throws:
        java.io.IOException
      • readMultilineResponse

        private java.io.InputStream readMultilineResponse​(int size)
                                                   throws java.io.IOException
        Read the response to a multiline command after the command response. The size parameter indicates the expected size of the response; the actual size can be different. Returns an InputStream to the response bytes.
        Throws:
        java.io.IOException
      • isTracing

        protected boolean isTracing()
        Is protocol tracing enabled?
      • suspendTracing

        private void suspendTracing()
        Temporarily turn off protocol tracing, e.g., to prevent tracing the authentication sequence, including the password.
      • resumeTracing

        private void resumeTracing()
        Resume protocol tracing, if it was enabled to begin with.
      • simpleCommandStart

        private void simpleCommandStart​(java.lang.String command)
      • simpleCommandEnd

        private void simpleCommandEnd()
      • multilineCommandStart

        private void multilineCommandStart​(java.lang.String command)
      • multilineCommandEnd

        private void multilineCommandEnd()
      • batchCommandStart

        private void batchCommandStart​(java.lang.String command)
      • batchCommandContinue

        private void batchCommandContinue​(java.lang.String command)
      • batchCommandEnd

        private void batchCommandEnd()