Recommend ObjectProvider as alternative to @lazy for optional dependencies

Closes gh-27649

Author: jhoeller

spring-context/src/main/java/org/springframework/context/annotation/Lazy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2021 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.
@@ -47,6 +47,11 @@
  * or {@link javax.inject.Inject}: In that context, it leads to the creation of a
  * lazy-resolution proxy for all affected dependencies, as an alternative to using
  * {@link org.springframework.beans.factory.ObjectFactory} or {@link javax.inject.Provider}.
+ * Please note that such a lazy-resolution proxy will always be injected; if the target
+ * dependency does not exist, you will only be able to find out through an exception on
+ * invocation. As a consequence, such an injection point results in unintuitive behavior
+ * for optional dependencies. For a programmatic equivalent, allowing for lazy references
+ * with more sophistication, consider {@link org.springframework.beans.factory.ObjectProvider}.
  *
  * @author Chris Beams
  * @author Juergen Hoeller

src/docs/asciidoc/core/core-beans.adoc

@@ -3039,7 +3039,7 @@ constructor or setter argument or autowired field) as `ObjectFactory<MyTargetBea
 allowing for a `getObject()` call to retrieve the current instance on demand every
 time it is needed -- without holding on to the instance or storing it separately.
 
-As an extended variant, you may declare `ObjectProvider<MyTargetBean>`, which delivers
+As an extended variant, you may declare `ObjectProvider<MyTargetBean>` which delivers
 several additional access variants, including `getIfAvailable` and `getIfUnique`.
 
 The JSR-330 variant of this is called `Provider` and is used with a `Provider<MyTargetBean>`
@@ -6675,9 +6675,11 @@ factory method and other bean definition properties, such as a qualifier value t
 the `@Qualifier` annotation. Other method-level annotations that can be specified are
 `@Scope`, `@Lazy`, and custom qualifier annotations.
 
-TIP: In addition to its role for component initialization, you can also place the `@Lazy` annotation
-on injection points marked with `@Autowired` or `@Inject`. In this context, it
-leads to the injection of a lazy-resolution proxy.
+TIP: In addition to its role for component initialization, you can also place the `@Lazy`
+annotation on injection points marked with `@Autowired` or `@Inject`. In this context,
+it leads to the injection of a lazy-resolution proxy. However, such a proxy approach
+is rather limited. For sophisticated lazy interactions, in particular in combination
+with optional dependencies, we recommend `ObjectProvider<MyTargetBean>` instead.
 
 Autowired fields and methods are supported, as previously discussed, with additional
 support for autowiring of `@Bean` methods. The following example shows how to do so: