diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/support/GenericBeanDefinition.java b/spring-beans/src/main/java/org/springframework/beans/factory/support/GenericBeanDefinition.java index b0a40b332a..01bb1726ed 100644 --- a/spring-beans/src/main/java/org/springframework/beans/factory/support/GenericBeanDefinition.java +++ b/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. * *

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 diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/support/RootBeanDefinition.java b/spring-beans/src/main/java/org/springframework/beans/factory/support/RootBeanDefinition.java index e149007c4b..99eb8f5020 100644 --- a/spring-beans/src/main/java/org/springframework/beans/factory/support/RootBeanDefinition.java +++ b/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 merged bean definition at runtime + * 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. * - *

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. + *

Root bean definitions may also be used for registering individual bean + * definitions in the configuration phase. 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)}). + * + *

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 diff --git a/spring-core/src/main/java/org/springframework/cglib/beans/package-info.java b/spring-core/src/main/java/org/springframework/cglib/beans/package-info.java index 10dd532ae0..a75c6124de 100644 --- a/spring-core/src/main/java/org/springframework/cglib/beans/package-info.java +++ b/spring-core/src/main/java/org/springframework/cglib/beans/package-info.java @@ -2,9 +2,5 @@ * Spring's repackaging of the * CGLIB beans package * (for internal use only). - * - *

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; diff --git a/spring-core/src/main/java/org/springframework/cglib/core/internal/package-info.java b/spring-core/src/main/java/org/springframework/cglib/core/internal/package-info.java new file mode 100644 index 0000000000..8c30df6192 --- /dev/null +++ b/spring-core/src/main/java/org/springframework/cglib/core/internal/package-info.java @@ -0,0 +1,6 @@ +/** + * Spring's repackaging of the + * CGLIB core internal package + * (for internal use only). + */ +package org.springframework.cglib.core.internal; diff --git a/spring-core/src/main/java/org/springframework/cglib/core/package-info.java b/spring-core/src/main/java/org/springframework/cglib/core/package-info.java index 15c9faabb7..d68373f270 100644 --- a/spring-core/src/main/java/org/springframework/cglib/core/package-info.java +++ b/spring-core/src/main/java/org/springframework/cglib/core/package-info.java @@ -2,9 +2,5 @@ * Spring's repackaging of the * CGLIB core package * (for internal use only). - * - *

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; diff --git a/spring-core/src/main/java/org/springframework/cglib/package-info.java b/spring-core/src/main/java/org/springframework/cglib/package-info.java index 638ce59770..b2462d4d76 100644 --- a/spring-core/src/main/java/org/springframework/cglib/package-info.java +++ b/spring-core/src/main/java/org/springframework/cglib/package-info.java @@ -6,8 +6,5 @@ *

This repackaging technique avoids any potential conflicts with * dependencies on CGLIB at the application level or from third-party * libraries and frameworks. - * - *

As this repackaging happens at the class file level, sources - * and javadocs are not available here. */ package org.springframework.cglib; diff --git a/spring-core/src/main/java/org/springframework/cglib/proxy/package-info.java b/spring-core/src/main/java/org/springframework/cglib/proxy/package-info.java index 345b4175a1..cb92f510fe 100644 --- a/spring-core/src/main/java/org/springframework/cglib/proxy/package-info.java +++ b/spring-core/src/main/java/org/springframework/cglib/proxy/package-info.java @@ -2,9 +2,5 @@ * Spring's repackaging of the * CGLIB proxy package * (for internal use only). - * - *

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; diff --git a/spring-core/src/main/java/org/springframework/cglib/reflect/package-info.java b/spring-core/src/main/java/org/springframework/cglib/reflect/package-info.java new file mode 100644 index 0000000000..cd1f3a8498 --- /dev/null +++ b/spring-core/src/main/java/org/springframework/cglib/reflect/package-info.java @@ -0,0 +1,6 @@ +/** + * Spring's repackaging of the + * CGLIB reflect package + * (for internal use only). + */ +package org.springframework.cglib.reflect; diff --git a/spring-core/src/main/java/org/springframework/cglib/transform/impl/package-info.java b/spring-core/src/main/java/org/springframework/cglib/transform/impl/package-info.java new file mode 100644 index 0000000000..df2014cfc8 --- /dev/null +++ b/spring-core/src/main/java/org/springframework/cglib/transform/impl/package-info.java @@ -0,0 +1,6 @@ +/** + * Spring's repackaging of the + * CGLIB transform impl package + * (for internal use only). + */ +package org.springframework.cglib.transform.impl; diff --git a/spring-core/src/main/java/org/springframework/cglib/transform/package-info.java b/spring-core/src/main/java/org/springframework/cglib/transform/package-info.java new file mode 100644 index 0000000000..2a6a57f031 --- /dev/null +++ b/spring-core/src/main/java/org/springframework/cglib/transform/package-info.java @@ -0,0 +1,6 @@ +/** + * Spring's repackaging of the + * CGLIB transform package + * (for internal use only). + */ +package org.springframework.cglib.transform; diff --git a/spring-core/src/main/java/org/springframework/cglib/util/package-info.java b/spring-core/src/main/java/org/springframework/cglib/util/package-info.java new file mode 100644 index 0000000000..17abeed069 --- /dev/null +++ b/spring-core/src/main/java/org/springframework/cglib/util/package-info.java @@ -0,0 +1,6 @@ +/** + * Spring's repackaging of the + * CGLIB util package + * (for internal use only). + */ +package org.springframework.cglib.util;