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
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 */
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 }