SocketOptions.java revision 0
0N/A * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * Interface of methods to get/set socket options. This interface is 0N/A * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>. 0N/A * Subclasses of these should override the methods 0N/A * of this interface in order to support their own options. 0N/A * The methods and constants which specify options in this interface are 0N/A * for implementation only. If you're not subclassing SocketImpl or 0N/A * DatagramSocketImpl, <B>you won't use these directly.</B> There are 0N/A * type-safe methods to get/set each of these options in Socket, ServerSocket, 0N/A * DatagramSocket and MulticastSocket. 0N/A * @author David Brown 0N/A * is to be enabled, and it takes an option-specific "value", this is 0N/A * passed in <I>value</I>. The actual type of value is option-specific, 0N/A * and it is an error to pass something that isn't of the expected type: 0N/A * s.setOption(SO_LINGER, new Integer(10)); 0N/A * // OK - set SO_LINGER w/ timeout of 10 sec. 0N/A * s.setOption(SO_LINGER, new Double(10)); 0N/A * // ERROR - expects java.lang.Integer 0N/A * If the requested option is binary, it can be set using this method by 0N/A * a java.lang.Boolean: 0N/A * s.setOption(TCP_NODELAY, new Boolean(true)); 0N/A * // OK - enables TCP_NODELAY, a binary option 0N/A * Any option can be disabled using this method with a Boolean(false): 0N/A * s.setOption(TCP_NODELAY, new Boolean(false)); 0N/A * // OK - disables TCP_NODELAY 0N/A * s.setOption(SO_LINGER, new Boolean(false)); 0N/A * // OK - disables SO_LINGER 0N/A * For an option that has a notion of on and off, and requires 0N/A * a non-boolean parameter, setting its value to anything other than 0N/A * <I>Boolean(false)</I> implicitly enables it. 0N/A * Throws SocketException if the option is unrecognized, 0N/A * the socket is closed, or some low-level error occurred 0N/A * @param optID identifies the option 0N/A * @param value the parameter of the socket option 0N/A * @throws SocketException if the option is unrecognized, 0N/A * the socket is closed, or some low-level error occurred 0N/A * @see #getOption(int) 0N/A * Fetch the value of an option. 0N/A * Binary options will return java.lang.Boolean(true) 0N/A * if enabled, java.lang.Boolean(false) if disabled, e.g.: 0N/A * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY)); 0N/A * if (noDelay.booleanValue()) { 0N/A * // true if TCP_NODELAY is enabled... 0N/A * For options that take a particular type as a parameter, 0N/A * getOption(int) will return the parameter's value, else 0N/A * it will return java.lang.Boolean(false): 0N/A * Object o = s.getOption(SO_LINGER); 0N/A * if (o instanceof Integer) { 0N/A * System.out.print("Linger time is " + ((Integer)o).intValue()); 0N/A * // the true type of o is java.lang.Boolean(false); 0N/A * @param optID an <code>int</code> identifying the option to fetch 0N/A * @return the value of the option 0N/A * @throws SocketException if the socket is closed 0N/A * @throws SocketException if <I>optID</I> is unknown along the 0N/A * protocol stack (including the SocketImpl) 0N/A * @see #setOption(int, java.lang.Object) 0N/A * The java-supported BSD-style options. 0N/A * Disable Nagle's algorithm for this connection. Written data 0N/A * to the network is not buffered pending acknowledgement of 0N/A * previously written data. 0N/A * Valid for TCP only: SocketImpl. 0N/A * @see Socket#setTcpNoDelay 0N/A * @see Socket#getTcpNoDelay 0N/A * Fetch the local address binding of a socket (this option cannot 0N/A * be "set" only "gotten", since sockets are bound at creation time, 0N/A * and so the locally bound address cannot be changed). The default local 0N/A * address of a socket is INADDR_ANY, meaning any local address on a 0N/A * multi-homed host. A multi-homed host can use this option to accept 0N/A * connections to only one of its addresses (in the case of a 0N/A * ServerSocket or DatagramSocket), or to specify its return address 0N/A * to the peer (for a Socket or DatagramSocket). The parameter of 0N/A * this option is an InetAddress. 0N/A * This option <B>must</B> be specified in the constructor. 0N/A * Valid for: SocketImpl, DatagramSocketImpl 0N/A * @see Socket#getLocalAddress 0N/A * @see DatagramSocket#getLocalAddress 0N/A /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets 0N/A * in java, and it is set by default for MulticastSockets. 0N/A * Valid for: DatagramSocketImpl 0N/A * Sets SO_BROADCAST for a socket. This option enables and disables 0N/A * the ability of the process to send broadcast messages. It is supported 0N/A * for only datagram sockets and only on networks that support 0N/A * the concept of a broadcast message (e.g. Ethernet, token ring, etc.), 0N/A * and it is set by default for DatagramSockets. 0N/A /** Set which outgoing interface on which to send multicast packets. 0N/A * Useful on hosts with multiple network interfaces, where applications 0N/A * Valid for Multicast: DatagramSocketImpl 0N/A * @see MulticastSocket#setInterface(InetAddress) 0N/A * @see MulticastSocket#getInterface() 0N/A /** Same as above. This option is introduced so that the behaviour 0N/A * with IP_MULTICAST_IF will be kept the same as before, while 0N/A * this new option can support setting outgoing interfaces with either 0N/A * IPv4 and IPv6 addresses. 0N/A * NOTE: make sure there is no conflict with this 0N/A * @see MulticastSocket#setNetworkInterface(NetworkInterface) 0N/A * @see MulticastSocket#getNetworkInterface() 0N/A * This option enables or disables local loopback of multicast datagrams. 0N/A * This option is enabled by default for Multicast Sockets. 0N/A * This option sets the type-of-service or traffic class field 0N/A * in the IP header for a TCP or UDP socket. 0N/A * immediate return from a <B>close()</B> of a TCP Socket. Enabling 0N/A * this option with a non-zero Integer <I>timeout</I> means that a 0N/A * <B>close()</B> will block pending the transmission and acknowledgement 0N/A * of all data written to the peer, at which point the socket is closed 0N/A * <I>gracefully</I>. Upon reaching the linger timeout, the socket is 0N/A * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a 0N/A * timeout of zero does a forceful close immediately. If the specified 0N/A * timeout value exceeds 65,535 it will be reduced to 65,535. 0N/A * Valid only for TCP: SocketImpl 0N/A * @see Socket#setSoLinger 0N/A * @see Socket#getSoLinger 0N/A /** Set a timeout on blocking Socket operations: 0N/A * ServerSocket.accept(); 0N/A * SocketInputStream.read(); 0N/A * DatagramSocket.receive(); 0N/A * <P> The option must be set prior to entering a blocking 0N/A * operation to take effect. If the timeout expires and the 0N/A * operation would continue to block, 0N/A * <B>java.io.InterruptedIOException</B> is raised. The Socket is 0N/A * not closed in this case. 0N/A * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl 0N/A * @see Socket#setSoTimeout 0N/A * @see ServerSocket#setSoTimeout 0N/A * @see DatagramSocket#setSoTimeout 0N/A * Set a hint the size of the underlying buffers used by the 0N/A * platform for outgoing network I/O. When used in set, this is a 0N/A * suggestion to the kernel from the application about the size of 0N/A * buffers to use for the data to be sent over the socket. When 0N/A * used in get, this must return the size of the buffer actually 0N/A * used by the platform when sending out data on this socket. 0N/A * Valid for all sockets: SocketImpl, DatagramSocketImpl 0N/A * @see Socket#setSendBufferSize 0N/A * @see Socket#getSendBufferSize 0N/A * @see DatagramSocket#setSendBufferSize 0N/A * @see DatagramSocket#getSendBufferSize 0N/A * Set a hint the size of the underlying buffers used by the 0N/A * platform for incoming network I/O. When used in set, this is a 0N/A * suggestion to the kernel from the application about the size of 0N/A * buffers to use for the data to be received over the 0N/A * socket. When used in get, this must return the size of the 0N/A * buffer actually used by the platform when receiving in data on 0N/A * Valid for all sockets: SocketImpl, DatagramSocketImpl 0N/A * @see Socket#setReceiveBufferSize 0N/A * @see Socket#getReceiveBufferSize 0N/A * @see DatagramSocket#setReceiveBufferSize 0N/A * @see DatagramSocket#getReceiveBufferSize 0N/A * When the keepalive option is set for a TCP socket and no data 0N/A * has been exchanged across the socket in either direction for 0N/A * 2 hours (NOTE: the actual value is implementation dependent), 0N/A * TCP automatically sends a keepalive probe to the peer. This probe is a 0N/A * TCP segment to which the peer must respond. 0N/A * One of three responses is expected: 0N/A * 1. The peer responds with the expected ACK. The application is not 0N/A * notified (since everything is OK). TCP will send another probe 0N/A * following another 2 hours of inactivity. 0N/A * 2. The peer responds with an RST, which tells the local TCP that 0N/A * the peer host has crashed and rebooted. The socket is closed. 0N/A * 3. There is no response from the peer. The socket is closed. 0N/A * The purpose of this option is to detect if the peer host crashes. 0N/A * Valid only for TCP socket: SocketImpl 0N/A * @see Socket#setKeepAlive 0N/A * @see Socket#getKeepAlive 0N/A * When the OOBINLINE option is set, any TCP urgent data received on 0N/A * the socket will be received through the socket input stream. 0N/A * When the option is disabled (which is the default) urgent data 0N/A * is silently discarded. 0N/A * @see Socket#setOOBInline 0N/A * @see Socket#getOOBInline