Summary

ClassLoader.getSystemClassLoader() should clearly specify that an IllegalStateException is thrown in the case that a custom system classloader recursively calls getSystemClassLoader() during initialization.

Problem

The method description of ClassLoader.getSystemClassLoader() states (in regards to setting a custom system classloader):

"If circular initialization of the system class loader is detected then an unspecified error or exception is thrown."

That is inconsistent with the method @throws tag, which specifies this exception to be an IllegalStateException:

* @throws  IllegalStateException
*          If invoked recursively during the construction of the class
*          loader specified by the "{@code java.system.class.loader}"
*          property. 

The JDK 9 implementation throws InternalError which should be fixed to throw IllegalStateException as specified.

Solution

The method descriptor should state that an IllegalStateException is thrown, to match the @throws tag.
The previous (pre-9) behavior should be restored, to match the spec.

Specification

+++ b/src/java.base/share/classes/java/lang/ClassLoader.java    Mon Dec 04 13:41:04 2017 -0800
@@ -1867,7 +1868,7 @@ public abstract class ClassLoader {
      * to be the system class loader. During construction, the class loader
      * should take great care to avoid calling {@code getSystemClassLoader()}.
      * If circular initialization of the system class loader is detected then
-     * an unspecified error or exception is thrown.
+     * an {@code IllegalStateException} is thrown.
      * ...
     public static ClassLoader getSystemClassLoader()