com.sun.mail.iap

## Class Protocol

- java.lang.Object
- - com.sun.mail.iap.Protocol

- Direct Known Subclasses:
    IMAPProtocol

      public class Protocol
      extends Object

  General protocol handling code for IMAP-like protocols.

  The Protocol object is multithread safe.

  Author:
    John Mani, Max Spivak, Bill Shannon

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `host`
    `protected MailLogger` | `logger`
    `protected String` | `prefix`
    `protected Properties` | `props`
    `protected boolean` | `quote`
    `protected MailLogger` | `traceLogger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Protocol(InputStream in, PrintStream out, Properties props, boolean debug)` Constructor for debugging.
    `Protocol(String host, int port, Properties props, String prefix, boolean isSSL, MailLogger logger)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addResponseHandler(ResponseHandler h)` Adds a response handler.
    `Response[]` | `command(String command, Argument args)` Send a command to the server.
    `protected void` | `disconnect()` Disconnect.
    `protected void` | `finalize()` Finalizer.
    `SocketChannel` | `getChannel()` Return the SocketChannel associated with this connection, if any.
    `InetAddress` | `getInetAddress()` Return the address the socket connected to.
    `protected ResponseInputStream` | `getInputStream()` Return the Protocol's InputStream.
    `protected String` | `getLocalHost()` Get the name of the local host.
    `protected OutputStream` | `getOutputStream()` Return the Protocol's OutputStream
    `protected ByteArray` | `getResponseBuffer()` Return a buffer to be used to read a response.
    `long` | `getTimestamp()` Returns the timestamp.
    `void` | `handleResult(Response response)` Convenience routine to handle OK, NO, BAD and BYE responses.
    `boolean` | `hasResponse()` Is another response available in our buffer?
    `boolean` | `isSSL()` Is this connection using an SSL socket?
    `protected boolean` | `isTracing()` Is protocol tracing enabled?
    `void` | `notifyResponseHandlers(Response[] responses)` Notify response handlers
    `protected void` | `processGreeting(Response r)`
    `Response` | `readResponse()`
    `void` | `removeResponseHandler(ResponseHandler h)` Removed the specified response handler.
    `protected void` | `resumeTracing()` Resume protocol tracing, if it was enabled to begin with.
    `void` | `simpleCommand(String cmd, Argument args)` Convenience routine to handle simple IAP commands that do not have responses specific to that command.
    `void` | `startCompression(String cmd)` Start compression on the current connection.
    `void` | `startTLS(String cmd)` Start TLS on the current connection.
    `protected boolean` | `supportsNonSyncLiterals()` Returns whether this Protocol supports non-synchronizing literals Default is false.
    `protected void` | `suspendTracing()` Temporarily turn off protocol tracing, e.g., to prevent tracing the authentication sequence, including the password.
    `String` | `writeCommand(String command, Argument args)`

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

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

