Package 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
`protected String` `host`
`protected MailLogger` `logger`
`protected String` `prefix`
`protected Properties` `props`
`protected boolean` `quote`
`protected MailLogger` `traceLogger`

### Constructor Summary

Constructors
`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

All Methods Instance Methods Concrete Methods
`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.
`boolean` `supportsUtf8​()` Does the server support UTF-8? This implementation returns 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

#### supportsUtf8

    public boolean supportsUtf8​()

Does the server support UTF-8? This implementation returns false. Subclasses should override as appropriate.

Returns:
  true if the server supports UTF-8
Since:
  JavaMail 1.6.0

#### 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`