SocketOptions (Java SE 23 & JDK 23)
Description: declaration: module: java.base, package: java.net, interface: SocketOptions
Keywords: java.net.SocketOptions interface

# Interface SocketOptions

All Known Implementing Classes:
  `DatagramSocketImpl`, `SocketImpl`

public interface SocketOptions
Interface of methods to get/set socket options. This interface is implemented by `SocketImpl` and `DatagramSocketImpl`. Subclasses of these two classes should override the `getOption(int)` and `setOption(int, Object)` methods of this interface in order to support their own options.

The methods and constants defined in this interface are for implementation only. If you're not subclassing `SocketImpl` or `DatagramSocketImpl`, then you won't use these directly. There are type-safe methods to get/set each of these options in `Socket`, `ServerSocket`, `DatagramSocket` and `MulticastSocket`.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `IP_MULTICAST_IF`
  See `StandardSocketOptions.IP_MULTICAST_IF` for description of this socket option.
  `static final int`
  `IP_MULTICAST_IF2`
  This option is used to both set and fetch the outgoing interface on which the multicast packets are sent.
  `static final int`
  `IP_MULTICAST_LOOP`
  See `StandardSocketOptions.IP_MULTICAST_LOOP` for description of this socket option.
  `static final int`
  `IP_TOS`
  See `StandardSocketOptions.IP_TOS` for description of this socket option.
  `static final int`
  `SO_BINDADDR`
  Fetch the local address binding of a socket.
  `static final int`
  `SO_BROADCAST`
  See `StandardSocketOptions.SO_BROADCAST` for description of this socket option.
  `static final int`
  `SO_KEEPALIVE`
  See `StandardSocketOptions.SO_KEEPALIVE` for description of this socket option.
  `static final int`
  `SO_LINGER`
  See `StandardSocketOptions.SO_LINGER` for description of this socket option.
  `static final int`
  `SO_OOBINLINE`
  When this option is set, any TCP urgent data received on the socket will be received through the socket input stream.
  `static final int`
  `SO_RCVBUF`
  See `StandardSocketOptions.SO_RCVBUF` for description of this socket option.
  `static final int`
  `SO_REUSEADDR`
  See `StandardSocketOptions.SO_REUSEADDR` for description of this socket option.
  `static final int`
  `SO_REUSEPORT`
  See `StandardSocketOptions.SO_REUSEPORT` for description of this socket option.
  `static final int`
  `SO_SNDBUF`
  See `StandardSocketOptions.SO_SNDBUF` for description of this socket option.
  `static final int`
  `SO_TIMEOUT`
  This option is used to both set and fetch a timeout value on blocking `Socket` operations: ServerSocket.accept() Socket InputStream.read() DatagramSocket.receive()
  `static final int`
  `TCP_NODELAY`
  See `StandardSocketOptions.TCP_NODELAY` for description of this socket option.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `getOption(int optID)`
  Fetch the value of an option.
  `void`
  `setOption(int optID, Object value)`
  Enable/disable the option specified by `optID`.

