Package org.apache.commons.net.pop3

# Class POP3SClient

java.lang.Object
org.apache.commons.net.SocketClient
org.apache.commons.net.pop3.POP3
org.apache.commons.net.pop3.POP3Client
org.apache.commons.net.pop3.POP3SClient

Direct Known Subclasses:
  `ExtendedPOP3Client`

public class POP3SClient extends POP3Client
POP3 over SSL processing. Copied from FTPSClient.java and modified to suit POP3. 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: POP3SClient c = new POP3SClient(true); c.connect("127.0.0.1", 995); Explicit usage: POP3SClient c = new POP3SClient(); c.connect("127.0.0.1", 110); 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.

Since:
  3.0

- ## Field Summary

  ### Fields inherited from class org.apache.commons.net.pop3.POP3

  `_commandSupport_, AUTHORIZATION_STATE, DEFAULT_PORT, DISCONNECTED_STATE, TRANSACTION_STATE, UPDATE_STATE`

  ### 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
  `POP3SClient()`
  Constructor for POP3SClient, using `DEFAULT_PROTOCOL` i.e.
  `POP3SClient(boolean implicit)`
  Constructor for POP3SClient, using `DEFAULT_PROTOCOL` i.e.
  `POP3SClient(boolean implicit, SSLContext ctx)`
  Constructor for POP3SClient, using `DEFAULT_PROTOCOL` i.e.
  `POP3SClient(String proto)`
  Constructor for POP3SClient.
  `POP3SClient(String proto, boolean implicit)`
  Constructor for POP3SClient.
  `POP3SClient(String proto, boolean implicit, SSLContext ctx)`
  Constructor for POP3SClient.
  `POP3SClient(SSLContext context)`
  Constructor for POP3SClient, using `DEFAULT_PROTOCOL` - TLS - and isImplicit = false

- ## 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()`
  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.pop3.POP3Client

  `capa, deleteMessage, listMessage, listMessages, listUniqueIdentifier, listUniqueIdentifiers, login, login, logout, noop, reset, retrieveMessage, retrieveMessageTop, status`

  ### Methods inherited from class org.apache.commons.net.pop3.POP3

  `disconnect, getAdditionalReply, getCommandSupport, getReplyString, getReplyStrings, getState, removeProtocolCommandistener, sendCommand, sendCommand, sendCommand, sendCommand, setState`

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

  `addProtocolCommandListener, applySocketAttributes, checkOpenOutputStream, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCharset, getCharsetName, 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`

- ## Constructor Details

  - ### POP3SClient

    public POP3SClient()
    Constructor for POP3SClient, using `DEFAULT_PROTOCOL` i.e. TLS Sets security mode to explicit.

  - ### POP3SClient

    public POP3SClient(boolean implicit)
    Constructor for POP3SClient, using `DEFAULT_PROTOCOL` i.e. TLS
    Parameters:
      `implicit` - The security mode, `true` for implicit, `false` for explicit

  - ### POP3SClient

    public POP3SClient(boolean implicit, SSLContext ctx)
    Constructor for POP3SClient, using `DEFAULT_PROTOCOL` i.e. TLS
    Parameters:
      `implicit` - The security mode, `true` for implicit, `false` for explicit
      `ctx` - A pre-configured SSL Context.

  - ### POP3SClient

    public POP3SClient(SSLContext context)
    Constructor for POP3SClient, using `DEFAULT_PROTOCOL` - TLS - and isImplicit = false
    Parameters:
      `context` - A pre-configured SSL Context.
    See Also:
      - `POP3SClient(boolean, SSLContext)`

  - ### POP3SClient

    public POP3SClient(String proto)
    Constructor for POP3SClient. Sets security mode to explicit.
    Parameters:
      `proto` - the protocol.

  - ### POP3SClient

    public POP3SClient(String proto, boolean implicit)
    Constructor for POP3SClient.
    Parameters:
      `proto` - the protocol.
      `implicit` - The security mode, `true` for implicit, `false` for explicit

  - ### POP3SClient

    public POP3SClient(String proto, boolean implicit, SSLContext ctx)
    Constructor for POP3SClient. Sets the default port to `DEFAULT_POP3S_PORT` - 995 - if using implicit mode
    Parameters:
      `proto` - the protocol.
      `implicit` - The security mode, `true` for implicit, `false` for explicit
      `ctx` - the context to be used

- ## 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 `POP3`
    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.
    Since:
      3.4

  - ### 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.
    Since:
      3.4

  - ### 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+.
    Since:
      3.4

  - ### 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.
    Since:
      3.4

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