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 private static final PlatformSocketOptions platformSocketOptions =
184 PlatformSocketOptions.get();
185
186 private static final boolean quickAckSupported =
187 platformSocketOptions.quickAckSupported();
188 private static final boolean keepAliveOptSupported =
189 platformSocketOptions.keepAliveOptionsSupported();
190 private static final boolean incomingNapiIdOptSupported =
191 platformSocketOptions.incomingNapiIdSupported();
192 private static final Set<SocketOption<?>> extendedOptions = options();
193
194 static Set<SocketOption<?>> options() {
195 Set<SocketOption<?>> options = new HashSet<>();
196 if (quickAckSupported) {
197 options.add(TCP_QUICKACK);
198 }
199 if (incomingNapiIdOptSupported) {
200 options.add(SO_INCOMING_NAPI_ID);
201 }
202 if (keepAliveOptSupported) {
203 options.addAll(Set.of(TCP_KEEPCOUNT, TCP_KEEPIDLE, TCP_KEEPINTERVAL));
204 }
205 return Collections.unmodifiableSet(options);
206 }
207
208 static {
209 // Registers the extended socket options with the base module.
210 sun.net.ext.ExtendedSocketOptions.register(
211 new sun.net.ext.ExtendedSocketOptions(extendedOptions) {
212
213 @Override
214 @SuppressWarnings("removal")
215 public void setOption(FileDescriptor fd,
216 SocketOption<?> option,
217 Object value)
218 throws SocketException
219 {
220 if (fd == null || !fd.valid())
221 throw new SocketException("socket closed");
222
223 if (option == TCP_QUICKACK) {
224 setQuickAckOption(fd, (boolean) value);
225 } else if (option == TCP_KEEPCOUNT) {
226 setTcpkeepAliveProbes(fd, (Integer) value);
227 } else if (option == TCP_KEEPIDLE) {
228 setTcpKeepAliveTime(fd, (Integer) value);
229 } else if (option == TCP_KEEPINTERVAL) {
230 setTcpKeepAliveIntvl(fd, (Integer) value);
231 } else if (option == SO_INCOMING_NAPI_ID) {
232 if (!incomingNapiIdOptSupported)
233 throw new UnsupportedOperationException("Attempt to set unsupported option " + option);
234 else
235 throw new SocketException("Attempt to set read only option " + option);
236 } else {
237 throw new InternalError("Unexpected option " + option);
238 }
239 }
240
241 @Override
242 @SuppressWarnings("removal")
243 public Object getOption(FileDescriptor fd,
244 SocketOption<?> option)
245 throws SocketException
246 {
247 if (fd == null || !fd.valid())
248 throw new SocketException("socket closed");
249
250 if (option == TCP_QUICKACK) {
251 return getQuickAckOption(fd);
252 } else if (option == TCP_KEEPCOUNT) {
253 return getTcpkeepAliveProbes(fd);
254 } else if (option == TCP_KEEPIDLE) {
255 return getTcpKeepAliveTime(fd);
256 } else if (option == TCP_KEEPINTERVAL) {
257 return getTcpKeepAliveIntvl(fd);
258 } else if (option == SO_INCOMING_NAPI_ID) {
259 return getIncomingNapiId(fd);
260 } else {
261 throw new InternalError("Unexpected option " + option);
262 }
263 }
264 });
265 }
266
267 private static final JavaIOFileDescriptorAccess fdAccess =
268 SharedSecrets.getJavaIOFileDescriptorAccess();
269
270 private static void setQuickAckOption(FileDescriptor fd, boolean enable)
271 throws SocketException {
272 platformSocketOptions.setQuickAck(fdAccess.get(fd), enable);
273 }
274
275 private static Object getQuickAckOption(FileDescriptor fd)
276 throws SocketException {
277 return platformSocketOptions.getQuickAck(fdAccess.get(fd));
278 }
279
280 private static void setTcpkeepAliveProbes(FileDescriptor fd, int value)
281 throws SocketException {
282 platformSocketOptions.setTcpkeepAliveProbes(fdAccess.get(fd), value);
283 }
284
285 private static void setTcpKeepAliveTime(FileDescriptor fd, int value)
286 throws SocketException {
287 platformSocketOptions.setTcpKeepAliveTime(fdAccess.get(fd), value);
288 }
289
290 private static void setTcpKeepAliveIntvl(FileDescriptor fd, int value)
291 throws SocketException {
292 platformSocketOptions.setTcpKeepAliveIntvl(fdAccess.get(fd), value);
293 }
294
295 private static int getTcpkeepAliveProbes(FileDescriptor fd) throws SocketException {
296 return platformSocketOptions.getTcpkeepAliveProbes(fdAccess.get(fd));
297 }
298
299 private static int getTcpKeepAliveTime(FileDescriptor fd) throws SocketException {
300 return platformSocketOptions.getTcpKeepAliveTime(fdAccess.get(fd));
301 }
302
303 private static int getTcpKeepAliveIntvl(FileDescriptor fd) throws SocketException {
304 return platformSocketOptions.getTcpKeepAliveIntvl(fdAccess.get(fd));
305 }
306
307 private static int getIncomingNapiId(FileDescriptor fd) throws SocketException {
308 return platformSocketOptions.getIncomingNapiId(fdAccess.get(fd));
309 }
310
311 static class PlatformSocketOptions {
312
313 protected PlatformSocketOptions() {}
314
315 @SuppressWarnings("unchecked")
316 private static PlatformSocketOptions newInstance(String cn) {
317 Class<PlatformSocketOptions> c;
318 try {
319 c = (Class<PlatformSocketOptions>)Class.forName(cn);
320 return c.getConstructor(new Class<?>[] { }).newInstance();
321 } catch (ReflectiveOperationException x) {
322 throw new AssertionError(x);
323 }
324 }
325
326 private static PlatformSocketOptions create() {
327 String osname = AccessController.doPrivileged(
328 new PrivilegedAction<String>() {
329 public String run() {
330 return System.getProperty("os.name");
331 }
332 });
333 if ("Linux".equals(osname)) {
334 return newInstance("jdk.net.LinuxSocketOptions");
335 } else if (osname.startsWith("Mac")) {
336 return newInstance("jdk.net.MacOSXSocketOptions");
337 } else {
338 return new PlatformSocketOptions();
339 }
340 }
341
342 private static final PlatformSocketOptions instance = create();
343
344 static PlatformSocketOptions get() {
345 return instance;
346 }
347
348 void setQuickAck(int fd, boolean on) throws SocketException {
349 throw new UnsupportedOperationException("unsupported TCP_QUICKACK option");
350 }
351
352 boolean getQuickAck(int fd) throws SocketException {
353 throw new UnsupportedOperationException("unsupported TCP_QUICKACK option");
354 }
355
356 boolean quickAckSupported() {
357 return false;
358 }
359
360 boolean keepAliveOptionsSupported() {
361 return false;
362 }
363
364 void setTcpkeepAliveProbes(int fd, final int value) throws SocketException {
365 throw new UnsupportedOperationException("unsupported TCP_KEEPCNT option");
366 }
367
368 void setTcpKeepAliveTime(int fd, final int value) throws SocketException {
369 throw new UnsupportedOperationException("unsupported TCP_KEEPIDLE option");
370 }
371
372 void setTcpKeepAliveIntvl(int fd, final int value) throws SocketException {
373 throw new UnsupportedOperationException("unsupported TCP_KEEPINTVL option");
374 }
375
376 int getTcpkeepAliveProbes(int fd) throws SocketException {
377 throw new UnsupportedOperationException("unsupported TCP_KEEPCNT option");
378 }
379
380 int getTcpKeepAliveTime(int fd) throws SocketException {
381 throw new UnsupportedOperationException("unsupported TCP_KEEPIDLE option");
382 }
383
384 int getTcpKeepAliveIntvl(int fd) throws SocketException {
385 throw new UnsupportedOperationException("unsupported TCP_KEEPINTVL option");
386 }
387
388 boolean incomingNapiIdSupported() {
389 return false;
390 }
391
392 int getIncomingNapiId(int fd) throws SocketException {
393 throw new UnsupportedOperationException("unsupported SO_INCOMING_NAPI_ID socket option");
394 }
395 }
396 }