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.

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)