From cff0eacfc45c4c682a71679bd7881c7bb2e10aaa Mon Sep 17 00:00:00 2001
From: prrace <philip.race@oracle.com>
Date: Fri, 22 Aug 2025 10:36:36 -0700
Subject: [PATCH] 8366002

---
 .../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 313bfe9851550..e8f55e125033f 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 Beans() {}
      * <p>
      * Instantiate a JavaBean.
      * </p>
+     * The bean is created based on a name relative to a class-loader.
+     * This name should be a dot-separated name such as "a.b.c".
+     * <p>
+     * The given name can indicate either a serialized object or a class.
+     * We first try to treat the beanName as a serialized object
+     * name then as a class name.
+     * <p>
+     * When using the beanName as a serialized object name we convert the
+     * given 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 beanName of "x.y", 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 dot-separated name such as "a.b.c".
+     * <p>
+     * The given name can indicate either a serialized object or a class.
+     * We first try to treat the beanName as a serialized object
+     * name then as a class name.
+     * <p>
+     * When using the beanName as a serialized object name we convert the
+     * given 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 beanName of "x.y", 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