Package org.apache.commons.net.imap

# Class IMAPSClient

java.lang.Object
org.apache.commons.net.SocketClient
org.apache.commons.net.imap.IMAP
org.apache.commons.net.imap.IMAPClient
org.apache.commons.net.imap.IMAPSClient

Direct Known Subclasses:
  `AuthenticatingIMAPClient`

public class IMAPSClient extends IMAPClient
The IMAPSClient class provides SSL/TLS connection encryption to IMAPClient. Copied from FTPSClient and modified to suit IMAP. If implicit mode is selected (NOT the default), SSL/TLS negotiation starts right after the connection has been established. In explicit mode (the default), SSL/TLS negotiation starts when the user calls execTLS() and the server accepts the command.

     //Implicit usage:

                   IMAPSClient c = new IMAPSClient(true);
                   c.connect("127.0.0.1", 993);

     //Explicit usage:

                   IMAPSClient c = new IMAPSClient();
                   c.connect("127.0.0.1", 143);
                   if (c.execTLS()) { /rest of the commands here/ }

Warning: the hostname is not verified against the certificate by default, use `setHostnameVerifier(HostnameVerifier)` or `setEndpointCheckingEnabled(boolean)` (on Java 1.7+) to enable verification.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.commons.net.imap.IMAPClient

  `IMAPClient.FETCH_ITEM_NAMES, IMAPClient.SEARCH_CRITERIA, IMAPClient.STATUS_DATA_ITEMS`

  ## Nested classes/interfaces inherited from class org.apache.commons.net.imap.IMAP

  `IMAP.IMAPChunkListener, IMAP.IMAPState`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_IMAPS_PORT`
  The default IMAP over SSL port.
  `static final String`
  `DEFAULT_PROTOCOL`
  Default secure socket protocol name.

  ### Fields inherited from class org.apache.commons.net.imap.IMAP

  `__DEFAULT_ENCODING, __writer, _reader, DEFAULT_PORT, TRUE_CHUNK_LISTENER`

  ### Fields inherited from class org.apache.commons.net.SocketClient

  `_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL, remoteInetSocketAddress`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `IMAPSClient()`
  Constructor for IMAPSClient.
  `IMAPSClient(boolean implicit)`
  Constructor for IMAPSClient.
  `IMAPSClient(boolean implicit, SSLContext ctx)`
  Constructor for IMAPSClient.
  `IMAPSClient(String proto)`
  Constructor for IMAPSClient.
  `IMAPSClient(String proto, boolean implicit)`
  Constructor for IMAPSClient.
  `IMAPSClient(String proto, boolean implicit, SSLContext ctx)`
  Constructor for IMAPSClient.
  `IMAPSClient(SSLContext context)`
  Constructor for IMAPSClient.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `_connectAction_()`
  Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all the connect() methods.
  `boolean`
  `execTLS()`
  The TLS command execution.
  `String[]`
  `getEnabledCipherSuites()`
  Returns the names of the cipher suites which could be enabled for use on this connection.
  `String[]`
  `getEnabledProtocols()`
  Returns the names of the protocol versions which are currently enabled for use on this connection.
  `HostnameVerifier`
  `getHostnameVerifier()`
  Get the currently configured `HostnameVerifier`.
  `TrustManager`
  `getTrustManager()`
  Get the currently configured `TrustManager`.
  `boolean`
  `isEndpointCheckingEnabled()`
  Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled.
  `void`
  `setEnabledCipherSuites(String[] cipherSuites)`
  Controls which particular cipher suites are enabled for use on this connection.
  `void`
  `setEnabledProtocols(String[] protocolVersions)`
  Controls which particular protocol versions are enabled for use on this connection.
  `void`
  `setEndpointCheckingEnabled(boolean enable)`
  Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+.
  `void`
  `setHostnameVerifier(HostnameVerifier newHostnameVerifier)`
  Override the default `HostnameVerifier` to use.
  `void`
  `setKeyManager(KeyManager newKeyManager)`
  Set a `KeyManager` to use.
  `void`
  `setTrustManager(TrustManager newTrustManager)`
  Override the default `TrustManager` to use.

  ### Methods inherited from class org.apache.commons.net.imap.IMAPClient

  `append, append, append, capability, check, close, copy, create, delete, examine, expunge, fetch, list, login, logout, lsub, noop, rename, search, search, select, status, store, subscribe, uid, unsubscribe`

  ### Methods inherited from class org.apache.commons.net.imap.IMAP

  `disconnect, doCommand, doCommand, fireReplyReceived, generateCommandID, getReplyString, getReplyStrings, getState, sendCommand, sendCommand, sendCommand, sendCommand, sendData, setChunkListener, setState`

  ### Methods inherited from class org.apache.commons.net.SocketClient

  `addProtocolCommandListener, applySocketAttributes, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, getCharset, getCharsetName, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemoteInetSocketAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote`

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

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

- ## Field Details

  - ### DEFAULT_IMAPS_PORT

    public static final int DEFAULT_IMAPS_PORT
    The default IMAP over SSL port.
    See Also:
      - Constant Field Values

  - ### DEFAULT_PROTOCOL

    public static final String DEFAULT_PROTOCOL
    Default secure socket protocol name.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### IMAPSClient

    public IMAPSClient()
    Constructor for IMAPSClient. Sets security mode to explicit (isImplicit = false).

  - ### IMAPSClient

    public IMAPSClient(boolean implicit)
    Constructor for IMAPSClient.
    Parameters:
      `implicit` - The security mode (Implicit/Explicit).

  - ### IMAPSClient

    public IMAPSClient(boolean implicit, SSLContext ctx)
    Constructor for IMAPSClient.
    Parameters:
      `implicit` - The security mode(Implicit/Explicit).
      `ctx` - A pre-configured SSL Context.

  - ### IMAPSClient

    public IMAPSClient(SSLContext context)
    Constructor for IMAPSClient.
    Parameters:
      `context` - A pre-configured SSL Context.

  - ### IMAPSClient

    public IMAPSClient(String proto)
    Constructor for IMAPSClient.
    Parameters:
      `proto` - the protocol.

  - ### IMAPSClient

    public IMAPSClient(String proto, boolean implicit)
    Constructor for IMAPSClient.
    Parameters:
      `proto` - the protocol.
      `implicit` - The security mode(Implicit/Explicit).

  - ### IMAPSClient

    public IMAPSClient(String proto, boolean implicit, SSLContext ctx)
    Constructor for IMAPSClient.
    Parameters:
      `proto` - the protocol.
      `implicit` - The security mode(Implicit/Explicit).
      `ctx` - the SSL context

- ## Method Details

  - ### _connectAction_

    protected void _connectAction_() throws IOException
    Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all the connect() methods.
    Overrides:
      `_connectAction_` in class `IMAP`
    Throws:
      `IOException` - If it is thrown by _connectAction_().
    See Also:
      - `SocketClient._connectAction_()`

  - ### execTLS

    public boolean execTLS() throws SSLException, IOException
    The TLS command execution.
    Returns:
      TRUE if the command and negotiation succeeded.
    Throws:
      `SSLException` - If the server reply code is not positive.
      `IOException` - If an I/O error occurs while sending the command or performing the negotiation.

  - ### getEnabledCipherSuites

    public String[] getEnabledCipherSuites()
    Returns the names of the cipher suites which could be enabled for use on this connection. When the underlying `Socket` is not an `SSLSocket` instance, returns null.
    Returns:
      An array of cipher suite names, or `null`.

  - ### getEnabledProtocols

    public String[] getEnabledProtocols()
    Returns the names of the protocol versions which are currently enabled for use on this connection. When the underlying `Socket` is not an `SSLSocket` instance, returns null.
    Returns:
      An array of protocols, or `null`.

  - ### getHostnameVerifier

    public HostnameVerifier getHostnameVerifier()
    Get the currently configured `HostnameVerifier`.
    Returns:
      A HostnameVerifier instance.
    Since:
      3.4

  - ### getTrustManager

    public TrustManager getTrustManager()
    Get the currently configured `TrustManager`.
    Returns:
      A TrustManager instance.

  - ### isEndpointCheckingEnabled

    public boolean isEndpointCheckingEnabled()
    Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled. The default behavior is for this to be disabled.
    Returns:
      True if enabled, false if not.
    Since:
      3.4

  - ### setEnabledCipherSuites

    public void setEnabledCipherSuites(String[] cipherSuites)
    Controls which particular cipher suites are enabled for use on this connection. Called before server negotiation.
    Parameters:
      `cipherSuites` - The cipher suites.

  - ### setEnabledProtocols

    public void setEnabledProtocols(String[] protocolVersions)
    Controls which particular protocol versions are enabled for use on this connection. I perform setting before a server negotiation.
    Parameters:
      `protocolVersions` - The protocol versions.

  - ### setEndpointCheckingEnabled

    public void setEndpointCheckingEnabled(boolean enable)
    Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+. The default behavior is for this to be disabled.
    Parameters:
      `enable` - Enable automatic endpoint identification checking using the HTTPS algorithm on Java 1.7+.
    Since:
      3.4

  - ### setHostnameVerifier

    public void setHostnameVerifier(HostnameVerifier newHostnameVerifier)
    Override the default `HostnameVerifier` to use.
    Parameters:
      `newHostnameVerifier` - The HostnameVerifier implementation to set or `null` to disable.
    Since:
      3.4

  - ### setKeyManager

    public void setKeyManager(KeyManager newKeyManager)
    Set a `KeyManager` to use.
    Parameters:
      `newKeyManager` - The KeyManager implementation to set.
    See Also:
      - `KeyManagerUtils`

  - ### setTrustManager

    public void setTrustManager(TrustManager newTrustManager)
    Override the default `TrustManager` to use.
    Parameters:
      `newTrustManager` - The TrustManager implementation to set.
    See Also:
      - `TrustManagerUtils`