Modernize the lazy-initialized beans refdoc section

Closes gh-32767

Author: sdeleuze

Diff for: framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc

@@ -10,33 +10,25 @@ pre-instantiation of a singleton bean by marking the bean definition as being
 lazy-initialized. A lazy-initialized bean tells the IoC container to create a bean
 instance when it is first requested, rather than at startup.
 
-In XML, this behavior is controlled by the `lazy-init` attribute on the `<bean/>`
-element, as the following example shows:
+This behavior is controlled by the `@Lazy` annotation or in XML the `lazy-init` attribute on the `<bean/>` element, as
+the following example shows:
 
-[source,xml,indent=0,subs="verbatim,quotes"]
-----
-	<bean id="lazy" class="com.something.ExpensiveToCreateBean" lazy-init="true"/>
-	<bean name="not.lazy" class="com.something.AnotherBean"/>
-----
+include-code::./ApplicationConfiguration[tag=snippet,indent=0]
 
 When the preceding configuration is consumed by an `ApplicationContext`, the `lazy` bean
 is not eagerly pre-instantiated when the `ApplicationContext` starts,
-whereas the `not.lazy` bean is eagerly pre-instantiated.
+whereas the `notLazy` one is eagerly pre-instantiated.
 
 However, when a lazy-initialized bean is a dependency of a singleton bean that is
 not lazy-initialized, the `ApplicationContext` creates the lazy-initialized bean at
 startup, because it must satisfy the singleton's dependencies. The lazy-initialized bean
 is injected into a singleton bean elsewhere that is not lazy-initialized.
 
-You can also control lazy-initialization at the container level by using the
-`default-lazy-init` attribute on the `<beans/>` element, as the following example shows:
+You can also control lazy-initialization for a set of beans by using the `@Lazy` annotation on your `@Configuration`
+annotated class or in XML using the `default-lazy-init` attribute on the `<beans/>` element, as the following example
+shows:
 
-[source,xml,indent=0,subs="verbatim,quotes"]
-----
-	<beans default-lazy-init="true">
-		<!-- no beans will be pre-instantiated... -->
-	</beans>
-----
+include-code::./LazyConfiguration[tag=snippet,indent=0]
 
 
 

Diff for: framework-docs/src/main/java/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/AnotherBean.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.beans.dependencies.beansfactorylazyinit;
+
+public class AnotherBean {
+}

Diff for: framework-docs/src/main/java/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/ApplicationConfiguration.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.beans.dependencies.beansfactorylazyinit;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Lazy;
+
+@Configuration
+public class ApplicationConfiguration {
+
+	// tag::snippet[]
+	@Bean
+	@Lazy
+	ExpensiveToCreateBean lazy() {
+		return new ExpensiveToCreateBean();
+	}
+
+	@Bean
+	AnotherBean notLazy() {
+		return new AnotherBean();
+	}
+	// end::snippet[]
+}

Diff for: framework-docs/src/main/java/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/ExpensiveToCreateBean.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.beans.dependencies.beansfactorylazyinit;
+
+public class ExpensiveToCreateBean {
+}

Diff for: framework-docs/src/main/java/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/LazyConfiguration.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.beans.dependencies.beansfactorylazyinit;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Lazy;
+
+// tag::snippet[]
+@Configuration
+@Lazy
+public class LazyConfiguration {
+	// No bean will be pre-instantiated...
+}
+// end::snippet[]

Diff for: framework-docs/src/main/kotlin/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/ApplicationConfiguration.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.core.beans.dependencies.beansfactorylazyinit
+
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.context.annotation.Lazy
+
+@Configuration
+class ApplicationConfiguration {
+
+	// tag::snippet[]
+	@Bean
+	@Lazy
+	fun lazy(): ExpensiveToCreateBean {
+		return ExpensiveToCreateBean()
+	}
+
+	@Bean
+	fun notLazy(): AnotherBean {
+		return AnotherBean()
+	}
+	// end::snippet[]
+}

Diff for: framework-docs/src/main/kotlin/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/LazyConfiguration.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2002-2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.docs.core.beans.dependencies.beansfactorylazyinit
+
+import org.springframework.context.annotation.Configuration
+import org.springframework.context.annotation.Lazy
+
+// tag::snippet[]
+@Configuration
+@Lazy
+class LazyConfiguration {
+	// No bean will be pre-instantiated...
+}
+// end::snippet[]

Diff for: framework-docs/src/main/resources/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/ApplicationConfiguration.xml

@@ -0,0 +1,12 @@
+<beans xmlns="http://www.springframework.org/schema/beans"
+	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	   xsi:schemaLocation="http://www.springframework.org/schema/beans
+			https://www.springframework.org/schema/beans/spring-beans.xsd">
+
+	<!-- tag::snippet[] -->
+	<bean id="lazy" class="com.something.ExpensiveToCreateBean" lazy-init="true"/>
+
+	<bean name="notLazy" class="com.something.AnotherBean"/>
+	<!-- end::snippet[] -->
+
+</beans>

Diff for: framework-docs/src/main/resources/org/springframework/docs/core/beans/dependencies/beansfactorylazyinit/LazyConfiguration.xml

@@ -0,0 +1,6 @@
+<!-- tag::snippet[] -->
+<beans default-lazy-init="true">
+
+	<!-- No bean will be pre-instantiated... -->
+</beans>
+<!-- end::snippet[] -->