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