--- a/src/java.base/share/classes/java/net/SocketImpl.java	Wed Mar 20 13:54:50 2019 +0000
+++ b/src/java.base/share/classes/java/net/SocketImpl.java	Thu Mar 21 08:41:10 2019 +0000
@@ -41,9 +41,18 @@
  * The abstract class {@code SocketImpl} is a common superclass
  * of all classes that actually implement sockets. It is used to
  * create both client and server sockets.
- * <p>
- * A "plain" socket implements these methods exactly as
- * described, without attempting to go through a firewall or proxy.
+ *
+ * @implNote The JDK historically used a {@code SocketImpl} implementation named
+ * <em>PlainSocketImpl</em>. This has been replaced by a simpler and more modern
+ * implementation but the JDK continues to ship with the older implementation
+ * to allow code that depends on unspecified behavior, that differs between the
+ * old and new implementations, to continue to run. The old implementation
+ * will be used if the Java virtual machine is started with the system property
+ * {@systemProperty jdk.net.usePlainSocketImpl} set on the command line. The
+ * value of the system property is a boolean. If set without a value then it
+ * defaults to {@code true}, hence running with {@code -Djdk.net.usePlainSocketImpl}
+ * or {@code -Djdk.net.usePlainSocketImpl=true} will configure the Java virtual
+ * machine use the old implementation.
  *
  * @author  unascribed
  * @since   1.0