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
Modifier and Type
Field
Description
`protected String`
`host`
`protected MailLogger`
`logger`
`protected String`
`prefix`
`protected Properties`
`props`
`protected boolean`
`quote`
`protected MailLogger`
`traceLogger`

## Constructor Summary

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

Modifier and Type
Method
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.
`SocketAddress`
`getLocalSocketAddress()`
Return the local SocketAddress (host and port) for this end of the connection.
`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 Details

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

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

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

### getLocalSocketAddress

public SocketAddress getLocalSocketAddress()
Return the local SocketAddress (host and port) for this end of the connection.

Returns:
  the SocketAddress
Since:
  Jakarta Mail 1.6.4

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