8356154: Respecify java.net.Socket constructors that allow creating UDP sockets to throw IllegalArgumentException

Reviewed-by: dfuchs, alanb

Author: jaikiran

src/java.base/share/classes/java/net/Socket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -378,27 +378,22 @@ public Socket(InetAddress address, int port, InetAddress localAddr,
      * In other words, it is equivalent to specifying an address of the
      * loopback interface. </p>
      * <p>
-     * If the stream argument is {@code true}, this creates a
-     * stream socket. If the stream argument is {@code false}, it
-     * creates a datagram socket.
-     * <p>
      * If the application has specified a {@linkplain SocketImplFactory client
      * socket implementation factory}, that factory's
      * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl}
      * method is called to create the actual socket implementation. Otherwise
      * a system-default socket implementation is created.
-     * <p>
-     * If a UDP socket is used, TCP/IP related socket options will not apply.
      *
      * @param      host     the host name, or {@code null} for the loopback address.
      * @param      port     the port number.
-     * @param      stream   a {@code boolean} indicating whether this is
-     *                      a stream socket or a datagram socket.
+     * @param      stream   must be true, false is not allowed.
      * @throws     IOException  if an I/O error occurs when creating the socket.
-     * @throws     IllegalArgumentException if the port parameter is outside
-     *             the specified range of valid port values, which is between
-     *             0 and 65535, inclusive.
-     * @deprecated Use {@link DatagramSocket} instead for UDP transport.
+     * @throws     IllegalArgumentException if the stream parameter is {@code false}
+     *             or if the port parameter is outside the specified range of valid
+     *             port values, which is between 0 and 65535, inclusive.
+     * @deprecated The {@code stream} parameter provided a way in early JDK releases
+     *             to create a {@code Socket} that used a datagram socket. This feature
+     *             no longer exists. Instead use {@link DatagramSocket} for datagram sockets.
      */
     @Deprecated(forRemoval = true, since = "1.1")
     @SuppressWarnings("this-escape")
@@ -412,28 +407,23 @@ public Socket(String host, int port, boolean stream) throws IOException {
      * Creates a socket and connects it to the specified port number at
      * the specified IP address.
      * <p>
-     * If the stream argument is {@code true}, this creates a
-     * stream socket. If the stream argument is {@code false}, it
-     * creates a datagram socket.
-     * <p>
      * If the application has specified a {@linkplain SocketImplFactory client
      * socket implementation factory}, that factory's
      * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl}
      * method is called to create the actual socket implementation. Otherwise
      * a system-default socket implementation is created.
-     * <p>
-     * If UDP socket is used, TCP/IP related socket options will not apply.
      *
      * @param      host     the IP address.
      * @param      port      the port number.
-     * @param      stream    if {@code true}, create a stream socket;
-     *                       otherwise, create a datagram socket.
+     * @param      stream    must be true, false is not allowed.
      * @throws     IOException  if an I/O error occurs when creating the socket.
-     * @throws     IllegalArgumentException if the port parameter is outside
-     *             the specified range of valid port values, which is between
-     *             0 and 65535, inclusive.
+     * @throws     IllegalArgumentException if the stream parameter is {@code false}
+     *             or if the port parameter is outside the specified range of valid
+     *             port values, which is between 0 and 65535, inclusive.
      * @throws     NullPointerException if {@code host} is null.
-     * @deprecated Use {@link DatagramSocket} instead for UDP transport.
+     * @deprecated The {@code stream} parameter provided a way in early JDK releases
+     *             to create a {@code Socket} that used a datagram socket. This feature
+     *             no longer exists. Instead use {@link DatagramSocket} for datagram sockets.
      */
     @Deprecated(forRemoval = true, since = "1.1")
     @SuppressWarnings("this-escape")
