Explicit documentation on defaulting for 'autowire' and 'lazy-init'

Issue: SPR-13038

spring-beans/src/main/java/org/springframework/beans/factory/xml/BeanDefinitionParserDelegate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -332,9 +332,8 @@ public class BeanDefinitionParserDelegate {
 	/**
 	 * Populate the given DocumentDefaultsDefinition instance with the default lazy-init,
 	 * autowire, dependency check settings, init-method, destroy-method and merge settings.
-	 * Support nested 'beans' element use cases by falling back to
+	 * Support nested 'beans' element use cases by falling back to <literal>parentDefaults</literal>
-	 * <literal>parentDefaults</literal> in case the defaults are not explicitly set
+	 * in case the defaults are not explicitly set locally.
-	 * locally.
 	 * @param defaults the defaults to populate
 	 * @param parentDefaults the parent BeanDefinitionParserDelegate (if any) defaults to fall back to
 	 * @param root the root element of the current bean definition document (or nested beans element)
@@ -342,25 +341,27 @@ public class BeanDefinitionParserDelegate {
 	protected void populateDefaults(DocumentDefaultsDefinition defaults, DocumentDefaultsDefinition parentDefaults, Element root) {
 		String lazyInit = root.getAttribute(DEFAULT_LAZY_INIT_ATTRIBUTE);
 		if (DEFAULT_VALUE.equals(lazyInit)) {
-			lazyInit = parentDefaults != null ? parentDefaults.getLazyInit() : FALSE_VALUE;
+			// Potentially inherited from outer <beans> sections, otherwise falling back to false.
+			lazyInit = (parentDefaults != null ? parentDefaults.getLazyInit() : FALSE_VALUE);
 		}
 		defaults.setLazyInit(lazyInit);
 
 		String merge = root.getAttribute(DEFAULT_MERGE_ATTRIBUTE);
 		if (DEFAULT_VALUE.equals(merge)) {
-			merge = parentDefaults != null ? parentDefaults.getMerge() : FALSE_VALUE;
+			// Potentially inherited from outer <beans> sections, otherwise falling back to false.
+			merge = (parentDefaults != null ? parentDefaults.getMerge() : FALSE_VALUE);
 		}
 		defaults.setMerge(merge);
 
 		String autowire = root.getAttribute(DEFAULT_AUTOWIRE_ATTRIBUTE);
 		if (DEFAULT_VALUE.equals(autowire)) {
-			autowire = parentDefaults != null ? parentDefaults.getAutowire() : AUTOWIRE_NO_VALUE;
+			// Potentially inherited from outer <beans> sections, otherwise falling back to 'no'.
+			autowire = (parentDefaults != null ? parentDefaults.getAutowire() : AUTOWIRE_NO_VALUE);
 		}
 		defaults.setAutowire(autowire);
 
-		// don't fall back to parentDefaults for dependency-check as it's no
+		// Don't fall back to parentDefaults for dependency-check as it's no longer supported in
-		// longer supported in <beans> as of 3.0. Therefore, no nested <beans>
+		// <beans> as of 3.0. Therefore, no nested <beans> would ever need to fall back to it.
-		// would ever need to fall back to it.
 		defaults.setDependencyCheck(root.getAttribute(DEFAULT_DEPENDENCY_CHECK_ATTRIBUTE));
 
 		if (root.hasAttribute(DEFAULT_AUTOWIRE_CANDIDATES_ATTRIBUTE)) {

spring-beans/src/main/resources/org/springframework/beans/factory/xml/spring-beans-4.2.xsd

@@ -113,16 +113,19 @@
 				<xsd:annotation>
 					<xsd:documentation><![CDATA[
 	The default 'lazy-init' value; see the documentation for the
-	'lazy-init' attribute of the 'bean' element.
+	'lazy-init' attribute of the 'bean' element. The default is "default",
+	indicating inheritance from outer 'beans' sections in case of nesting,
+	otherwise falling back to "false".
 					]]></xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>
 			<xsd:attribute name="default-merge" default="default" type="defaultable-boolean">
 				<xsd:annotation>
 					<xsd:documentation><![CDATA[
-	The default 'merge' value; see the documentation for the
+	The default 'merge' value; see the documentation for the 'merge'
-	'merge' attribute of the various collection elements. The default
+	attribute of the various collection elements. The default is "default",
-	is 'false'.
+	indicating inheritance from outer 'beans' sections in case of nesting,
+	otherwise falling back to "false".
 					]]></xsd:documentation>
 				</xsd:annotation>
 			</xsd:attribute>
@@ -130,7 +133,9 @@
 				<xsd:annotation>
 					<xsd:documentation><![CDATA[
 	The default 'autowire' value; see the documentation for the
-	'autowire' attribute of the 'bean' element. The default is 'default'.
+	'autowire' attribute of the 'bean' element. The default is "default",
+	indicating inheritance from outer 'beans' sections in case of nesting,
+	otherwise falling back to "no" (i.e. no externally driven autowiring).
 					]]></xsd:documentation>
 				</xsd:annotation>
 				<xsd:simpleType>
@@ -328,13 +333,15 @@
 		<xsd:attribute name="lazy-init" default="default" type="defaultable-boolean">
 			<xsd:annotation>
 				<xsd:documentation><![CDATA[
-	Indicates whether or not this bean is to be lazily initialized.
+	Indicates whether this bean is to be lazily initialized. If "false",
-	If false, it will be instantiated on startup by bean factories
+	it will be instantiated on startup by bean factories that perform eager
-	that perform eager initialization of singletons. The default is
+	initialization of singletons. The effective default is "false".
-	"false".
 
 	Note: This attribute will not be inherited by child bean definitions.
-	Hence, it needs to be specified per concrete bean definition.
+	Hence, it needs to be specified per concrete bean definition. It can be
+	shared through the 'default-lazy-init' attribute at the 'beans' level
+	and potentially inherited from outer 'beans' defaults in case of nested
+	'beans' sections (e.g. with different profiles).
 				]]></xsd:documentation>
 			</xsd:annotation>
 		</xsd:attribute>
@@ -344,7 +351,7 @@
 	Controls whether bean properties are "autowired".
 	This is an automagical process in which bean references don't need
 	to be coded explicitly in the XML bean definition file, but rather the
-	Spring container works out dependencies.
+	Spring container works out dependencies. The effective default is "no".
 
 	There are 4 modes:
 
@@ -379,7 +386,10 @@
 	elements, always override autowiring.
 
 	Note: This attribute will not be inherited by child bean definitions.
-	Hence, it needs to be specified per concrete bean definition.
+	Hence, it needs to be specified per concrete bean definition. It can be
+	shared through the 'default-autowire' attribute at the 'beans' level
+	and potentially inherited from outer 'beans' defaults in case of nested
+	'beans' sections (e.g. with different profiles).
 				]]></xsd:documentation>
 			</xsd:annotation>
 			<xsd:simpleType>

src/asciidoc/core-beans.adoc

@@ -1858,7 +1858,7 @@ advantages:
 When using XML-based configuration metadata footnote:[See
 pass:specialcharacters,macros[<<beans-factory-collaborators>>]], you specify autowire
 mode for a bean definition with the `autowire` attribute of the `<bean/>` element. The
-autowiring functionality has five modes. You specify autowiring __per__ bean and thus
+autowiring functionality has four modes. You specify autowiring __per__ bean and thus
 can choose which ones to autowire.
 
 [[beans-factory-autowiring-modes-tbl]]