8241072: Reimplement the Legacy DatagramSocket API

Replace the underlying implementations of the java.net.DatagramSocket and java.net.MulticastSocket APIs with simpler and more modern implementations that are easy to maintain and debug.

Co-authored-by: Alan Bateman <alan.bateman@oracle.com>
Co-authored-by: Chris Hegarty <chris.hegarty@oracle.com>
Co-authored-by: Daniel Fuchs <daniel.fuchs@oracle.com>
Reviewed-by: alanb, chegar, dfuchs

Author: 4 people

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

@@ -32,6 +32,25 @@
 
 /**
  * Abstract datagram and multicast socket implementation base class.
+ *
+ * @implNote Sockets created with the {@code DatagramSocket} and {@code
+ * MulticastSocket} public constructors historically delegated all socket
+ * operations to a {@code DatagramSocketImpl} implementation named
+ * "PlainDatagramSocketImpl". {@code DatagramSocket} and {@code MulticastSocket}
+ * have since been changed to a new implementation based on {@code DatagramChannel}.
+ * The JDK continues to ship with the older implementation to allow code to run
+ * that depends on unspecified behavior that differs between the old and new
+ * implementations. The old implementation will be used if the Java virtual
+ * machine is started with the system property {@systemProperty
+ * jdk.net.usePlainDatagramSocketImpl} set to use the old implementation. It may
+ * also be set in the JDK's network configuration file, located in {@code
+ * ${java.home}/conf/net.properties}. The value of the property is the string
+ * representation of a boolean. If set without a value then it defaults to {@code
+ * true}, hence running with {@code -Djdk.net.usePlainDatagramSocketImpl} or
+ * {@code -Djdk.net.usePlainDatagramSocketImpl=true} will configure the Java
+ * virtual machine to use the old implementation. The property and old
+ * implementation will be removed in a future version.
+ *
  * @author Pavani Diwanji
  * @since  1.1
  */