From 6bfd018beaf187940ebafc71885045b4aabca673 Mon Sep 17 00:00:00 2001
From: Phil Race <prr@openjdk.org>
Date: Tue, 7 Oct 2025 19:08:22 +0000
Subject: [PATCH] 8366002: Beans.instantiate needs to describe the lookup
 procedure

Reviewed-by: serb, aivanov
---
 .../share/classes/java/beans/Beans.java       | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/java.desktop/share/classes/java/beans/Beans.java b/src/java.desktop/share/classes/java/beans/Beans.java
index 313bfe98515..a95aeb45cbb 100644
--- a/src/java.desktop/share/classes/java/beans/Beans.java
+++ b/src/java.desktop/share/classes/java/beans/Beans.java
@@ -64,6 +64,22 @@ public class 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 class 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