1 /*
2 * Copyright (c) 2014, 2020, 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 jdk.net;
27
28 import java.io.FileDescriptor;
29 import java.net.SocketException;
30 import java.net.SocketOption;
31 import java.security.AccessController;
32 import java.security.PrivilegedAction;
33 import java.util.Collections;
34 import java.util.HashSet;
35 import java.util.Set;
36 import jdk.internal.access.JavaIOFileDescriptorAccess;
37 import jdk.internal.access.SharedSecrets;
38
39 /**
40 * Defines extended socket options, beyond those defined in
41 * {@link java.net.StandardSocketOptions}. These options may be platform
42 * specific.
43 *
44 * @since 1.8
45 */
46 public final class ExtendedSocketOptions {
47
48 private static class ExtSocketOption<T> implements SocketOption<T> {
49 private final String name;
50 private final Class<T> type;
51 ExtSocketOption(String name, Class<T> type) {
52 this.name = name;
53 this.type = type;
54 }
55 @Override public String name() { return name; }
56 @Override public Class<T> type() { return type; }
57 @Override public String toString() { return name; }
58 }
59
60 private ExtendedSocketOptions() { }
61
62 /**
63 * Service level properties. When a security manager is installed,
64 * setting or getting this option requires a {@link NetworkPermission}
65 * {@code ("setOption.SO_FLOW_SLA")} or {@code "getOption.SO_FLOW_SLA"}
66 * respectively.
67 * @deprecated This is supported only on Solaris. Due to deprecation
68 * of Solaris port, this option is also deprecated.
69 */
70 @Deprecated(since="14", forRemoval=true)
71 @SuppressWarnings("removal")
72 public static final SocketOption<SocketFlow> SO_FLOW_SLA = new
73 ExtSocketOption<SocketFlow>("SO_FLOW_SLA", SocketFlow.class);
74
75 /**
76 * Disable Delayed Acknowledgements.
77 *
78 * <p>
79 * This socket option can be used to reduce or disable delayed
80 * acknowledgments (ACKs). When {@code TCP_QUICKACK} is enabled, ACKs are
81 * sent immediately, rather than delayed if needed in accordance to normal
82 * TCP operation. This option is not permanent, it only enables a switch to
83 * or from {@code TCP_QUICKACK} mode. Subsequent operations of the TCP
84 * protocol will once again disable/enable {@code TCP_QUICKACK} mode
85 * depending on internal protocol processing and factors such as delayed ACK
86 * timeouts occurring and data transfer, therefore this option needs to be
87 * set with {@code setOption} after each operation of TCP on a given socket.
88 *
89 * <p>
90 * The value of this socket option is a {@code Boolean} that represents
91 * whether the option is enabled or disabled. The socket option is specific
92 * to stream-oriented sockets using the TCP/IP protocol. The exact semantics
93 * of this socket option are socket type and system dependent.
94 *
95 * @since 10
96 */
97 public static final SocketOption<Boolean> TCP_QUICKACK =
98 new ExtSocketOption<Boolean>("TCP_QUICKACK", Boolean.class);
99
100 /**
101 * Keep-Alive idle time.
102 *
103 * <p>
104 * The value of this socket option is an {@code Integer} that is the number
105 * of seconds of idle time before keep-alive initiates a probe. The socket
106 * option is specific to stream-oriented sockets using the TCP/IP protocol.
107 * The exact semantics of this socket option are system dependent.
108 *
109 * <p>
110 * When the {@link java.net.StandardSocketOptions#SO_KEEPALIVE
111 * SO_KEEPALIVE} option is enabled, TCP probes a connection that has been
112 * idle for some amount of time. The default value for this idle period is
113 * system dependent, but is typically 2 hours. The {@code TCP_KEEPIDLE}
114 * option can be used to affect this value for a given socket.
115 *
116 * @since 11
117 */
118 public static final SocketOption<Integer> TCP_KEEPIDLE
119 = new ExtSocketOption<Integer>("TCP_KEEPIDLE", Integer.class);
120
121 /**
122 * Keep-Alive retransmission interval time.
123 *
124 * <p>
125 * The value of this socket option is an {@code Integer} that is the number
126 * of seconds to wait before retransmitting a keep-alive probe. The socket
127 * option is specific to stream-oriented sockets using the TCP/IP protocol.
128 * The exact semantics of this socket option are system dependent.
129 *
130 * <p>
131 * When the {@link java.net.StandardSocketOptions#SO_KEEPALIVE
132 * SO_KEEPALIVE} option is enabled, TCP probes a connection that has been
133 * idle for some amount of time. If the remote system does not respond to a
134 * keep-alive probe, TCP retransmits the probe after some amount of time.
135 * The default value for this retransmission interval is system dependent,
136 * but is typically 75 seconds. The {@code TCP_KEEPINTERVAL} option can be
137 * used to affect this value for a given socket.
138 *
139 * @since 11
140 */
141 public static final SocketOption<Integer> TCP_KEEPINTERVAL
142 = new ExtSocketOption<Integer>("TCP_KEEPINTERVAL", Integer.class);
143
144 /**
145 * Keep-Alive retransmission maximum limit.
146 *
147 * <p>
148 * The value of this socket option is an {@code Integer} that is the maximum
149 * number of keep-alive probes to be sent. The socket option is specific to
150 * stream-oriented sockets using the TCP/IP protocol. The exact semantics of
151 * this socket option are system dependent.
152 *
153 * <p>
154 * When the {@link java.net.StandardSocketOptions#SO_KEEPALIVE
155 * SO_KEEPALIVE} option is enabled, TCP probes a connection that has been
156 * idle for some amount of time. If the remote system does not respond to a
157 * keep-alive probe, TCP retransmits the probe a certain number of times
158 * before a connection is considered to be broken. The default value for
159 * this keep-alive probe retransmit limit is system dependent, but is
160 * typically 8. The {@code TCP_KEEPCOUNT} option can be used to affect this
161 * value for a given socket.
162 *
163 * @since 11
164 */
165 public static final SocketOption<Integer> TCP_KEEPCOUNT
166 = new ExtSocketOption<Integer>("TCP_KEEPCOUNT", Integer.class);
167
168 /**
169 * Identifies the receive queue that the last incoming packet for the socket
170 * was received on.
171 *
172 * <p> The value of this socket option is a positive {@code Integer} that
173 * identifies a receive queue that the application can use to split the
174 * incoming flows among threads based on the queue identifier. The value is
175 * {@code 0} when the socket is not bound, a packet has not been received,
176 * or more generally, when there is no receive queue to identify.
177 * The socket option is supported by both stream-oriented and datagram-oriented
178 * sockets.
179 *
180 * <p> The socket option is read-only and an attempt to set the socket option
181 * will throw {@code SocketException}.
182 *
183 * @apiNote
184 * Network devices may have multiple queues or channels to transmit and receive
185 * network packets. The {@code SO_INCOMING_NAPI_ID} socket option provides a hint
186 * to the application to indicate the receive queue on which an incoming socket
187 * connection or packets for that connection are directed to. An application may
188 * take advantage of this by handling all socket connections assigned to a
189 * specific queue on one thread.
190 *
191 * @since 15
192 */
193 public static final SocketOption<Integer> SO_INCOMING_NAPI_ID
194 = new ExtSocketOption<Integer>("SO_INCOMING_NAPI_ID", Integer.class);
195
196 private static final PlatformSocketOptions platformSocketOptions =
197 PlatformSocketOptions.get();
198
199 private static final boolean flowSupported =
200 platformSocketOptions.flowSupported();
201 private static final boolean quickAckSupported =
202 platformSocketOptions.quickAckSupported();
203 private static final boolean keepAliveOptSupported =
204 platformSocketOptions.keepAliveOptionsSupported();
205 private static final boolean incomingNapiIdOptSupported =
206 platformSocketOptions.incomingNapiIdSupported();
207 private static final Set<SocketOption<?>> extendedOptions = options();
208
209 static Set<SocketOption<?>> options() {
210 Set<SocketOption<?>> options = new HashSet<>();
211 if (flowSupported) {
212 options.add(SO_FLOW_SLA);
213 }
214 if (quickAckSupported) {
215 options.add(TCP_QUICKACK);
216 }
217 if (incomingNapiIdOptSupported) {
218 options.add(SO_INCOMING_NAPI_ID);
219 }
220 if (keepAliveOptSupported) {
221 options.addAll(Set.of(TCP_KEEPCOUNT, TCP_KEEPIDLE, TCP_KEEPINTERVAL));
222 }
223 return Collections.unmodifiableSet(options);
224 }
225
226 static {
227 // Registers the extended socket options with the base module.
228 sun.net.ext.ExtendedSocketOptions.register(
229 new sun.net.ext.ExtendedSocketOptions(extendedOptions) {
230
231 @Override
232 @SuppressWarnings("removal")
233 public void setOption(FileDescriptor fd,
234 SocketOption<?> option,
235 Object value)
236 throws SocketException
237 {
238 SecurityManager sm = System.getSecurityManager();
239 if (sm != null)
240 sm.checkPermission(new NetworkPermission("setOption." + option.name()));
241
242 if (fd == null || !fd.valid())
243 throw new SocketException("socket closed");
244
245 if (option == SO_FLOW_SLA) {
246 assert flowSupported;
247 SocketFlow flow = checkValueType(value, SocketFlow.class);
248 setFlowOption(fd, flow);
249 } else if (option == TCP_QUICKACK) {
250 setQuickAckOption(fd, (boolean) value);
251 } else if (option == TCP_KEEPCOUNT) {
252 setTcpkeepAliveProbes(fd, (Integer) value);
253 } else if (option == TCP_KEEPIDLE) {
254 setTcpKeepAliveTime(fd, (Integer) value);
255 } else if (option == TCP_KEEPINTERVAL) {
256 setTcpKeepAliveIntvl(fd, (Integer) value);
257 } else if (option == SO_INCOMING_NAPI_ID) {
258 if (!incomingNapiIdOptSupported)
259 throw new UnsupportedOperationException("Attempt to set unsupported option " + option);
260 else
261 throw new SocketException("Attempt to set read only option " + option);
262 } else {
263 throw new InternalError("Unexpected option " + option);
264 }
265 }
266
267 @Override
268 @SuppressWarnings("removal")
269 public Object getOption(FileDescriptor fd,
270 SocketOption<?> option)
271 throws SocketException
272 {
273 SecurityManager sm = System.getSecurityManager();
274 if (sm != null)
275 sm.checkPermission(new NetworkPermission("getOption." + option.name()));
276
277 if (fd == null || !fd.valid())
278 throw new SocketException("socket closed");
279
280 if (option == SO_FLOW_SLA) {
281 assert flowSupported;
282 SocketFlow flow = SocketFlow.create();
283 getFlowOption(fd, flow);
284 return flow;
285 } else if (option == TCP_QUICKACK) {
286 return getQuickAckOption(fd);
287 } else if (option == TCP_KEEPCOUNT) {
288 return getTcpkeepAliveProbes(fd);
289 } else if (option == TCP_KEEPIDLE) {
290 return getTcpKeepAliveTime(fd);
291 } else if (option == TCP_KEEPINTERVAL) {
292 return getTcpKeepAliveIntvl(fd);
293 } else if (option == SO_INCOMING_NAPI_ID) {
294 return getIncomingNapiId(fd);
295 } else {
296 throw new InternalError("Unexpected option " + option);
297 }
298 }
299 });
300 }
301
302 @SuppressWarnings("unchecked")
303 private static <T> T checkValueType(Object value, Class<T> type) {
304 if (!type.isAssignableFrom(value.getClass())) {
305 String s = "Found: " + value.getClass() + ", Expected: " + type;
306 throw new IllegalArgumentException(s);
307 }
308 return (T) value;
309 }
310
311 private static final JavaIOFileDescriptorAccess fdAccess =
312 SharedSecrets.getJavaIOFileDescriptorAccess();
313
314 @SuppressWarnings("removal")
315 private static void setFlowOption(FileDescriptor fd, SocketFlow f)
316 throws SocketException
317 {
318 int status = platformSocketOptions.setFlowOption(fdAccess.get(fd),
319 f.priority(),
320 f.bandwidth());
321 f.status(status); // augment the given flow with the status
322 }
323
324 @SuppressWarnings("removal")
325 private static void getFlowOption(FileDescriptor fd, SocketFlow f)
326 throws SocketException {
327 int status = platformSocketOptions.getFlowOption(fdAccess.get(fd), f);
328 f.status(status); // augment the given flow with the status
329 }
330
331 private static void setQuickAckOption(FileDescriptor fd, boolean enable)
332 throws SocketException {
333 platformSocketOptions.setQuickAck(fdAccess.get(fd), enable);
334 }
335
336 private static Object getQuickAckOption(FileDescriptor fd)
337 throws SocketException {
338 return platformSocketOptions.getQuickAck(fdAccess.get(fd));
339 }
340
341 private static void setTcpkeepAliveProbes(FileDescriptor fd, int value)
342 throws SocketException {
343 platformSocketOptions.setTcpkeepAliveProbes(fdAccess.get(fd), value);
344 }
345
346 private static void setTcpKeepAliveTime(FileDescriptor fd, int value)
347 throws SocketException {
348 platformSocketOptions.setTcpKeepAliveTime(fdAccess.get(fd), value);
349 }
350
351 private static void setTcpKeepAliveIntvl(FileDescriptor fd, int value)
352 throws SocketException {
353 platformSocketOptions.setTcpKeepAliveIntvl(fdAccess.get(fd), value);
354 }
355
356 private static int getTcpkeepAliveProbes(FileDescriptor fd) throws SocketException {
357 return platformSocketOptions.getTcpkeepAliveProbes(fdAccess.get(fd));
358 }
359
360 private static int getTcpKeepAliveTime(FileDescriptor fd) throws SocketException {
361 return platformSocketOptions.getTcpKeepAliveTime(fdAccess.get(fd));
362 }
363
364 private static int getTcpKeepAliveIntvl(FileDescriptor fd) throws SocketException {
365 return platformSocketOptions.getTcpKeepAliveIntvl(fdAccess.get(fd));
366 }
367
368 private static int getIncomingNapiId(FileDescriptor fd) throws SocketException {
369 return platformSocketOptions.getIncomingNapiId(fdAccess.get(fd));
370 }
371
372 static class PlatformSocketOptions {
373
374 protected PlatformSocketOptions() {}
375
376 @SuppressWarnings("unchecked")
377 private static PlatformSocketOptions newInstance(String cn) {
378 Class<PlatformSocketOptions> c;
379 try {
380 c = (Class<PlatformSocketOptions>)Class.forName(cn);
381 return c.getConstructor(new Class<?>[] { }).newInstance();
382 } catch (ReflectiveOperationException x) {
383 throw new AssertionError(x);
384 }
385 }
386
387 private static PlatformSocketOptions create() {
388 String osname = AccessController.doPrivileged(
389 new PrivilegedAction<String>() {
390 public String run() {
391 return System.getProperty("os.name");
392 }
393 });
394 if ("Linux".equals(osname)) {
395 return newInstance("jdk.net.LinuxSocketOptions");
396 } else if (osname.startsWith("Mac")) {
397 return newInstance("jdk.net.MacOSXSocketOptions");
398 } else {
399 return new PlatformSocketOptions();
400 }
401 }
402
403 private static final PlatformSocketOptions instance = create();
404
405 static PlatformSocketOptions get() {
406 return instance;
407 }
408
409 int setFlowOption(int fd, int priority, long bandwidth)
410 throws SocketException
411 {
412 throw new UnsupportedOperationException("unsupported socket option");
413 }
414
415 @SuppressWarnings("removal")
416 int getFlowOption(int fd, SocketFlow f) throws SocketException {
417 throw new UnsupportedOperationException("unsupported socket option");
418 }
419
420 boolean flowSupported() {
421 return false;
422 }
423
424 void setQuickAck(int fd, boolean on) throws SocketException {
425 throw new UnsupportedOperationException("unsupported TCP_QUICKACK option");
426 }
427
428 boolean getQuickAck(int fd) throws SocketException {
429 throw new UnsupportedOperationException("unsupported TCP_QUICKACK option");
430 }
431
432 boolean quickAckSupported() {
433 return false;
434 }
435
436 boolean keepAliveOptionsSupported() {
437 return false;
438 }
439
440 void setTcpkeepAliveProbes(int fd, final int value) throws SocketException {
441 throw new UnsupportedOperationException("unsupported TCP_KEEPCNT option");
442 }
443
444 void setTcpKeepAliveTime(int fd, final int value) throws SocketException {
445 throw new UnsupportedOperationException("unsupported TCP_KEEPIDLE option");
446 }
447
448 void setTcpKeepAliveIntvl(int fd, final int value) throws SocketException {
449 throw new UnsupportedOperationException("unsupported TCP_KEEPINTVL option");
450 }
451
452 int getTcpkeepAliveProbes(int fd) throws SocketException {
453 throw new UnsupportedOperationException("unsupported TCP_KEEPCNT option");
454 }
455
456 int getTcpKeepAliveTime(int fd) throws SocketException {
457 throw new UnsupportedOperationException("unsupported TCP_KEEPIDLE option");
458 }
459
460 int getTcpKeepAliveIntvl(int fd) throws SocketException {
461 throw new UnsupportedOperationException("unsupported TCP_KEEPINTVL option");
462 }
463
464 boolean incomingNapiIdSupported() {
465 return false;
466 }
467
468 int getIncomingNapiId(int fd) throws SocketException {
469 throw new UnsupportedOperationException("unsupported SO_INCOMING_NAPI_ID socket option");
470 }
471 }
472 }