From fab3633c7504686f8ab89a4449e2cf910014388f Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <juergen.hoeller@broadcom.com>
Date: Tue, 30 Apr 2024 15:45:46 +0200
Subject: [PATCH] Add notes on constructor and factory method overloading

Closes gh-32091
---
 .../ROOT/pages/core/beans/definition.adoc     | 28 ++++++++++++++++---
 .../server-setup-options.adoc                 |  3 +-
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc
index 2141abd706..8de9ff4a17 100644
--- a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc
+++ b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc
@@ -234,6 +234,10 @@ For details about the mechanism for supplying arguments to the constructor (if r
 and setting object instance properties after the object is constructed, see
 xref:core/beans/dependencies/factory-collaborators.adoc[Injecting Dependencies].
 
+NOTE: In the case of constructor arguments, the container can select a corresponding
+constructor among several overloaded constructors. That said, to avoid ambiguities,
+it is recommended to keep your constructor signatures as straightforward as possible.
+
 
 [[beans-factory-class-static-factory-method]]
 === Instantiation with a Static Factory Method
@@ -294,6 +298,24 @@ For details about the mechanism for supplying (optional) arguments to the factor
 and setting object instance properties after the object is returned from the factory,
 see xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail].
 
+NOTE: In the case of factory method arguments, the container can select a corresponding
+method among several overloaded methods of the same name. That said, to avoid ambiguities,
+it is recommended to keep your factory method signatures as straightforward as possible.
+
+[TIP]
+====
+A typical problematic case with factory method overloading is Mockito with its many
+overloads of the `mock` method. Choose the most specific variant of `mock` possible:
+
+[source,xml,indent=0,subs="verbatim,quotes"]
+----
+	<bean id="clientService" class="org.mockito.Mockito" factory-method="mock">
+		<constructor-arg type="java.lang.Class" value="examples.ClientService"/>
+		<constructor-arg type="java.lang.String" value="clientService"/>
+	</bean>
+----
+====
+
 
 [[beans-factory-class-instance-factory-method]]
 === Instantiation by Using an Instance Factory Method
@@ -416,8 +438,8 @@ Kotlin::
 ======
 
 This approach shows that the factory bean itself can be managed and configured through
-dependency injection (DI). See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail]
-.
+dependency injection (DI).
+See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail].
 
 NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the
 Spring container and that creates objects through an
@@ -444,5 +466,3 @@ cases into account and returns the type of object that a `BeanFactory.getBean` c
 going to return for the same bean name.
 
 
-
-
diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc
index 9dd0498d4e..2abf6919d5 100644
--- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc
+++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc
@@ -111,7 +111,8 @@ a mock service with Mockito:
 [source,xml,indent=0,subs="verbatim,quotes"]
 ----
 	<bean id="accountService" class="org.mockito.Mockito" factory-method="mock">
-		<constructor-arg value="org.example.AccountService"/>
+		<constructor-arg type="java.lang.Class" value="org.example.AccountService"/>
+		<constructor-arg type="java.lang.String" value="accountService"/>
 	</bean>
 ----