8366002: Beans.instantiate needs to describe the lookup procedure

Reviewed-by: serb, aivanov

Author: prrace

src/java.desktop/share/classes/java/beans/Beans.java

@@ -64,6 +64,22 @@ public Beans() {}
      * <p>
      * Instantiate a JavaBean.
      * </p>
+     * The bean is created based on a name relative to a class-loader.
+     * This name should be a {@linkplain ClassLoader##binary-name binary name} of a class such as "a.b.C".
+     * <p>
+     * The given name can indicate either a serialized object or a class.
+     * We first try to treat the {@code beanName} as a serialized object
+     * name then as a class name.
+     * <p>
+     * When using the {@code beanName} as a serialized object name we convert the
+     * given {@code beanName} to a resource pathname and add a trailing ".ser" suffix.
+     * We then try to load a serialized object from that resource.
+     * <p>
+     * For example, given a {@code beanName} of "x.y", {@code Beans.instantiate} would first
+     * try to read a serialized object from the resource "x/y.ser" and if
+     * that failed it would try to load the class "x.y" and create an
+     * instance of that class.
+     *
      * @return a JavaBean
      * @param     cls         the class-loader from which we should create
      *                        the bean.  If this is null, then the system
@@ -84,6 +100,22 @@ public static Object instantiate(ClassLoader cls, String beanName) throws IOExce
      * <p>
      * Instantiate a JavaBean.
      * </p>
+     * The bean is created based on a name relative to a class-loader.
+     * This name should be a {@linkplain ClassLoader##binary-name binary name} of a class such as "a.b.C".
+     * <p>
+     * The given name can indicate either a serialized object or a class.
+     * We first try to treat the {@code beanName} as a serialized object
+     * name then as a class name.
+     * <p>
+     * When using the {@code beanName} as a serialized object name we convert the
+     * given {@code beanName} to a resource pathname and add a trailing ".ser" suffix.
+     * We then try to load a serialized object from that resource.
+     * <p>
+     * For example, given a {@code beanName} of "x.y", {@code Beans.instantiate} would first
+     * try to read a serialized object from the resource "x/y.ser" and if
+     * that failed it would try to load the class "x.y" and create an
+     * instance of that class.
+     *
      * @return a JavaBean
      *
      * @param     cls         the class-loader from which we should create