From c787ab4180d63fe96f6e8bf4d283cef08d17d058 Mon Sep 17 00:00:00 2001
From: Yanming Zhou <zhouyanming@gmail.com>
Date: Wed, 19 Feb 2025 10:14:13 +0800
Subject: [PATCH] Improve Javadoc of ObjectProvider to clarify what is unique

Signed-off-by: Yanming Zhou <zhouyanming@gmail.com>
---
 .../beans/factory/ObjectProvider.java          | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/ObjectProvider.java b/spring-beans/src/main/java/org/springframework/beans/factory/ObjectProvider.java
index 2768d066c3bc..e1087cc8d411 100644
--- a/spring-beans/src/main/java/org/springframework/beans/factory/ObjectProvider.java
+++ b/spring-beans/src/main/java/org/springframework/beans/factory/ObjectProvider.java
@@ -149,8 +149,14 @@ default void ifAvailable(Consumer<T> dependencyConsumer) throws BeansException {
 	/**
 	 * Return an instance (possibly shared or independent) of the object
 	 * managed by this factory.
-	 * @return an instance of the bean, or {@code null} if not available or
-	 * not unique (i.e. multiple candidates found with none marked as primary)
+	 * <p>An instance is considered as unique when multiple candidates found
+	 * if it meet one of the following conditions:
+	 * <ul>
+	 * <li>It's the only one marked as primary</li>
+	 * <li>It's the only one not marked as fallback</li>
+	 * <li>It's the only one default candidate</li>
+	 * </ul>
+	 * @return an instance of the bean, or {@code null} if not available or not unique
 	 * @throws BeansException in case of creation errors
 	 * @see #getObject()
 	 */
@@ -167,10 +173,10 @@ default void ifAvailable(Consumer<T> dependencyConsumer) throws BeansException {
 	 * Return an instance (possibly shared or independent) of the object
 	 * managed by this factory.
 	 * @param defaultSupplier a callback for supplying a default object
-	 * if no unique candidate is present in the factory
+	 * if no unique (refer to {@link #getIfUnique()} for the definition)
+	 * candidate is present in the factory
 	 * @return an instance of the bean, or the supplied default object
 	 * if no such bean is available or if it is not unique in the factory
-	 * (i.e. multiple candidates found with none marked as primary)
 	 * @throws BeansException in case of creation errors
 	 * @since 5.0
 	 * @see #getIfUnique()
@@ -182,12 +188,12 @@ default T getIfUnique(Supplier<T> defaultSupplier) throws BeansException {
 
 	/**
 	 * Consume an instance (possibly shared or independent) of the object
-	 * managed by this factory, if unique.
+	 * managed by this factory, if unique (refer to {@link #getIfUnique()} for the definition).
 	 * @param dependencyConsumer a callback for processing the target object
 	 * if unique (not called otherwise)
 	 * @throws BeansException in case of creation errors
 	 * @since 5.0
-	 * @see #getIfAvailable()
+	 * @see #getIfUnique()
 	 */
 	default void ifUnique(Consumer<T> dependencyConsumer) throws BeansException {
 		T dependency = getIfUnique();