- ## Field Details

  - ### TCP_NODELAY

    @Native static final int TCP_NODELAY
    See `StandardSocketOptions.TCP_NODELAY` for description of this socket option.
    See Also:
      - `Socket.setTcpNoDelay(boolean)`
      - `Socket.getTcpNoDelay()`
      - Constant Field Values

  - ### SO_BINDADDR

    @Native static final int SO_BINDADDR
    Fetch the local address binding of a socket. This option cannot be set and can only be fetched. The default local address of a socket is `INADDR_ANY`, meaning any local address on a multi-homed host. A multi-homed host can use this option to accept connections to only one of its addresses (in the case of a `ServerSocket` or `DatagramSocket`), or to specify its return address to the peer (for a `Socket` or `DatagramSocket`). The type of this option's value is an `InetAddress`.
    See Also:
      - `Socket.getLocalAddress()`
      - `DatagramSocket.getLocalAddress()`
      - Constant Field Values

  - ### SO_REUSEADDR

    @Native static final int SO_REUSEADDR
    See `StandardSocketOptions.SO_REUSEADDR` for description of this socket option.
    See Also:
      - Constant Field Values

  - ### SO_REUSEPORT

    @Native static final int SO_REUSEPORT
    See `StandardSocketOptions.SO_REUSEPORT` for description of this socket option.
    Since:
      9
    See Also:
      - Constant Field Values

  - ### SO_BROADCAST

    @Native static final int SO_BROADCAST
    See `StandardSocketOptions.SO_BROADCAST` for description of this socket option.
    Since:
      1.4
    See Also:
      - Constant Field Values

  - ### IP_MULTICAST_IF

    @Native static final int IP_MULTICAST_IF
    See `StandardSocketOptions.IP_MULTICAST_IF` for description of this socket option.
    See Also:
      - `MulticastSocket.setInterface(InetAddress)`
      - `MulticastSocket.getInterface()`
      - Constant Field Values

  - ### IP_MULTICAST_IF2

    @Native static final int IP_MULTICAST_IF2
    This option is used to both set and fetch the outgoing interface on which the multicast packets are sent. Useful on hosts with multiple network interfaces, where applications want to use other than the system default. This option supports setting outgoing interfaces with either IPv4 and IPv6 addresses.
    Since:
      1.4
    See Also:
      - `MulticastSocket.setNetworkInterface(NetworkInterface)`
      - `MulticastSocket.getNetworkInterface()`
      - Constant Field Values

  - ### IP_MULTICAST_LOOP

    @Native static final int IP_MULTICAST_LOOP
    See `StandardSocketOptions.IP_MULTICAST_LOOP` for description of this socket option.
    Since:
      1.4
    See Also:
      - Constant Field Values

  - ### IP_TOS

    @Native static final int IP_TOS
    See `StandardSocketOptions.IP_TOS` for description of this socket option.
    Since:
      1.4
    See Also:
      - Constant Field Values

  - ### SO_LINGER

    @Native static final int SO_LINGER
    See `StandardSocketOptions.SO_LINGER` for description of this socket option.

    Set the value to `Boolean.FALSE` or an integer less than `0` with `setOption(int, Object)` to disable this option. An integer greater than or equal to `0` will enable the option and will represent the linger interval.

    If this option is enabled then `getOption(int)` will return an integer value representing the linger interval, else the return value will be `Boolean.FALSE`.

    See Also:
      - `Socket.setSoLinger(boolean, int)`
      - `Socket.getSoLinger()`
      - Constant Field Values

  - ### SO_TIMEOUT

    @Native static final int SO_TIMEOUT
    This option is used to both set and fetch a timeout value on blocking `Socket` operations:
    - ServerSocket.accept()
    - Socket InputStream.read()
    - DatagramSocket.receive()

    This option must be set prior to entering a blocking operation to take effect. If the timeout expires and the operation would continue to block, then `InterruptedIOException` is raised. The `Socket` is not closed in such cases.

    See Also:
      - `Socket.setSoTimeout(int)`
      - `ServerSocket.setSoTimeout(int)`
      - `DatagramSocket.setSoTimeout(int)`
      - Constant Field Values

  - ### SO_SNDBUF

    @Native static final int SO_SNDBUF
    See `StandardSocketOptions.SO_SNDBUF` for description of this socket option.
    See Also:
      - `Socket.setSendBufferSize(int)`
      - `Socket.getSendBufferSize()`
      - `DatagramSocket.setSendBufferSize(int)`
      - `DatagramSocket.getSendBufferSize()`
      - Constant Field Values

  - ### SO_RCVBUF

    @Native static final int SO_RCVBUF
    See `StandardSocketOptions.SO_RCVBUF` for description of this socket option.
    See Also:
      - `Socket.setReceiveBufferSize(int)`
      - `Socket.getReceiveBufferSize()`
      - `DatagramSocket.setReceiveBufferSize(int)`
      - `DatagramSocket.getReceiveBufferSize()`
      - Constant Field Values

  - ### SO_KEEPALIVE

    @Native static final int SO_KEEPALIVE
    See `StandardSocketOptions.SO_KEEPALIVE` for description of this socket option.
    See Also:
      - `Socket.setKeepAlive(boolean)`
      - `Socket.getKeepAlive()`
      - Constant Field Values

  - ### SO_OOBINLINE

    @Native static final int SO_OOBINLINE
    When this option is set, any TCP urgent data received on the socket will be received through the socket input stream. When the option is disabled (which is the default) urgent data is silently discarded.
    See Also:
      - `Socket.setOOBInline(boolean)`
      - `Socket.getOOBInline()`
      - Constant Field Values

- ## Method Details

  - ### setOption

    void setOption(int optID, Object value) throws SocketException
    Enable/disable the option specified by `optID`. If the option is to be enabled, and it takes an option-specific "value", this is passed in `value`. The actual type of `value` is option-specific, and it is an error to pass something that isn't of the expected type:

         SocketImpl s;
         ...
         s.setOption(SO_LINGER, Integer.valueOf(10));
            // OK - set SO_LINGER w/ timeout of 10 sec.
         s.setOption(SO_LINGER, Double.valueOf(10));
            // ERROR - expects java.lang.Integer

    If the requested option is binary, it can be set using this method by a `Boolean`:

        s.setOption(TCP_NODELAY, Boolean.TRUE);
           // OK - enables TCP_NODELAY, a binary option

    Any option can be disabled using this method with a `Boolean.FALSE`:

        s.setOption(TCP_NODELAY, Boolean.FALSE);
           // OK - disables TCP_NODELAY
        s.setOption(SO_LINGER, Boolean.FALSE);
           // OK - disables SO_LINGER

    For an option that has a notion of on and off, and requires a non-boolean parameter, setting its value to anything other than `Boolean.FALSE` implicitly enables it.
    Parameters:
      `optID` - identifies the option
      `value` - the parameter of the socket option
    Throws:
      `SocketException` - if the option is unrecognized, the socket is closed, or some low-level error occurred
    See Also:
      - `getOption(int)`

  - ### getOption

    Object getOption(int optID) throws SocketException
    Fetch the value of an option. Binary options will return `Boolean.TRUE` if enabled, `Boolean.FALSE` if disabled, e.g.:

        SocketImpl s;
        ...
        Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY));
        if (noDelay.booleanValue()) {
            // true if TCP_NODELAY is enabled...
        ...
        }

    For options that take a particular type as a parameter, this method will return the parameter's value, else it will return `Boolean.FALSE`:

        Object o = s.getOption(SO_LINGER);
        if (o instanceof Integer) {
            System.out.print("Linger time is " + ((Integer)o).intValue());
        } else {
          // the true type of o is java.lang.Boolean.FALSE;
        }

    Parameters:
      `optID` - an `int` identifying the option to fetch
    Returns:
      the value of the option
    Throws:
      `SocketException` - if the socket is closed or if `optID` is unknown along the protocol stack
    See Also:
      - `setOption(int, java.lang.Object)`