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 }