Java tutorial
/* * Copyright (c) 1996, 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; import java.lang.annotation.Native; /** * Interface of methods to get/set socket options. This interface is * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>. * Subclasses of these should override the methods * of this interface in order to support their own options. * <P> * The methods and constants which specify options in this interface are * for implementation only. If you're not subclassing SocketImpl or * DatagramSocketImpl, <B>you won't use these directly.</B> There are * type-safe methods to get/set each of these options in Socket, ServerSocket, * DatagramSocket and MulticastSocket. * * @author David Brown * @since 1.1 */ public interface SocketOptions { /** * Enable/disable the option specified by <I>optID</I>. If the option * is to be enabled, and it takes an option-specific "value", this is * passed in <I>value</I>. The actual type of value is option-specific, * and it is an error to pass something that isn't of the expected type: * <BR><PRE> * SocketImpl s; * ... * s.setOption(SO_LINGER, new Integer(10)); * // OK - set SO_LINGER w/ timeout of 10 sec. * s.setOption(SO_LINGER, new Double(10)); * // ERROR - expects java.lang.Integer *</PRE> * If the requested option is binary, it can be set using this method by * a java.lang.Boolean: * <BR><PRE> * s.setOption(TCP_NODELAY, Boolean.TRUE); * // OK - enables TCP_NODELAY, a binary option * </PRE> * <BR> * Any option can be disabled using this method with a Boolean.FALSE: * <BR><PRE> * s.setOption(TCP_NODELAY, Boolean.FALSE); * // OK - disables TCP_NODELAY * s.setOption(SO_LINGER, Boolean.FALSE); * // OK - disables SO_LINGER * </PRE> * <BR> * For an option that has a notion of on and off, and requires * a non-boolean parameter, setting its value to anything other than * <I>Boolean.FALSE</I> implicitly enables it. * <BR> * Throws SocketException if the option is unrecognized, * the socket is closed, or some low-level error occurred * <BR> * @param optID identifies the option * @param 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 #getOption(int) */ public void setOption(int optID, Object value) throws SocketException; /** * Fetch the value of an option. * Binary options will return java.lang.Boolean.TRUE * if enabled, java.lang.Boolean.FALSE if disabled, e.g.: * <BR><PRE> * SocketImpl s; * ... * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY)); * if (noDelay.booleanValue()) { * // true if TCP_NODELAY is enabled... * ... * } * </PRE> * <P> * For options that take a particular type as a parameter, * getOption(int) will return the parameter's value, else * it will return java.lang.Boolean.FALSE: * <PRE> * 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; * } * </PRE> * * @param optID an {@code int} identifying the option to fetch * @return the value of the option * @throws SocketException if the socket is closed * @throws SocketException if <I>optID</I> is unknown along the * protocol stack (including the SocketImpl) * @see #setOption(int, java.lang.Object) */ public Object getOption(int optID) throws SocketException; /** * The java-supported BSD-style options. */ /** * Disable Nagle's algorithm for this connection. Written data * to the network is not buffered pending acknowledgement of * previously written data. *<P> * Valid for TCP only: SocketImpl. * * @see Socket#setTcpNoDelay * @see Socket#getTcpNoDelay */ @Native public static final int TCP_NODELAY = 0x0001; /** * Fetch the local address binding of a socket (this option cannot * be "set" only "gotten", since sockets are bound at creation time, * and so the locally bound address cannot be changed). 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 parameter of * this option is an InetAddress. * <P> * This option <B>must</B> be specified in the constructor. * <P> * Valid for: SocketImpl, DatagramSocketImpl * * @see Socket#getLocalAddress * @see DatagramSocket#getLocalAddress */ @Native public static final int SO_BINDADDR = 0x000F; /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets * in java, and it is set by default for MulticastSockets. * <P> * Valid for: DatagramSocketImpl */ @Native public static final int SO_REUSEADDR = 0x04; /** Sets SO_REUSEPORT for a socket. This option enables and disables * the ability to have multiple sockets listen to the same address * and port. * <P> * Valid for: SocketImpl, DatagramSocketImpl * * @since 9 * @see StandardSocketOptions#SO_REUSEPORT */ @Native public static final int SO_REUSEPORT = 0x0E; /** * Sets SO_BROADCAST for a socket. This option enables and disables * the ability of the process to send broadcast messages. It is supported * for only datagram sockets and only on networks that support * the concept of a broadcast message (e.g. Ethernet, token ring, etc.), * and it is set by default for DatagramSockets. * @since 1.4 */ @Native public static final int SO_BROADCAST = 0x0020; /** Set which outgoing interface on which to send multicast packets. * Useful on hosts with multiple network interfaces, where applications * want to use other than the system default. Takes/returns an InetAddress. * <P> * Valid for Multicast: DatagramSocketImpl * * @see MulticastSocket#setInterface(InetAddress) * @see MulticastSocket#getInterface() */ @Native public static final int IP_MULTICAST_IF = 0x10; /** Same as above. This option is introduced so that the behaviour * with IP_MULTICAST_IF will be kept the same as before, while * this new option can support setting outgoing interfaces with either * IPv4 and IPv6 addresses. * * NOTE: make sure there is no conflict with this * @see MulticastSocket#setNetworkInterface(NetworkInterface) * @see MulticastSocket#getNetworkInterface() * @since 1.4 */ @Native public static final int IP_MULTICAST_IF2 = 0x1f; /** * This option enables or disables local loopback of multicast datagrams. * This option is enabled by default for Multicast Sockets. * @since 1.4 */ @Native public static final int IP_MULTICAST_LOOP = 0x12; /** * This option sets the type-of-service or traffic class field * in the IP header for a TCP or UDP socket. * @since 1.4 */ @Native public static final int IP_TOS = 0x3; /** * Specify a linger-on-close timeout. This option disables/enables * immediate return from a <B>close()</B> of a TCP Socket. Enabling * this option with a non-zero Integer <I>timeout</I> means that a * <B>close()</B> will block pending the transmission and acknowledgement * of all data written to the peer, at which point the socket is closed * <I>gracefully</I>. Upon reaching the linger timeout, the socket is * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a * timeout of zero does a forceful close immediately. If the specified * timeout value exceeds 65,535 it will be reduced to 65,535. * <P> * Valid only for TCP: SocketImpl * * @see Socket#setSoLinger * @see Socket#getSoLinger */ @Native public static final int SO_LINGER = 0x0080; /** Set a timeout on blocking Socket operations: * <PRE> * ServerSocket.accept(); * SocketInputStream.read(); * DatagramSocket.receive(); * </PRE> * * <P> The option must be set prior to entering a blocking * operation to take effect. If the timeout expires and the * operation would continue to block, * <B>java.io.InterruptedIOException</B> is raised. The Socket is * not closed in this case. * * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl * * @see Socket#setSoTimeout * @see ServerSocket#setSoTimeout * @see DatagramSocket#setSoTimeout */ @Native public static final int SO_TIMEOUT = 0x1006; /** * Set a hint the size of the underlying buffers used by the * platform for outgoing network I/O. When used in set, this is a * suggestion to the kernel from the application about the size of * buffers to use for the data to be sent over the socket. When * used in get, this must return the size of the buffer actually * used by the platform when sending out data on this socket. * * Valid for all sockets: SocketImpl, DatagramSocketImpl * * @see Socket#setSendBufferSize * @see Socket#getSendBufferSize * @see DatagramSocket#setSendBufferSize * @see DatagramSocket#getSendBufferSize */ @Native public static final int SO_SNDBUF = 0x1001; /** * Set a hint the size of the underlying buffers used by the * platform for incoming network I/O. When used in set, this is a * suggestion to the kernel from the application about the size of * buffers to use for the data to be received over the * socket. When used in get, this must return the size of the * buffer actually used by the platform when receiving in data on * this socket. * * Valid for all sockets: SocketImpl, DatagramSocketImpl * * @see Socket#setReceiveBufferSize * @see Socket#getReceiveBufferSize * @see DatagramSocket#setReceiveBufferSize * @see DatagramSocket#getReceiveBufferSize */ @Native public static final int SO_RCVBUF = 0x1002; /** * When the keepalive option is set for a TCP socket and no data * has been exchanged across the socket in either direction for * 2 hours (NOTE: the actual value is implementation dependent), * TCP automatically sends a keepalive probe to the peer. This probe is a * TCP segment to which the peer must respond. * One of three responses is expected: * 1. The peer responds with the expected ACK. The application is not * notified (since everything is OK). TCP will send another probe * following another 2 hours of inactivity. * 2. The peer responds with an RST, which tells the local TCP that * the peer host has crashed and rebooted. The socket is closed. * 3. There is no response from the peer. The socket is closed. * * The purpose of this option is to detect if the peer host crashes. * * Valid only for TCP socket: SocketImpl * * @see Socket#setKeepAlive * @see Socket#getKeepAlive */ @Native public static final int SO_KEEPALIVE = 0x0008; /** * When the OOBINLINE 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 Socket#setOOBInline * @see Socket#getOOBInline */ @Native public static final int SO_OOBINLINE = 0x1003; }