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 and Description
    --- | ---
    `static int` | `DEFAULT_IMAPS_PORT` The default IMAP over SSL port.
    `static 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 and Description
    `IMAPSClient()` Constructor for IMAPSClient.
    `IMAPSClient(boolean implicit)` Constructor for IMAPSClient.
    `IMAPSClient(boolean implicit, SSLContext ctx)` Constructor for IMAPSClient.
    `IMAPSClient(SSLContext context)` 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.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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()` Gets the names of the cipher suites which could be enabled for use on this connection.
    `String[]` | `getEnabledProtocols()` Gets the names of the protocol versions which are currently enabled for use on this connection.
    `HostnameVerifier` | `getHostnameVerifier()` Gets the currently configured `HostnameVerifier`.
    `TrustManager` | `getTrustManager()` Gets the currently configured `TrustManager`.
    `boolean` | `isEndpointCheckingEnabled()` Tests whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled.
    `void` | `setEnabledCipherSuites(String[] cipherSuites)` Sets which particular cipher suites are enabled for use on this connection.
    `void` | `setEnabledProtocols(String[] protocolVersions)` Sets which particular protocol versions are enabled for use on this connection.
    `void` | `setEndpointCheckingEnabled(boolean enable)` Sets automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+.
    `void` | `setHostnameVerifier(HostnameVerifier newHostnameVerifier)` Sets to override the default `HostnameVerifier` to use.
    `void` | `setKeyManager(KeyManager newKeyManager)` Sets a `KeyManager` to use.
    `void` | `setTrustManager(TrustManager newTrustManager)` Sets to override the default `TrustManager` to use.

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

      `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, quoteMailboxName, sendCommand, sendCommand, sendCommand, sendCommand, sendData, setChunkListener, setState`

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

      `addProtocolCommandListener, applySocketAttributes, checkOpenOutputStream, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, getCharset, getCommandSupport, getConnectTimeout, getDefaultPort, getDefaultTimeout, getHostAddress, getHostAddress, 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 Detail

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

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

    - #### _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()

      Gets 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()

      Gets 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()

      Gets the currently configured `HostnameVerifier`.
      Returns:
        A HostnameVerifier instance.

    - #### getTrustManager

          public TrustManager getTrustManager()

      Gets the currently configured `TrustManager`.
      Returns:
        A TrustManager instance.

    - #### isEndpointCheckingEnabled

          public boolean isEndpointCheckingEnabled()

      Tests 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.

    - #### setEnabledCipherSuites

          public void setEnabledCipherSuites(String[] cipherSuites)

      Sets 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)

      Sets 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)

      Sets 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+.

    - #### setHostnameVerifier

          public void setHostnameVerifier(HostnameVerifier newHostnameVerifier)

      Sets to override the default `HostnameVerifier` to use.
      Parameters:
        `newHostnameVerifier` - The HostnameVerifier implementation to set or `null` to disable.

    - #### setKeyManager

          public void setKeyManager(KeyManager newKeyManager)

      Sets a `KeyManager` to use.
      Parameters:
        `newKeyManager` - The KeyManager implementation to set.
      See Also:
        `KeyManagerUtils`

    - #### setTrustManager

          public void setTrustManager(TrustManager newTrustManager)

      Sets to override the default `TrustManager` to use.
      Parameters:
        `newTrustManager` - The TrustManager implementation to set.
      See Also:
        `TrustManagerUtils`