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