Merge branch '6.0.x'

spring-beans/src/main/java/org/springframework/beans/factory/support/GenericBeanDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2023 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,15 +21,17 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.ObjectUtils;
 
 /**
- * GenericBeanDefinition is a one-stop shop for standard bean definition purposes.
- * Like any bean definition, it allows for specifying a class plus optionally
+ * GenericBeanDefinition is a one-stop shop for declarative bean definition purposes.
+ * Like all common bean definitions, it allows for specifying a class plus optionally
  * constructor argument values and property values. Additionally, deriving from a
  * parent bean definition can be flexibly configured through the "parentName" property.
  *
  * <p>In general, use this {@code GenericBeanDefinition} class for the purpose of
- * registering user-visible bean definitions (which a post-processor might operate on,
- * potentially even reconfiguring the parent name). Use {@code RootBeanDefinition} /
- * {@code ChildBeanDefinition} where parent/child relationships happen to be pre-determined.
+ * registering declarative bean definitions (e.g. XML definitions which a bean
+ * post-processor might operate on, potentially even reconfiguring the parent name).
+ * Use {@code RootBeanDefinition}/{@code ChildBeanDefinition} where parent/child
+ * relationships happen to be pre-determined, and prefer {@link RootBeanDefinition}
+ * specifically for programmatic definitions derived from factory methods/suppliers.
  *
  * @author Juergen Hoeller
  * @since 2.5

spring-beans/src/main/java/org/springframework/beans/factory/support/RootBeanDefinition.java

@@ -35,17 +35,23 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
- * A root bean definition represents the merged bean definition that backs
- * a specific bean in a Spring BeanFactory at runtime. It might have been created
- * from multiple original bean definitions that inherit from each other,
- * typically registered as {@link GenericBeanDefinition GenericBeanDefinitions}.
+ * A root bean definition represents the <b>merged bean definition at runtime</b>
+ * that backs a specific bean in a Spring BeanFactory. It might have been created
+ * from multiple original bean definitions that inherit from each other, e.g.
+ * {@link GenericBeanDefinition GenericBeanDefinitions} from XML declarations.
  * A root bean definition is essentially the 'unified' bean definition view at runtime.
  *
- * <p>Root bean definitions may also be used for registering individual bean definitions
- * in the configuration phase. However, since Spring 2.5, the preferred way to register
- * bean definitions programmatically is the {@link GenericBeanDefinition} class.
- * GenericBeanDefinition has the advantage that it allows to dynamically define
- * parent dependencies, not 'hard-coding' the role as a root bean definition.
+ * <p>Root bean definitions may also be used for <b>registering individual bean
+ * definitions in the configuration phase.</b> This is particularly applicable for
+ * programmatic definitions derived from factory methods (e.g. {@code @Bean} methods)
+ * and instance suppliers (e.g. lambda expressions) which come with extra type metadata
+ * (see {@link #setTargetType(ResolvableType)}/{@link #setResolvedFactoryMethod(Method)}).
+ *
+ * <p>Note: The preferred choice for bean definitions derived from declarative sources
+ * (e.g. XML definitions) is the flexible {@link GenericBeanDefinition} variant.
+ * GenericBeanDefinition comes with the advantage that it allows for dynamically
+ * defining parent dependencies, not 'hard-coding' the role as a root bean definition,
+ * even supporting parent relationship changes in the bean post-processor phase.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller

spring-core/src/main/java/org/springframework/cglib/beans/package-info.java

@@ -2,9 +2,5 @@
  * Spring's repackaging of the
  * <a href="https://github.com/cglib/cglib">CGLIB</a> beans package
  * (for internal use only).
- *
- * <p>As this repackaging happens at the class file level, sources
- * and javadocs are not available here... except for a few files
- * that have been patched for Spring's purposes on JDK 9-17.
  */
 package org.springframework.cglib.beans;

spring-core/src/main/java/org/springframework/cglib/core/internal/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Spring's repackaging of the
+ * <a href="https://github.com/cglib/cglib">CGLIB</a> core internal package
+ * (for internal use only).
+ */
+package org.springframework.cglib.core.internal;

spring-core/src/main/java/org/springframework/cglib/core/package-info.java

@@ -2,9 +2,5 @@
  * Spring's repackaging of the
  * <a href="https://github.com/cglib/cglib">CGLIB</a> core package
  * (for internal use only).
- *
- * <p>As this repackaging happens at the class file level, sources
- * and javadocs are not available here... except for a few files
- * that have been patched for Spring's purposes on JDK 9-17.
  */
 package org.springframework.cglib.core;

spring-core/src/main/java/org/springframework/cglib/package-info.java

@@ -6,8 +6,5 @@
  * <p>This repackaging technique avoids any potential conflicts with
  * dependencies on CGLIB at the application level or from third-party
  * libraries and frameworks.
- *
- * <p>As this repackaging happens at the class file level, sources
- * and javadocs are not available here.
  */
 package org.springframework.cglib;

spring-core/src/main/java/org/springframework/cglib/proxy/package-info.java

@@ -2,9 +2,5 @@
  * Spring's repackaging of the
  * <a href="https://github.com/cglib/cglib">CGLIB</a> proxy package
  * (for internal use only).
- *
- * <p>As this repackaging happens at the class file level, sources
- * and javadocs are not available here... except for a few files
- * that have been patched for Spring's purposes on JDK 9-17.
  */
 package org.springframework.cglib.proxy;

spring-core/src/main/java/org/springframework/cglib/reflect/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Spring's repackaging of the
+ * <a href="https://github.com/cglib/cglib">CGLIB</a> reflect package
+ * (for internal use only).
+ */
+package org.springframework.cglib.reflect;

spring-core/src/main/java/org/springframework/cglib/transform/impl/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Spring's repackaging of the
+ * <a href="https://github.com/cglib/cglib">CGLIB</a> transform impl package
+ * (for internal use only).
+ */
+package org.springframework.cglib.transform.impl;

spring-core/src/main/java/org/springframework/cglib/transform/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Spring's repackaging of the
+ * <a href="https://github.com/cglib/cglib">CGLIB</a> transform package
+ * (for internal use only).
+ */
+package org.springframework.cglib.transform;

spring-core/src/main/java/org/springframework/cglib/util/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Spring's repackaging of the
+ * <a href="https://github.com/cglib/cglib">CGLIB</a> util package
+ * (for internal use only).
+ */
+package org.springframework.cglib.util;