/* |
|
* Copyright (c) 2007, 2016, Oracle and/or its affiliates. All rights reserved. |
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
* |
|
* This code is free software; you can redistribute it and/or modify it |
|
* under the terms of the GNU General Public License version 2 only, as |
|
* published by the Free Software Foundation. Oracle designates this |
|
* particular file as subject to the "Classpath" exception as provided |
|
* by Oracle in the LICENSE file that accompanied this code. |
|
* |
|
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
* version 2 for more details (a copy is included in the LICENSE file that |
|
* accompanied this code). |
|
* |
|
* You should have received a copy of the GNU General Public License version |
|
* 2 along with this work; if not, write to the Free Software Foundation, |
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
* |
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
* or visit www.oracle.com if you need additional information or have any |
|
* questions. |
|
*/ |
|
package java.net; |
|
/** |
|
* Defines the <em>standard</em> socket options. |
|
* |
|
* <p> The {@link SocketOption#name name} of each socket option defined by this |
|
* class is its field name. |
|
* |
|
* <p> In this release, the socket options defined here are used by {@link |
|
* java.nio.channels.NetworkChannel network} channels in the {@link |
|
* java.nio.channels channels} package. |
|
* |
|
* @since 1.7 |
|
*/ |
|
public final class StandardSocketOptions { |
|
private StandardSocketOptions() { } |
|
// -- SOL_SOCKET -- |
|
/** |
|
* Allow transmission of broadcast datagrams. |
|
* |
|
* <p> The value of this socket option is a {@code Boolean} that represents |
|
* whether the option is enabled or disabled. The option is specific to |
|
* datagram-oriented sockets sending to {@link java.net.Inet4Address IPv4} |
|
* broadcast addresses. When the socket option is enabled then the socket |
|
* can be used to send <em>broadcast datagrams</em>. |
|
* |
|
* <p> The initial value of this socket option is {@code FALSE}. The socket |
|
* option may be enabled or disabled at any time. Some operating systems may |
|
* require that the Java virtual machine be started with implementation |
|
* specific privileges to enable this option or send broadcast datagrams. |
|
* |
|
* @see <a href="http://www.ietf.org/rfc/rfc919.txt">RFC 929: |
|
* Broadcasting Internet Datagrams</a> |
|
* @see DatagramSocket#setBroadcast |
|
*/ |
|
public static final SocketOption<Boolean> SO_BROADCAST = |
|
new StdSocketOption<Boolean>("SO_BROADCAST", Boolean.class); |
|
/** |
|
* Keep connection alive. |
|
* |
|
* <p> The value of this socket option is a {@code Boolean} that represents |
|
* whether the option is enabled or disabled. When the {@code SO_KEEPALIVE} |
|
* option is enabled the operating system may use a <em>keep-alive</em> |
|
* mechanism to periodically probe the other end of a connection when the |
|
* connection is otherwise idle. The exact semantics of the keep alive |
|
* mechanism is system dependent and therefore unspecified. |
|
* |
|
* <p> The initial value of this socket option is {@code FALSE}. The socket |
|
* option may be enabled or disabled at any time. |
|
* |
|
* @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122 |
|
* Requirements for Internet Hosts -- Communication Layers</a> |
|
* @see Socket#setKeepAlive |
|
*/ |
|
public static final SocketOption<Boolean> SO_KEEPALIVE = |
|
new StdSocketOption<Boolean>("SO_KEEPALIVE", Boolean.class); |
|
/** |
|
* The size of the socket send buffer. |
|
* |
|
* <p> The value of this socket option is an {@code Integer} that is the |
|
* size of the socket send buffer in bytes. The socket send buffer is an |
|
* output buffer used by the networking implementation. It may need to be |
|
* increased for high-volume connections. The value of the socket option is |
|
* a <em>hint</em> to the implementation to size the buffer and the actual |
|
* size may differ. The socket option can be queried to retrieve the actual |
|
* size. |
|
* |
|
* <p> For datagram-oriented sockets, the size of the send buffer may limit |
|
* the size of the datagrams that may be sent by the socket. Whether |
|
* datagrams larger than the buffer size are sent or discarded is system |
|
* dependent. |
|
* |
|
* <p> The initial/default size of the socket send buffer and the range of |
|
* allowable values is system dependent although a negative size is not |
|
* allowed. An attempt to set the socket send buffer to larger than its |
|
* maximum size causes it to be set to its maximum size. |
|
* |
|
* <p> An implementation allows this socket option to be set before the |
|
* socket is bound or connected. Whether an implementation allows the |
|
* socket send buffer to be changed after the socket is bound is system |
|
* dependent. |
|
* |
|
* @see Socket#setSendBufferSize |
|
*/ |
|
public static final SocketOption<Integer> SO_SNDBUF = |
|
new StdSocketOption<Integer>("SO_SNDBUF", Integer.class); |
|
/** |
|
* The size of the socket receive buffer. |
|
* |
|
* <p> The value of this socket option is an {@code Integer} that is the |
|
* size of the socket receive buffer in bytes. The socket receive buffer is |
|
* an input buffer used by the networking implementation. It may need to be |
|
* increased for high-volume connections or decreased to limit the possible |
|
* backlog of incoming data. The value of the socket option is a |
|
* <em>hint</em> to the implementation to size the buffer and the actual |
|
* size may differ. |
|
* |
|
* <p> For datagram-oriented sockets, the size of the receive buffer may |
|
* limit the size of the datagrams that can be received. Whether datagrams |
|
* larger than the buffer size can be received is system dependent. |
|
* Increasing the socket receive buffer may be important for cases where |
|
* datagrams arrive in bursts faster than they can be processed. |
|
* |
|
* <p> In the case of stream-oriented sockets and the TCP/IP protocol, the |
|
* size of the socket receive buffer may be used when advertising the size |
|
* of the TCP receive window to the remote peer. |
|
* |
|
* <p> The initial/default size of the socket receive buffer and the range |
|
* of allowable values is system dependent although a negative size is not |
|
* allowed. An attempt to set the socket receive buffer to larger than its |
|
* maximum size causes it to be set to its maximum size. |
|
* |
|
* <p> An implementation allows this socket option to be set before the |
|
* socket is bound or connected. Whether an implementation allows the |
|
* socket receive buffer to be changed after the socket is bound is system |
|
* dependent. |
|
* |
|
* @see <a href="http://www.ietf.org/rfc/rfc1323.txt">RFC 1323: TCP |
|
* Extensions for High Performance</a> |
|
* @see Socket#setReceiveBufferSize |
|
* @see ServerSocket#setReceiveBufferSize |
|
*/ |
|
public static final SocketOption<Integer> SO_RCVBUF = |
|
new StdSocketOption<Integer>("SO_RCVBUF", Integer.class); |
|
/** |
|
* Re-use address. |
|
* |
|
* <p> The value of this socket option is a {@code Boolean} that represents |
|
* whether the option is enabled or disabled. The exact semantics of this |
|
* socket option are socket type and system dependent. |
|
* |
|
* <p> In the case of stream-oriented sockets, this socket option will |
|
* usually determine whether the socket can be bound to a socket address |
|
* when a previous connection involving that socket address is in the |
|
* <em>TIME_WAIT</em> state. On implementations where the semantics differ, |
|
* and the socket option is not required to be enabled in order to bind the |
|
* socket when a previous connection is in this state, then the |
|
* implementation may choose to ignore this option. |
|
* |
|
* <p> For datagram-oriented sockets the socket option is used to allow |
|
* multiple programs bind to the same address. This option should be enabled |
|
* when the socket is to be used for Internet Protocol (IP) multicasting. |
|
* |
|
* <p> An implementation allows this socket option to be set before the |
|
* socket is bound or connected. Changing the value of this socket option |
|
* after the socket is bound has no effect. The default value of this |
|
* socket option is system dependent. |
|
* |
|
* @see <a href="http://www.ietf.org/rfc/rfc793.txt">RFC 793: Transmission |
|
* Control Protocol</a> |
|
* @see ServerSocket#setReuseAddress |
|
*/ |
|
public static final SocketOption<Boolean> SO_REUSEADDR = |
|
new StdSocketOption<Boolean>("SO_REUSEADDR", Boolean.class); |
|
/** |
|
* Re-use port. |
|
* |
|
* <p> The value of this socket option is a {@code Boolean} that represents |
|
* whether the option is enabled or disabled. The exact semantics of this |
|
* socket option are socket type and system dependent. |
|
* |
|
* <p> In the case of stream-oriented sockets, this socket option usually allows |
|
* multiple listening sockets to be bound to both same address |
|
* and same port. |
|
* |
|
* <p> For datagram-oriented sockets the socket option usually allows |
|
* multiple UDP sockets to be bound to the same address and port. |
|
* |
|
* <p> An implementation allows this socket option to be set before the |
|
* socket is bound or connected. Changing the value of this socket option |
|
* after the socket is bound has no effect. |
|
* |
|
* @since 9 |
|
*/ |
|
public static final SocketOption<Boolean> SO_REUSEPORT = |
|
new StdSocketOption<Boolean>("SO_REUSEPORT", Boolean.class); |
|
/** |
|
* Linger on close if data is present. |
|
* |
|
* <p> The value of this socket option is an {@code Integer} that controls |
|
* the action taken when unsent data is queued on the socket and a method |
|
* to close the socket is invoked. If the value of the socket option is zero |
|
* or greater, then it represents a timeout value, in seconds, known as the |
|
* <em>linger interval</em>. The linger interval is the timeout for the |
|
* {@code close} method to block while the operating system attempts to |
|
* transmit the unsent data or it decides that it is unable to transmit the |
|
* data. If the value of the socket option is less than zero then the option |
|
* is disabled. In that case the {@code close} method does not wait until |
|
* unsent data is transmitted; if possible the operating system will transmit |
|
* any unsent data before the connection is closed. |
|
* |
|
* <p> This socket option is intended for use with sockets that are configured |
|
* in {@link java.nio.channels.SelectableChannel#isBlocking() blocking} mode |
|
* only. The behavior of the {@code close} method when this option is |
|
* enabled on a non-blocking socket is not defined. |
|
* |
|
* <p> The initial value of this socket option is a negative value, meaning |
|
* that the option is disabled. The option may be enabled, or the linger |
|
* interval changed, at any time. The maximum value of the linger interval |
|
* is system dependent. Setting the linger interval to a value that is |
|
* greater than its maximum value causes the linger interval to be set to |
|
* its maximum value. |
|
* |
|
* @see Socket#setSoLinger |
|
*/ |
|
public static final SocketOption<Integer> SO_LINGER = |
|
new StdSocketOption<Integer>("SO_LINGER", Integer.class); |
|
// -- IPPROTO_IP -- |
|
/** |
|
* The Type of Service (ToS) octet in the Internet Protocol (IP) header. |
|
* |
|
* <p> The value of this socket option is an {@code Integer} representing |
|
* the value of the ToS octet in IP packets sent by sockets to an {@link |
|
* StandardProtocolFamily#INET IPv4} socket. The interpretation of the ToS |
|
* octet is network specific and is not defined by this class. Further |
|
* information on the ToS octet can be found in <a |
|
* href="http://www.ietf.org/rfc/rfc1349.txt">RFC 1349</a> and <a |
|
* href="http://www.ietf.org/rfc/rfc2474.txt">RFC 2474</a>. The value |
|
* of the socket option is a <em>hint</em>. An implementation may ignore the |
|
* value, or ignore specific values. |
|
* |
|
* <p> The initial/default value of the TOS field in the ToS octet is |
|
* implementation specific but will typically be {@code 0}. For |
|
* datagram-oriented sockets the option may be configured at any time after |
|
* the socket has been bound. The new value of the octet is used when sending |
|
* subsequent datagrams. It is system dependent whether this option can be |
|
* queried or changed prior to binding the socket. |
|
* |
|
* <p> The behavior of this socket option on a stream-oriented socket, or an |
|
* {@link StandardProtocolFamily#INET6 IPv6} socket, is not defined in this |
|
* release. |
|
* |
|
* @see DatagramSocket#setTrafficClass |
|
*/ |
|
public static final SocketOption<Integer> IP_TOS = |
|
new StdSocketOption<Integer>("IP_TOS", Integer.class); |
|
/** |
|
* The network interface for Internet Protocol (IP) multicast datagrams. |
|
* |
|
* <p> The value of this socket option is a {@link NetworkInterface} that |
|
* represents the outgoing interface for multicast datagrams sent by the |
|
* datagram-oriented socket. For {@link StandardProtocolFamily#INET6 IPv6} |
|
* sockets then it is system dependent whether setting this option also |
|
* sets the outgoing interface for multicast datagrams sent to IPv4 |
|
* addresses. |
|
* |
|
* <p> The initial/default value of this socket option may be {@code null} |
|
* to indicate that outgoing interface will be selected by the operating |
|
* system, typically based on the network routing tables. An implementation |
|
* allows this socket option to be set after the socket is bound. Whether |
|
* the socket option can be queried or changed prior to binding the socket |
|
* is system dependent. |
|
* |
|
* @see java.nio.channels.MulticastChannel |
|
* @see MulticastSocket#setInterface |
|
*/ |
|
public static final SocketOption<NetworkInterface> IP_MULTICAST_IF = |
|
new StdSocketOption<NetworkInterface>("IP_MULTICAST_IF", NetworkInterface.class); |
|
/** |
|
* The <em>time-to-live</em> for Internet Protocol (IP) multicast datagrams. |
|
* |
|
* <p> The value of this socket option is an {@code Integer} in the range |
|
* {@code 0 <= value <= 255}. It is used to control the scope of multicast |
|
* datagrams sent by the datagram-oriented socket. |
|
* In the case of an {@link StandardProtocolFamily#INET IPv4} socket |
|
* the option is the time-to-live (TTL) on multicast datagrams sent by the |
|
* socket. Datagrams with a TTL of zero are not transmitted on the network |
|
* but may be delivered locally. In the case of an {@link |
|
* StandardProtocolFamily#INET6 IPv6} socket the option is the |
|
* <em>hop limit</em> which is number of <em>hops</em> that the datagram can |
|
* pass through before expiring on the network. For IPv6 sockets it is |
|
* system dependent whether the option also sets the <em>time-to-live</em> |
|
* on multicast datagrams sent to IPv4 addresses. |
|
* |
|
* <p> The initial/default value of the time-to-live setting is typically |
|
* {@code 1}. An implementation allows this socket option to be set after |
|
* the socket is bound. Whether the socket option can be queried or changed |
|
* prior to binding the socket is system dependent. |
|
* |
|
* @see java.nio.channels.MulticastChannel |
|
* @see MulticastSocket#setTimeToLive |
|
*/ |
|
public static final SocketOption<Integer> IP_MULTICAST_TTL = |
|
new StdSocketOption<Integer>("IP_MULTICAST_TTL", Integer.class); |
|
/** |
|
* Loopback for Internet Protocol (IP) multicast datagrams. |
|
* |
|
* <p> The value of this socket option is a {@code Boolean} that controls |
|
* the <em>loopback</em> of multicast datagrams. The value of the socket |
|
* option represents if the option is enabled or disabled. |
|
* |
|
* <p> The exact semantics of this socket options are system dependent. |
|
* In particular, it is system dependent whether the loopback applies to |
|
* multicast datagrams sent from the socket or received by the socket. |
|
* For {@link StandardProtocolFamily#INET6 IPv6} sockets then it is |
|
* system dependent whether the option also applies to multicast datagrams |
|
* sent to IPv4 addresses. |
|
* |
|
* <p> The initial/default value of this socket option is {@code TRUE}. An |
|
* implementation allows this socket option to be set after the socket is |
|
* bound. Whether the socket option can be queried or changed prior to |
|
* binding the socket is system dependent. |
|
* |
|
* @see java.nio.channels.MulticastChannel |
|
* @see MulticastSocket#setLoopbackMode |
|
*/ |
|
public static final SocketOption<Boolean> IP_MULTICAST_LOOP = |
|
new StdSocketOption<Boolean>("IP_MULTICAST_LOOP", Boolean.class); |
|
// -- IPPROTO_TCP -- |
|
/** |
|
* Disable the Nagle algorithm. |
|
* |
|
* <p> The value of this socket option is a {@code Boolean} that represents |
|
* whether the option is enabled or disabled. The socket option is specific to |
|
* stream-oriented sockets using the TCP/IP protocol. TCP/IP uses an algorithm |
|
* known as <em>The Nagle Algorithm</em> to coalesce short segments and |
|
* improve network efficiency. |
|
* |
|
* <p> The default value of this socket option is {@code FALSE}. The |
|
* socket option should only be enabled in cases where it is known that the |
|
* coalescing impacts performance. The socket option may be enabled at any |
|
* time. In other words, the Nagle Algorithm can be disabled. Once the option |
|
* is enabled, it is system dependent whether it can be subsequently |
|
* disabled. If it cannot, then invoking the {@code setOption} method to |
|
* disable the option has no effect. |
|
* |
|
* @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122: |
|
* Requirements for Internet Hosts -- Communication Layers</a> |
|
* @see Socket#setTcpNoDelay |
|
*/ |
|
public static final SocketOption<Boolean> TCP_NODELAY = |
|
new StdSocketOption<Boolean>("TCP_NODELAY", Boolean.class); |
|
private static class StdSocketOption<T> implements SocketOption<T> { |
|
private final String name; |
|
private final Class<T> type; |
|
StdSocketOption(String name, Class<T> type) { |
|
this.name = name; |
|
this.type = type; |
|
} |
|
@Override public String name() { return name; } |
|
@Override public Class<T> type() { return type; } |
|
@Override public String toString() { return name; } |
|
} |
|
} |