- - ### Field Detail

    - #### host

          protected String host

    - #### quote

          protected boolean quote

    - #### logger

          protected MailLogger logger

    - #### traceLogger

          protected MailLogger traceLogger

    - #### props

          protected Properties props

    - #### prefix

          protected String prefix

  - ### Constructor Detail

    - #### Protocol

          public Protocol(String host,
                  int port,
                  Properties props,
                  String prefix,
                  boolean isSSL,
                  MailLogger logger)
                   throws IOException,
                          ProtocolException

      Constructor.

      Opens a connection to the given host at given port.

      Parameters:
        `host` - host to connect to
        `port` - portnumber to connect to
        `props` - Properties object used by this protocol
        `prefix` - Prefix to prepend to property keys
        `isSSL` - use SSL?
        `logger` - log messages here
      Throws:
        `IOException` - for I/O errors
        `ProtocolException` - for protocol failures

    - #### Protocol

          public Protocol(InputStream in,
                  PrintStream out,
                  Properties props,
                  boolean debug)
                   throws IOException

      Constructor for debugging.
      Parameters:
        `in` - the InputStream to read from
        `out` - the PrintStream to write to
        `props` - Properties object used by this protocol
        `debug` - true to enable debugging output
      Throws:
        `IOException` - for I/O errors

  - ### Method Detail

    - #### getTimestamp

          public long getTimestamp()

      Returns the timestamp.
      Returns:
        the timestamp

    - #### addResponseHandler

          public void addResponseHandler(ResponseHandler h)

      Adds a response handler.
      Parameters:
        `h` - the response handler

    - #### removeResponseHandler

          public void removeResponseHandler(ResponseHandler h)

      Removed the specified response handler.
      Parameters:
        `h` - the response handler

    - #### notifyResponseHandlers

          public void notifyResponseHandlers(Response[] responses)

      Notify response handlers
      Parameters:
        `responses` - the responses

    - #### processGreeting

          protected void processGreeting(Response r)
                                  throws ProtocolException

      Throws:
        `ProtocolException`

    - #### getInputStream

          protected ResponseInputStream getInputStream()

      Return the Protocol's InputStream.
      Returns:
        the input stream

    - #### getOutputStream

          protected OutputStream getOutputStream()

      Return the Protocol's OutputStream
      Returns:
        the output stream

    - #### supportsNonSyncLiterals

          protected boolean supportsNonSyncLiterals()

      Returns whether this Protocol supports non-synchronizing literals Default is false. Subclasses should override this if required
      Returns:
        true if the server supports non-synchronizing literals

    - #### readResponse

          public Response readResponse()
                                throws IOException,
                                       ProtocolException

      Throws:
        `IOException`
        `ProtocolException`

    - #### hasResponse

          public boolean hasResponse()

      Is another response available in our buffer?
      Returns:
        true if another response is in the buffer
      Since:
        JavaMail 1.5.4

    - #### getResponseBuffer

          protected ByteArray getResponseBuffer()

      Return a buffer to be used to read a response. The default implementation returns null, which causes a new buffer to be allocated for every response.
      Returns:
        the buffer to use
      Since:
        JavaMail 1.4.1

    - #### writeCommand

          public String writeCommand(String command,
                            Argument args)
                              throws IOException,
                                     ProtocolException

      Throws:
        `IOException`
        `ProtocolException`

    - #### command

          public Response[] command(String command,
                           Argument args)

      Send a command to the server. Collect all responses until either the corresponding command completion response or a BYE response (indicating server failure). Return all the collected responses.
      Parameters:
        `command` - the command
        `args` - the arguments
      Returns:
        array of Response objects returned by the server

    - #### handleResult

          public void handleResult(Response response)
                            throws ProtocolException

      Convenience routine to handle OK, NO, BAD and BYE responses.
      Parameters:
        `response` - the response
      Throws:
        `ProtocolException` - for protocol failures

    - #### simpleCommand

          public void simpleCommand(String cmd,
                           Argument args)
                             throws ProtocolException

      Convenience routine to handle simple IAP commands that do not have responses specific to that command.
      Parameters:
        `cmd` - the command
        `args` - the arguments
      Throws:
        `ProtocolException` - for protocol failures

    - #### startTLS

          public void startTLS(String cmd)
                        throws IOException,
                               ProtocolException

      Start TLS on the current connection. `cmd` is the command to issue to start TLS negotiation. If the command succeeds, we begin TLS negotiation. If the socket is already an SSLSocket this is a nop and the command is not issued.
      Parameters:
        `cmd` - the command to issue
      Throws:
        `IOException` - for I/O errors
        `ProtocolException` - for protocol failures

    - #### startCompression

          public void startCompression(String cmd)
                                throws IOException,
                                       ProtocolException

      Start compression on the current connection. `cmd` is the command to issue to start compression. If the command succeeds, we begin compression.
      Parameters:
        `cmd` - the command to issue
      Throws:
        `IOException` - for I/O errors
        `ProtocolException` - for protocol failures

    - #### isSSL

          public boolean isSSL()

      Is this connection using an SSL socket?
      Returns:
        true if using SSL
      Since:
        JavaMail 1.4.6

    - #### getInetAddress

          public InetAddress getInetAddress()

      Return the address the socket connected to.
      Returns:
        the InetAddress the socket is connected to
      Since:
        JavaMail 1.5.2

    - #### getChannel

          public SocketChannel getChannel()

      Return the SocketChannel associated with this connection, if any.
      Returns:
        the SocketChannel
      Since:
        JavaMail 1.5.2

    - #### disconnect

          protected void disconnect()

      Disconnect.

    - #### getLocalHost

          protected String getLocalHost()

      Get the name of the local host. The property <prefix>.localhost overrides <prefix>.localaddress, which overrides what InetAddress would tell us.
      Returns:
        the name of the local host

    - #### isTracing

          protected boolean isTracing()

      Is protocol tracing enabled?
      Returns:
        true if protocol tracing is enabled

    - #### suspendTracing

          protected void suspendTracing()

      Temporarily turn off protocol tracing, e.g., to prevent tracing the authentication sequence, including the password.

    - #### resumeTracing

          protected void resumeTracing()

      Resume protocol tracing, if it was enabled to begin with.

    - #### finalize

          protected void finalize()
                           throws Throwable

      Finalizer.
      Overrides:
        `finalize` in class `Object`
      Throws:
        `Throwable`

Copyright © 2016 Oracle. All rights reserved.