JDK-8223103 : Document the jdk.net.URLClassPath.showIgnoredClassPathEntries system property
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang:class_loading
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 13
  • Submitted: 2019-04-29
  • Updated: 2019-05-01
  • Resolved: 2019-05-01
Related Reports
CSR :  
Description
Summary
-------

The `jdk.net.URLClassPath.showIgnoredClassPathEntries` system property should be documented in the JavaDoc.

Problem
-------

The `jdk.net.URLClassPath.showIgnoredClassPathEntries` system property was added in JDK-8211941 to assist in debugging of invalid Class-Path attributes in JAR file manifests.  It will be mentioned in the Release Notes, but should also be mentioned somewhere more accessible - in the JavaDoc.

Solution
--------

Problems with an invalid Class-Path entry would turn up during classloading.  A reasonable place to document the `jdk.net.URLClassPath.showIgnoredClassPathEntries` property is in `ClassLoader.getSystemClassLoader()`, which already has an @implNote describing the use of other classloading-related system properties.

Using the @systemProperty tag will allow the property name to be found in the JavaDoc search box.


Specification
-------------

    --- a/src/java.base/share/classes/java/lang/ClassLoader.java    Fri Apr 26 12:49:51 2019 -0400
    +++ b/src/java.base/share/classes/java/lang/ClassLoader.java    Mon Apr 29 14:58:54 2019 -0700
    @@ -1893,6 +1893,16 @@
          * otherwise, if unnamed, it will set the class path to the current
          * working directory.
          *
    +     * <p> JAR files on the class path may contain a {@code Class-Path} manifest
    +     * attribute to specify dependent JAR files to be included in the class path.
    +     * {@code Class-Path} entries must meet certain conditions for validity (see
    +     * the <a href="{@docRoot}/../specs/jar/jar.html#class-path-attribute">
    +     * JAR File Specification</a> for details).  Invalid {@code Class-Path}
    +     * entries are ignored.  For debugging purposes, ignored entries can be
    +     * printed to the console if the
    +     * {@systemProperty jdk.net.URLClassPath.showIgnoredClassPathEntries} system
    +     * property is set to {@code true}.
    +     *
            * ...
    public static ClassLoader getSystemClassLoader()





Comments
Moving to Approved.
01-05-2019