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