UnifiedServerSocket (Apache ZooKeeper - Server 3.7.0 API)
Date: 2021-03-17

org.apache.zookeeper.server.quorum

## Class UnifiedServerSocket

- java.lang.Object
- - java.net.ServerSocket
  - - org.apache.zookeeper.server.quorum.UnifiedServerSocket

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class UnifiedServerSocket
      extends ServerSocket

  A ServerSocket that can act either as a regular ServerSocket, as a SSLServerSocket, or as both, depending on the constructor parameters and on the type of client (TLS or plaintext) that connects to it. The constructors have the same signature as constructors of ServerSocket, with the addition of two parameters at the beginning:
  - X509Util - provides the SSL context to construct a secure socket when a client connects with TLS.
  - boolean allowInsecureConnection - when true, acts as a hybrid server socket (plaintext / TLS). When false, acts as a SSLServerSocket (rejects plaintext connections).
  The `!allowInsecureConnection` mode is needed so we can update the SSLContext (in particular, the key store and/or trust store) without having to re-create the server socket. By starting with a plaintext socket and delaying the upgrade to TLS until after a client has connected and begins a handshake, we can keep the same UnifiedServerSocket instance around, and replace the default SSLContext in the provided X509Util when the key store and/or trust store file changes on disk.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `UnifiedServerSocket.UnifiedSocket` The result of calling accept() on a UnifiedServerSocket.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UnifiedServerSocket(X509Util x509Util, boolean allowInsecureConnection)` Creates an unbound unified server socket by calling `ServerSocket()`.
    `UnifiedServerSocket(X509Util x509Util, boolean allowInsecureConnection, int port)` Creates a unified server socket bound to the specified port by calling `ServerSocket(int)`.
    `UnifiedServerSocket(X509Util x509Util, boolean allowInsecureConnection, int port, int backlog)` Creates a unified server socket bound to the specified port, with the specified backlog, by calling `ServerSocket(int, int)`.
    `UnifiedServerSocket(X509Util x509Util, boolean allowInsecureConnection, int port, int backlog, InetAddress bindAddr)` Creates a unified server socket bound to the specified port, with the specified backlog, and local IP address to bind to, by calling `ServerSocket(int, int, InetAddress)`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Socket` | `accept()`

    - ### Methods inherited from class java.net.ServerSocket

      `bind, bind, close, getChannel, getInetAddress, getLocalPort, getLocalSocketAddress, getReceiveBufferSize, getReuseAddress, getSoTimeout, implAccept, isBound, isClosed, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSocketFactory, setSoTimeout, toString`

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

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

- - ### Constructor Detail

    - #### UnifiedServerSocket

          public UnifiedServerSocket(X509Util x509Util,
                                     boolean allowInsecureConnection)
                              throws IOException

      Creates an unbound unified server socket by calling `ServerSocket()`. Secure client connections will be upgraded to TLS once this socket detects the ClientHello message (start of a TLS handshake). Plaintext client connections will either be accepted or rejected depending on the value of the `allowInsecureConnection` parameter.
      Parameters:
        `x509Util` - the X509Util that provides the SSLContext to use for secure connections.
        `allowInsecureConnection` - if true, accept plaintext connections, otherwise close them.
      Throws:
        `IOException` - if `ServerSocket()` throws.

    - #### UnifiedServerSocket

          public UnifiedServerSocket(X509Util x509Util,
                                     boolean allowInsecureConnection,
                                     int port)
                              throws IOException

      Creates a unified server socket bound to the specified port by calling `ServerSocket(int)`. Secure client connections will be upgraded to TLS once this socket detects the ClientHello message (start of a TLS handshake). Plaintext client connections will either be accepted or rejected depending on the value of the `allowInsecureConnection` parameter.
      Parameters:
        `x509Util` - the X509Util that provides the SSLContext to use for secure connections.
        `allowInsecureConnection` - if true, accept plaintext connections, otherwise close them.
        `port` - the port number, or `0` to use a port number that is automatically allocated.
      Throws:
        `IOException` - if `ServerSocket(int)` throws.

    - #### UnifiedServerSocket

          public UnifiedServerSocket(X509Util x509Util,
                                     boolean allowInsecureConnection,
                                     int port,
                                     int backlog)
                              throws IOException

      Creates a unified server socket bound to the specified port, with the specified backlog, by calling `ServerSocket(int, int)`. Secure client connections will be upgraded to TLS once this socket detects the ClientHello message (start of a TLS handshake). Plaintext client connections will either be accepted or rejected depending on the value of the `allowInsecureConnection` parameter.
      Parameters:
        `x509Util` - the X509Util that provides the SSLContext to use for secure connections.
        `allowInsecureConnection` - if true, accept plaintext connections, otherwise close them.
        `port` - the port number, or `0` to use a port number that is automatically allocated.
        `backlog` - requested maximum length of the queue of incoming connections.
      Throws:
        `IOException` - if `ServerSocket(int, int)` throws.

    - #### UnifiedServerSocket

          public UnifiedServerSocket(X509Util x509Util,
                                     boolean allowInsecureConnection,
                                     int port,
                                     int backlog,
                                     InetAddress bindAddr)
                              throws IOException

      Creates a unified server socket bound to the specified port, with the specified backlog, and local IP address to bind to, by calling `ServerSocket(int, int, InetAddress)`. Secure client connections will be upgraded to TLS once this socket detects the ClientHello message (start of a TLS handshake). Plaintext client connections will either be accepted or rejected depending on the value of the `allowInsecureConnection` parameter.
      Parameters:
        `x509Util` - the X509Util that provides the SSLContext to use for secure connections.
        `allowInsecureConnection` - if true, accept plaintext connections, otherwise close them.
        `port` - the port number, or `0` to use a port number that is automatically allocated.
        `backlog` - requested maximum length of the queue of incoming connections.
        `bindAddr` - the local InetAddress the server will bind to.
      Throws:
        `IOException` - if `ServerSocket(int, int, InetAddress)` throws.

  - ### Method Detail

    - #### accept

          public Socket accept()
                        throws IOException

      Overrides:
        `accept` in class `ServerSocket`
      Throws:
        `IOException`

Copyright © 2008–2021 The Apache Software Foundation. All rights reserved.