@@ -454,6 +444,10 @@ private Socket(SocketAddress address, SocketAddress localAddr, boolean stream)
         throws IOException
     {
         Objects.requireNonNull(address);
+        if (!stream) {
+            throw new IllegalArgumentException(
+                    "Socket constructor does not support creation of datagram sockets");
+        }
         assert address instanceof InetSocketAddress;
 
         // create the SocketImpl and the underlying socket

src/java.base/share/classes/java/net/SocketImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -78,15 +78,16 @@ static <S extends SocketImpl & PlatformSocketImpl> S createPlatformSocketImpl(bo
     public SocketImpl() { }
 
     /**
-     * Creates either a stream or a datagram socket.
+     * Creates a stream socket.
      *
      * @apiNote
-     * The {@link Socket} constructors to create a datagram socket
-     * are deprecated for removal. This method will be re-specified
-     * in a future release to not support creating datagram sockets.
+     * The {@code stream} parameter provided a way in early JDK releases
+     * to create a {@link Socket} that used a datagram socket.
+     * The Socket API no longer provides a way to do this, so the
+     * {@code create} method will always be called with a {@code stream}
+     * value of {@code true}.
      *
-     * @param      stream   if {@code true}, create a stream socket;
-     *                      otherwise, create a datagram socket.
+     * @param      stream   must be {@code true}.
      * @throws     IOException  if an I/O error occurs while creating the
      *               socket.
      */

src/java.base/share/classes/sun/nio/ch/AsynchronousServerSocketChannelImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -69,7 +69,7 @@ abstract class AsynchronousServerSocketChannelImpl
 
     AsynchronousServerSocketChannelImpl(AsynchronousChannelGroupImpl group) {
         super(group.provider());
-        this.fd = Net.serverSocket(true);
+        this.fd = Net.serverSocket();
     }
 
     @Override

src/java.base/share/classes/sun/nio/ch/AsynchronousSocketChannelImpl.java

@@ -88,7 +88,7 @@ abstract class AsynchronousSocketChannelImpl
         throws IOException
     {
         super(group.provider());
-        this.fd = Net.socket(true);
+        this.fd = Net.socket();
         this.state = ST_UNCONNECTED;
     }
 

src/java.base/share/classes/sun/nio/ch/Net.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -470,8 +470,8 @@ private static boolean isFastTcpLoopbackRequested() {
 
     private static native boolean canUseIPv6OptionsWithIPv4LocalAddress0();
 
-    static FileDescriptor socket(boolean stream) throws IOException {
-        return socket(UNSPEC, stream);
+    static FileDescriptor socket() throws IOException {
+        return socket(UNSPEC, true);
     }
 
     static FileDescriptor socket(ProtocolFamily family, boolean stream) throws IOException {
@@ -480,14 +480,14 @@ static FileDescriptor socket(ProtocolFamily family, boolean stream) throws IOExc
         return IOUtil.newFD(socket0(preferIPv6, stream, false, FAST_LOOPBACK));
     }
 
-    static FileDescriptor serverSocket(boolean stream) {
-        return serverSocket(UNSPEC, stream);
+    static FileDescriptor serverSocket() {
+        return serverSocket(UNSPEC);
     }
 
-    static FileDescriptor serverSocket(ProtocolFamily family, boolean stream) {
+    static FileDescriptor serverSocket(ProtocolFamily family) {
         boolean preferIPv6 = isIPv6Available() &&
             (family != StandardProtocolFamily.INET);
-        return IOUtil.newFD(socket0(preferIPv6, stream, true, FAST_LOOPBACK));
+        return IOUtil.newFD(socket0(preferIPv6, true, true, FAST_LOOPBACK));
     }
 
     // Due to oddities SO_REUSEADDR on Windows reuse is ignored

src/java.base/share/classes/sun/nio/ch/NioSocketImpl.java

@@ -100,8 +100,6 @@ public final class NioSocketImpl extends SocketImpl implements PlatformSocketImp
     private static final int ST_CLOSED = 5;
     private volatile int state;  // need stateLock to change
 
-    // set by SocketImpl.create, protected by stateLock
-    private boolean stream;
     private Cleanable cleaner;
 
     // set to true when the socket is in non-blocking mode
@@ -451,19 +449,20 @@ private void write(byte[] b, int off, int len) throws IOException {
      */
     @Override
     protected void create(boolean stream) throws IOException {
+        if (!stream) {
+            throw new IOException("Datagram socket creation not supported");
+        }
         synchronized (stateLock) {
             if (state != ST_NEW)
                 throw new IOException("Already created");
             FileDescriptor fd;
             if (server) {
-                assert stream;
-                fd = Net.serverSocket(true);
+                fd = Net.serverSocket();
             } else {
-                fd = Net.socket(stream);
+                fd = Net.socket();
             }
-            Runnable closer = closerFor(fd, stream);
+            Runnable closer = closerFor(fd);
             this.fd = fd;
-            this.stream = stream;
             this.cleaner = CleanerFactory.cleaner().register(this, closer);
             this.state = ST_UNCONNECTED;
         }
@@ -653,8 +652,6 @@ protected void listen(int backlog) throws IOException {
     private FileDescriptor beginAccept() throws SocketException {
         synchronized (stateLock) {
             ensureOpen();
-            if (!stream)
-                throw new SocketException("Not a stream socket");
             if (localport == 0)
                 throw new SocketException("Not bound");
             readerThread = NativeThread.current();
@@ -764,10 +761,9 @@ protected void accept(SocketImpl si) throws IOException {
         }
 
         // set the fields
-        Runnable closer = closerFor(newfd, true);
+        Runnable closer = closerFor(newfd);
         synchronized (nsi.stateLock) {
             nsi.fd = newfd;
-            nsi.stream = true;
             nsi.cleaner = CleanerFactory.cleaner().register(nsi, closer);
             nsi.localport = localAddress.getPort();
             nsi.address = isaa[0].getAddress();
@@ -1187,24 +1183,14 @@ protected void sendUrgentData(int data) throws IOException {
     /**
      * Returns an action to close the given file descriptor.
      */
-    private static Runnable closerFor(FileDescriptor fd, boolean stream) {
-        if (stream) {
-            return () -> {
-                try {
-                    nd.close(fd);
-                } catch (IOException ioe) {
-                    throw new UncheckedIOException(ioe);
-                }
-            };
-        } else {
-            return () -> {
-                try {
-                    nd.close(fd);
-                } catch (IOException ioe) {
-                    throw new UncheckedIOException(ioe);
-                }
-            };
-        }
+    private static Runnable closerFor(FileDescriptor fd) {
+        return () -> {
+            try {
+                nd.close(fd);
+            } catch (IOException ioe) {
+                throw new UncheckedIOException(ioe);
+            }
+        };
     }
 
     /**

src/java.base/share/classes/sun/nio/ch/ServerSocketChannelImpl.java

@@ -132,7 +132,7 @@ class ServerSocketChannelImpl
         if (family == UNIX) {
             this.fd = UnixDomainSockets.socket();
         } else {
-            this.fd = Net.serverSocket(family, true);
+            this.fd = Net.serverSocket(family);
         }
         this.fdVal = IOUtil.fdVal(fd);
     }

test/jdk/java/net/Socket/UdpSocket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -21,61 +21,52 @@
  * questions.
  */
 
-/**
- * @test
- * @run testng/othervm UdpSocket
- * @summary Basic test for a Socket to a UDP socket
- */
-
-import java.io.IOException;
 import java.net.InetAddress;
-import java.net.InetSocketAddress;
 import java.net.Socket;
-import java.net.SocketAddress;
-import java.nio.ByteBuffer;
-import java.nio.channels.DatagramChannel;
-import java.util.Arrays;
 
 import org.testng.annotations.Test;
-import static org.testng.Assert.*;
+import static org.testng.Assert.fail;
 
-@Test
+/*
+ * @test
+ * @summary Basic test for the UDP sockets through the java.net.Socket constructors
+ * @run testng UdpSocket
+ */
 public class UdpSocket {
 
-    private static final int MAX_RETRIES = 3;
-
     /**
-     * Test using the Socket API to send/receive datagrams
+     * Verifies that the {@code Socket} constructors that take the {@code stream}
+     * parameter don't allow construction of UDP sockets.
      */
-    public void testSendReceive() throws IOException {
-        final String MESSAGE = "hello";
-
-        try (DatagramChannel dc = DatagramChannel.open()) {
-            var loopback = InetAddress.getLoopbackAddress();
-            dc.bind(new InetSocketAddress(loopback, 0));
-
-            int port = ((InetSocketAddress) dc.getLocalAddress()).getPort();
-            try (Socket s = new Socket(loopback, port, false)) {
-                // send datagram with socket output stream
-                byte[] array1 = MESSAGE.getBytes("UTF-8");
-                s.getOutputStream().write(array1);
-
-                // receive the datagram
-                var buf = ByteBuffer.allocate(100);
-                SocketAddress remote = dc.receive(buf);
-                buf.flip();
-                assertTrue(buf.remaining() == MESSAGE.length(), "Unexpected size");
+    @Test
+    public void testUDPConstructors() throws Exception {
+        try {
+            new Socket("doesnotmatter", 12345, false);
+            fail("Socket constructor was expected to throw IllegalArgumentException" +
+                    " for stream=false, but didn't");
+        } catch (IllegalArgumentException iae) {
+            // verify it's thrown for the right reason
+            assertExceptionMessage(iae);
+        }
 
-                // echo the datagram
-                dc.send(buf, remote);
+        try {
+            new Socket(InetAddress.getLoopbackAddress(), 12345, false);
+            fail("Socket constructor was expected to throw IllegalArgumentException" +
+                    " for stream=false, but didn't");
+        } catch (IllegalArgumentException iae) {
+            // verify it's thrown for the right reason
+            assertExceptionMessage(iae);
+        }
+    }
 
-                // receive datagram with the socket input stream
-                byte[] array2 = new byte[100];
-                int n = s.getInputStream().read(array2);
-                assertTrue(n == MESSAGE.length(), "Unexpected size");
-                assertEquals(Arrays.copyOf(array1, n), Arrays.copyOf(array2, n),
-                            "Unexpected contents");
-            }
+    private static void assertExceptionMessage(final IllegalArgumentException iae) {
+        final String msg = iae.getMessage();
+        if (msg != null && msg.contains(
+                "Socket constructor does not support creation of datagram socket")) {
+            // contains the expected message
+            return;
         }
+        // unexpected exception message, propagate the original exception
+        throw iae;
     }
 }