W3cubDocs

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

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:

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:

SO_REUSEADDR

@Native static final int SO_REUSEADDR

See StandardSocketOptions.SO_REUSEADDR for description of this socket option.

See Also:

SO_REUSEPORT

@Native static final int SO_REUSEPORT

See StandardSocketOptions.SO_REUSEPORT for description of this socket option.

Since:

See Also:

SO_BROADCAST

@Native static final int SO_BROADCAST

See StandardSocketOptions.SO_BROADCAST for description of this socket option.

Since:

1.4

See Also:

IP_MULTICAST_IF

@Native static final int IP_MULTICAST_IF

See StandardSocketOptions.IP_MULTICAST_IF for description of this socket option.

See Also:

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:

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:

IP_TOS

@Native static final int IP_TOS

See StandardSocketOptions.IP_TOS for description of this socket option.

Since:

1.4

See Also:

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:

SO_TIMEOUT

@Native static final int SO_TIMEOUT

This option is used to both set and fetch a timeout value on blocking Socket operations:

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:

SO_SNDBUF

@Native static final int SO_SNDBUF

See StandardSocketOptions.SO_SNDBUF for description of this socket option.

See Also:

SO_RCVBUF

@Native static final int SO_RCVBUF

See StandardSocketOptions.SO_RCVBUF for description of this socket option.

See Also:

SO_KEEPALIVE

@Native static final int SO_KEEPALIVE

See StandardSocketOptions.SO_KEEPALIVE for description of this socket option.

See Also:

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:

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

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:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/SocketOptions.html