8039470: java.net Content Handler API incorrectly specifies implementation specific location of handler classes

Reviewed-by: alanb, michaelm

jdk/src/share/classes/java/net/ContentHandler.java

@@ -46,15 +46,28 @@ import java.io.IOException;
  * <p>
  * If no content handler could be found, URLConnection will
  * look for a content handler in a user-defineable set of places.
- * By default it looks in sun.net.www.content, but users can define a
- * vertical-bar delimited set of class prefixes to search through in
- * addition by defining the java.content.handler.pkgs property.
- * The class name must be of the form:
- * <pre>
- *     {package-prefix}.{major}.{minor}
- * e.g.
+ * Users can define a vertical-bar delimited set of class prefixes
+ * to search through by defining the <i>java.content.handler.pkgs</i>
+ * property. The class name must be of the form:
+ * <blockquote>
+ *     <i>{package-prefix}.{major}.{minor}</i>
+ *     <P>
+ *     where <i>{major}.{minor}</i> is formed by taking the
+ *     content-type string, replacing all slash characters with a
+ *     {@code period} ('.'), and all other non-alphanumeric characters
+ *     with the underscore character '{@code _}'. The alphanumeric
+ *     characters are specifically the 26 uppercase ASCII letters
+ *     '{@code A}' through '{@code Z}', the 26 lowercase ASCII
+ *     letters '{@code a}' through '{@code z}', and the 10 ASCII
+ *     digits '{@code 0}' through '{@code 9}'.
+ *     <p>
+ *     e.g.
  *     YoyoDyne.experimental.text.plain
- * </pre>
+ * </blockquote>
+ * If no user-defined content handler is found, then the system
+ * tries to load a specific <i>content-type</i> handler from one
+ * of the built-in handlers, if one exists.
+ * <p>
  * If the loading of the content handler class would be performed by
  * a classloader that is outside of the delegation chain of the caller,
  * the JVM will need the RuntimePermission "getClassLoader".

jdk/src/share/classes/java/net/URL.java

@@ -266,10 +266,7 @@ public final class URL implements java.io.Serializable {
      *     a subclass of {@code URLStreamHandler}, then the next package
      *     in the list is tried.
      * <li>If the previous step fails to find a protocol handler, then the
-     *     constructor tries to load from a system default package.
-     *     <blockquote><pre>
-     *         &lt;<i>system default package</i>&gt;.&lt;<i>protocol</i>&gt;.Handler
-     *     </pre></blockquote>
+     *     constructor tries to load a built-in protocol handler.
      *     If this class does not exist, or if the class exists but it is not a
      *     subclass of {@code URLStreamHandler}, then a
      *     {@code MalformedURLException} is thrown.

jdk/src/share/classes/java/net/URLConnection.java

@@ -704,21 +704,10 @@ public abstract class URLConnection {
      *     handler for that content type.
      * <li>If no content handler factory has yet been set up, or if the
      *     factory's {@code createContentHandler} method returns
-     *     {@code null}, then the application loads the class named:
-     *     <blockquote><pre>
-     *         sun.net.www.content.&lt;<i>contentType</i>&gt;
-     *     </pre></blockquote>
-     *     where &lt;<i>contentType</i>&gt; is formed by taking the
-     *     content-type string, replacing all slash characters with a
-     *     {@code period} ('.'), and all other non-alphanumeric characters
-     *     with the underscore character '{@code _}'. The alphanumeric
-     *     characters are specifically the 26 uppercase ASCII letters
-     *     '{@code A}' through '{@code Z}', the 26 lowercase ASCII
-     *     letters '{@code a}' through '{@code z}', and the 10 ASCII
-     *     digits '{@code 0}' through '{@code 9}'. If the specified
-     *     class does not exist, or is not a subclass of
-     *     {@code ContentHandler}, then an
-     *     {@code UnknownServiceException} is thrown.
+     *     {@code null}, then this method tries to load a content handler
+     *     class as defined by {@link java.net.ContentHandler ContentHandler}.
+     *     If the class does not exist, or is not a subclass of {@code
+     *     ContentHandler}, then an {@code UnknownServiceException} is thrown.
      * </ol>
      *
      * @return     the object fetched. The {@code instanceof} operator