POP3SClient (Apache Commons Net 3.4 API)

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`

  - ### Constructor Summary

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

  - ### Method Summary

    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 of 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.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, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCharset, getCharsetName, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, 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 Detail

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

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

  - ### 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 of the connect() methods.
      Overrides:
        `_connectAction_` in class `POP3`
      Throws:
        `IOException` - If it is thrown by _connectAction_().
      See Also:
        `SocketClient._connectAction_()`

    - #### setKeyManager

          public void setKeyManager(KeyManager newKeyManager)

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

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

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

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

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

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

    - #### getTrustManager

          public TrustManager getTrustManager()

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

    - #### setTrustManager

          public void setTrustManager(TrustManager newTrustManager)

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

    - #### getHostnameVerifier

          public HostnameVerifier getHostnameVerifier()

      Get the currently configured `HostnameVerifier`.
      Returns:
        A HostnameVerifier instance.
      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

    - #### isEndpointCheckingEnabled

          public boolean isEndpointCheckingEnabled()

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

    - #### setEndpointCheckingEnabled

          public void setEndpointCheckingEnabled(boolean enable)

      Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+. The default behaviour is for this to be disabled.
      Parameters:
        `enable` - Enable automatic endpoint identification checking using the HTTPS algorithm on Java 1.7+.
      Since:
        3.4

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.