src/java.instrument/share/classes/java/lang/instrument/Instrumentation.java

rev 58874 : imported patch svc-spec-update

*** 386,408 ****
      isModifiableClass(Class<?> theClass);
  
      /**
       * Returns an array of all classes currently loaded by the JVM.
       *
       * @return an array containing all the classes loaded by the JVM, zero-length if there are none
       */
      @SuppressWarnings("rawtypes")
      Class[]
      getAllLoadedClasses();
  
      /**
!      * Returns an array of all classes for which <code>loader</code> is an initiating loader.
!      * If the supplied loader is <code>null</code>, classes initiated by the bootstrap class
!      * loader are returned.
       *
       * @param loader          the loader whose initiated class list will be returned
!      * @return an array containing all the classes for which loader is an initiating loader,
       *          zero-length if there are none
       */
      @SuppressWarnings("rawtypes")
      Class[]
      getInitiatedClasses(ClassLoader loader);
--- 386,448 ----
      isModifiableClass(Class<?> theClass);
  
      /**
       * Returns an array of all classes currently loaded by the JVM.
       *
+      * <p>
+      * A class or interface creation can be triggered by one of the following:
+      * <ul>
+      * <li>by loading and deriving a class from a {@code class} file representation
+      *     using class loader (see JVMS {@jvms 5.3}).
+      * <li>by invoking {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, java.lang.invoke.MethodHandles.Lookup.ClassOption...)
+      *     Lookup::defineHiddenClass} that creates a {@link Class#isHidden
+      *     hidden class or interface} from a {@code class} file representation.
+      * <li>by invoking methods in certain reflection APIs such as
+      *     {@link Class#forName(String) Class::forName}.
+      * </ul>
+      * <p>
+      * An array class is created directly by Java virtual machine.  An array
+      * class creation can be triggered by using class loaders or by invoking
+      * methods in certain reflection APIs such as
+      * {@link java.lang.reflect.Array#newInstance(Class, int) Array::newInstance}
+      * and {@link Class#arrayType() Class::arrayType}.
+      * <p>
+      * The returned array includes all classes and interfaces, including
+      * {@link Class#isHidden hidden classes or interfaces}, and array classes
+      * of all types.
+      *
       * @return an array containing all the classes loaded by the JVM, zero-length if there are none
       */
      @SuppressWarnings("rawtypes")
      Class[]
      getAllLoadedClasses();
  
      /**
!      * Returns an array of all classes which {@code loader} can find by name
!      * via {@link ClassLoader#loadClass(String, boolean) ClassLoader::loadClass},
!      * {@link Class#forName(String) Class::forName} and bytecode linkage.
!      * That is, {@code loader} has been recorded as an initiating loader
!      * of these classes. If the supplied {@code loader} is {@code null},
!      * classes that the bootstrap class loader can find by name are returned.
!      *
!      * <p>
!      * The returned array does not include {@link Class#isHidden()
!      * <em>hidden</em>} classes or interfaces that are created by the invocation of
!      * {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, java.lang.invoke.MethodHandles.Lookup.ClassOption...)
!      * Lookup::defineHiddenClass} because:
!      * <ul>
!      * <li>A hidden class or interface cannot be referenced by the constant pools
!      *     of other classes and interfaces.
!      * <li>A hidden class or interface cannot be discovered by any class loader.
!      * </ul>
!      * In addition, the returned array does not include array classes whose
!      * {@linkplain Class#componentType() element type} is a
!      * {@link Class#isHidden() hidden class or interface} as they cannot
!      * be discovered by {@code loader}.
       *
       * @param loader          the loader whose initiated class list will be returned
!      * @return an array containing all classes which {@code loader} can find by name;
       *          zero-length if there are none
       */
      @SuppressWarnings("rawtypes")
      Class[]
      getInitiatedClasses(ClassLoader loader);