1 /* 2 * Copyright (c) 1996, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.net; 27 28 import java.lang.annotation.Native; 29 30 /** 31 * Interface of methods to get/set socket options. This interface is 32 * implemented by: <B>SocketImpl</B> and <B>DatagramSocketImpl</B>. 33 * Subclasses of these should override the methods 34 * of this interface in order to support their own options. 35 * <P> 36 * The methods and constants which specify options in this interface are 37 * for implementation only. If you're not subclassing SocketImpl or 38 * DatagramSocketImpl, <B>you won't use these directly.</B> There are 39 * type-safe methods to get/set each of these options in Socket, ServerSocket, 40 * DatagramSocket and MulticastSocket. 41 * 42 * @author David Brown 43 * @since 1.1 44 */ 45 46 47 public interface SocketOptions { 48 49 /** 50 * Enable/disable the option specified by <I>optID</I>. If the option 51 * is to be enabled, and it takes an option-specific "value", this is 52 * passed in <I>value</I>. The actual type of value is option-specific, 53 * and it is an error to pass something that isn't of the expected type: 54 * <BR><PRE> 55 * SocketImpl s; 56 * ... 57 * s.setOption(SO_LINGER, new Integer(10)); 58 * // OK - set SO_LINGER w/ timeout of 10 sec. 59 * s.setOption(SO_LINGER, new Double(10)); 60 * // ERROR - expects java.lang.Integer 61 *</PRE> 62 * If the requested option is binary, it can be set using this method by 63 * a java.lang.Boolean: 64 * <BR><PRE> 65 * s.setOption(TCP_NODELAY, Boolean.TRUE); 66 * // OK - enables TCP_NODELAY, a binary option 67 * </PRE> 68 * <BR> 69 * Any option can be disabled using this method with a Boolean.FALSE: 70 * <BR><PRE> 71 * s.setOption(TCP_NODELAY, Boolean.FALSE); 72 * // OK - disables TCP_NODELAY 73 * s.setOption(SO_LINGER, Boolean.FALSE); 74 * // OK - disables SO_LINGER 75 * </PRE> 76 * <BR> 77 * For an option that has a notion of on and off, and requires 78 * a non-boolean parameter, setting its value to anything other than 79 * <I>Boolean.FALSE</I> implicitly enables it. 80 * <BR> 81 * Throws SocketException if the option is unrecognized, 82 * the socket is closed, or some low-level error occurred 83 * <BR> 84 * @param optID identifies the option 85 * @param value the parameter of the socket option 86 * @throws SocketException if the option is unrecognized, 87 * the socket is closed, or some low-level error occurred 88 * @see #getOption(int) 89 */ 90 public void setOption(int optID, Object value)91 setOption(int optID, Object value) throws SocketException; 92 93 /** 94 * Fetch the value of an option. 95 * Binary options will return java.lang.Boolean.TRUE 96 * if enabled, java.lang.Boolean.FALSE if disabled, e.g.: 97 * <BR><PRE> 98 * SocketImpl s; 99 * ... 100 * Boolean noDelay = (Boolean)(s.getOption(TCP_NODELAY)); 101 * if (noDelay.booleanValue()) { 102 * // true if TCP_NODELAY is enabled... 103 * ... 104 * } 105 * </PRE> 106 * <P> 107 * For options that take a particular type as a parameter, 108 * getOption(int) will return the parameter's value, else 109 * it will return java.lang.Boolean.FALSE: 110 * <PRE> 111 * Object o = s.getOption(SO_LINGER); 112 * if (o instanceof Integer) { 113 * System.out.print("Linger time is " + ((Integer)o).intValue()); 114 * } else { 115 * // the true type of o is java.lang.Boolean.FALSE; 116 * } 117 * </PRE> 118 * 119 * @param optID an {@code int} identifying the option to fetch 120 * @return the value of the option 121 * @throws SocketException if the socket is closed 122 * @throws SocketException if <I>optID</I> is unknown along the 123 * protocol stack (including the SocketImpl) 124 * @see #setOption(int, java.lang.Object) 125 */ getOption(int optID)126 public Object getOption(int optID) throws SocketException; 127 128 /** 129 * The java-supported BSD-style options. 130 */ 131 132 /** 133 * Disable Nagle's algorithm for this connection. Written data 134 * to the network is not buffered pending acknowledgement of 135 * previously written data. 136 *<P> 137 * Valid for TCP only: SocketImpl. 138 * 139 * @see Socket#setTcpNoDelay 140 * @see Socket#getTcpNoDelay 141 */ 142 143 @Native public static final int TCP_NODELAY = 0x0001; 144 145 /** 146 * Fetch the local address binding of a socket (this option cannot 147 * be "set" only "gotten", since sockets are bound at creation time, 148 * and so the locally bound address cannot be changed). The default local 149 * address of a socket is INADDR_ANY, meaning any local address on a 150 * multi-homed host. A multi-homed host can use this option to accept 151 * connections to only one of its addresses (in the case of a 152 * ServerSocket or DatagramSocket), or to specify its return address 153 * to the peer (for a Socket or DatagramSocket). The parameter of 154 * this option is an InetAddress. 155 * <P> 156 * This option <B>must</B> be specified in the constructor. 157 * <P> 158 * Valid for: SocketImpl, DatagramSocketImpl 159 * 160 * @see Socket#getLocalAddress 161 * @see DatagramSocket#getLocalAddress 162 */ 163 164 @Native public static final int SO_BINDADDR = 0x000F; 165 166 /** Sets SO_REUSEADDR for a socket. This is used only for MulticastSockets 167 * in java, and it is set by default for MulticastSockets. 168 * <P> 169 * Valid for: DatagramSocketImpl 170 */ 171 172 @Native public static final int SO_REUSEADDR = 0x04; 173 174 /** Sets SO_REUSEPORT for a socket. This option enables and disables 175 * the ability to have multiple sockets listen to the same address 176 * and port. 177 * <P> 178 * Valid for: SocketImpl, DatagramSocketImpl 179 * 180 * @since 9 181 * @see StandardSocketOptions#SO_REUSEPORT 182 */ 183 @Native public static final int SO_REUSEPORT = 0x0E; 184 185 /** 186 * Sets SO_BROADCAST for a socket. This option enables and disables 187 * the ability of the process to send broadcast messages. It is supported 188 * for only datagram sockets and only on networks that support 189 * the concept of a broadcast message (e.g. Ethernet, token ring, etc.), 190 * and it is set by default for DatagramSockets. 191 * @since 1.4 192 */ 193 194 @Native public static final int SO_BROADCAST = 0x0020; 195 196 /** Set which outgoing interface on which to send multicast packets. 197 * Useful on hosts with multiple network interfaces, where applications 198 * want to use other than the system default. Takes/returns an InetAddress. 199 * <P> 200 * Valid for Multicast: DatagramSocketImpl 201 * 202 * @see MulticastSocket#setInterface(InetAddress) 203 * @see MulticastSocket#getInterface() 204 */ 205 206 @Native public static final int IP_MULTICAST_IF = 0x10; 207 208 /** Same as above. This option is introduced so that the behaviour 209 * with IP_MULTICAST_IF will be kept the same as before, while 210 * this new option can support setting outgoing interfaces with either 211 * IPv4 and IPv6 addresses. 212 * 213 * NOTE: make sure there is no conflict with this 214 * @see MulticastSocket#setNetworkInterface(NetworkInterface) 215 * @see MulticastSocket#getNetworkInterface() 216 * @since 1.4 217 */ 218 @Native public static final int IP_MULTICAST_IF2 = 0x1f; 219 220 /** 221 * This option enables or disables local loopback of multicast datagrams. 222 * This option is enabled by default for Multicast Sockets. 223 * @since 1.4 224 */ 225 226 @Native public static final int IP_MULTICAST_LOOP = 0x12; 227 228 /** 229 * This option sets the type-of-service or traffic class field 230 * in the IP header for a TCP or UDP socket. 231 * @since 1.4 232 */ 233 234 @Native public static final int IP_TOS = 0x3; 235 236 /** 237 * Specify a linger-on-close timeout. This option disables/enables 238 * immediate return from a <B>close()</B> of a TCP Socket. Enabling 239 * this option with a non-zero Integer <I>timeout</I> means that a 240 * <B>close()</B> will block pending the transmission and acknowledgement 241 * of all data written to the peer, at which point the socket is closed 242 * <I>gracefully</I>. Upon reaching the linger timeout, the socket is 243 * closed <I>forcefully</I>, with a TCP RST. Enabling the option with a 244 * timeout of zero does a forceful close immediately. If the specified 245 * timeout value exceeds 65,535 it will be reduced to 65,535. 246 * <P> 247 * Valid only for TCP: SocketImpl 248 * 249 * @see Socket#setSoLinger 250 * @see Socket#getSoLinger 251 */ 252 @Native public static final int SO_LINGER = 0x0080; 253 254 /** Set a timeout on blocking Socket operations: 255 * <PRE> 256 * ServerSocket.accept(); 257 * SocketInputStream.read(); 258 * DatagramSocket.receive(); 259 * </PRE> 260 * 261 * <P> The option must be set prior to entering a blocking 262 * operation to take effect. If the timeout expires and the 263 * operation would continue to block, 264 * <B>java.io.InterruptedIOException</B> is raised. The Socket is 265 * not closed in this case. 266 * 267 * <P> Valid for all sockets: SocketImpl, DatagramSocketImpl 268 * 269 * @see Socket#setSoTimeout 270 * @see ServerSocket#setSoTimeout 271 * @see DatagramSocket#setSoTimeout 272 */ 273 @Native public static final int SO_TIMEOUT = 0x1006; 274 275 /** 276 * Set a hint the size of the underlying buffers used by the 277 * platform for outgoing network I/O. When used in set, this is a 278 * suggestion to the kernel from the application about the size of 279 * buffers to use for the data to be sent over the socket. When 280 * used in get, this must return the size of the buffer actually 281 * used by the platform when sending out data on this socket. 282 * 283 * Valid for all sockets: SocketImpl, DatagramSocketImpl 284 * 285 * @see Socket#setSendBufferSize 286 * @see Socket#getSendBufferSize 287 * @see DatagramSocket#setSendBufferSize 288 * @see DatagramSocket#getSendBufferSize 289 */ 290 @Native public static final int SO_SNDBUF = 0x1001; 291 292 /** 293 * Set a hint the size of the underlying buffers used by the 294 * platform for incoming network I/O. When used in set, this is a 295 * suggestion to the kernel from the application about the size of 296 * buffers to use for the data to be received over the 297 * socket. When used in get, this must return the size of the 298 * buffer actually used by the platform when receiving in data on 299 * this socket. 300 * 301 * Valid for all sockets: SocketImpl, DatagramSocketImpl 302 * 303 * @see Socket#setReceiveBufferSize 304 * @see Socket#getReceiveBufferSize 305 * @see DatagramSocket#setReceiveBufferSize 306 * @see DatagramSocket#getReceiveBufferSize 307 */ 308 @Native public static final int SO_RCVBUF = 0x1002; 309 310 /** 311 * When the keepalive option is set for a TCP socket and no data 312 * has been exchanged across the socket in either direction for 313 * 2 hours (NOTE: the actual value is implementation dependent), 314 * TCP automatically sends a keepalive probe to the peer. This probe is a 315 * TCP segment to which the peer must respond. 316 * One of three responses is expected: 317 * 1. The peer responds with the expected ACK. The application is not 318 * notified (since everything is OK). TCP will send another probe 319 * following another 2 hours of inactivity. 320 * 2. The peer responds with an RST, which tells the local TCP that 321 * the peer host has crashed and rebooted. The socket is closed. 322 * 3. There is no response from the peer. The socket is closed. 323 * 324 * The purpose of this option is to detect if the peer host crashes. 325 * 326 * Valid only for TCP socket: SocketImpl 327 * 328 * @see Socket#setKeepAlive 329 * @see Socket#getKeepAlive 330 */ 331 @Native public static final int SO_KEEPALIVE = 0x0008; 332 333 /** 334 * When the OOBINLINE option is set, any TCP urgent data received on 335 * the socket will be received through the socket input stream. 336 * When the option is disabled (which is the default) urgent data 337 * is silently discarded. 338 * 339 * @see Socket#setOOBInline 340 * @see Socket#getOOBInline 341 */ 342 @Native public static final int SO_OOBINLINE = 0x1003; 343 } 344