Appendix refactoring

1. Move schemas to local appendix within each top-level section.
2. Link to Javadoc for JSP tags
3. Purge Class Spring usage information

Issue: SPR-16045

src/docs/asciidoc/core.adoc

@@ -34,3 +34,4 @@ include::core/core-aop-api.adoc[leveloffset=+1]
 
 include::core/core-null-safety.adoc[leveloffset=+1]
 
+include::core/core-appendix.adoc[leveloffset=+1]

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

@@ -259,9 +259,10 @@ element:
 	<aop:aspectj-autoproxy/>
 ----
 
-This assumes that you are using schema support as described in <<appendix.adoc#xsd-configuration,
-XML Schema-based configuration>>. See <<appendix.adoc#xsd-config-body-schemas-aop, the AOP schema>>
-for how to import the tags in the `aop` namespace.
+This assumes that you are using schema support as described in
+<<core.adoc#xsd-schemas, XML Schema-based configuration>>. See
+<<core.adoc#xsd-schemas-aop, the AOP schema>> for how to import the tags in the `aop`
+namespace.
 
 
 
@@ -1553,9 +1554,9 @@ the new __syntax__ and refer the reader to the discussion in the previous sectio
 of advice parameters.
 
 To use the aop namespace tags described in this section, you need to import the
-`spring-aop` schema as described in <<appendix.adoc#xsd-configuration,
+`spring-aop` schema as described in <<core.adoc#xsd-schemas,
 XML Schema-based configuration>>.
-See <<appendix.adoc#xsd-config-body-schemas-aop, the AOP schema>>
+See <<core.adoc#xsd-schemas-aop, the AOP schema>>
 for how to import the tags in the `aop` namespace.
 
 Within your Spring configurations, all aspect and advisor elements must be placed within
@@ -2793,8 +2794,9 @@ using Java based configuration simply add `@EnableSpringConfigured` to any
 	}
 ----
 
-If you prefer XML based configuration, the Spring <<appendix.adoc#xsd-config-body-schemas-context,
-`context` namespace>> defines a convenient `context:spring-configured` element:
+If you prefer XML based configuration, the Spring
+<<core.adoc#xsd-schemas-context, `context` namespace>>
+defines a convenient `context:spring-configured` element:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]

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

@@ -1711,7 +1711,8 @@ The above configuration is equivalent to the following Java code:
 The p-namespace enables you to use the `bean` element's attributes, instead of nested
 `<property/>` elements, to describe your property values and/or collaborating beans.
 
-Spring supports extensible configuration formats <<appendix.adoc#xsd-configuration,with namespaces>>,
+Spring supports extensible configuration formats
+<<core.adoc#xsd-schemas,with namespaces>>,
 which are based on an XML Schema definition. The `beans` configuration format discussed in this
 chapter is defined in an XML Schema document. However, the p-namespace is not defined in
 an XSD file and exists only in the core of Spring.
@@ -2771,7 +2772,7 @@ understand the "why" as well as the "how" behind it.
 
 To create such a proxy, you insert a child `<aop:scoped-proxy/>` element into a scoped
 bean definition (see <<beans-factory-scopes-other-injection-proxies>> and
-<<appendix.adoc#xsd-configuration, XML Schema-based configuration>>).
+<<core.adoc#xsd-schemas, XML Schema-based configuration>>).
 Why do definitions of beans scoped at the `request`, `session` and custom-scope
 levels require the `<aop:scoped-proxy/>` element?
 Let's examine the following singleton bean definition and contrast it with
@@ -5293,7 +5294,9 @@ Or with an overridden value for the `proxyMode` as follows:
 	}
 ----
 
-For further details, consult the <<appendix.adoc#annotation-programming-model,Spring Annotation Programming Model>>.
+For further details, consult the
+https://github.com/spring-projects/spring-framework/wiki/Spring-Annotation-Programming-Model[Spring Annotation Programming Model]
+wiki page.
 
 
 [[beans-scanning-autodetection]]

src/docs/asciidoc/data-access-appendix.adoc

@@ -0,0 +1,80 @@
+= Appendix
+
+[[xsd-schemas]]
+== XML Schemas
+
+This part of the appendix lists XML schemas for data access.
+
+
+[[xsd-schemas-tx]]
+=== The `tx` schema
+
+The `tx` tags deal with configuring all of those beans in Spring's comprehensive support
+for transactions. These tags are covered in the chapter entitled
+<<data-access.adoc#transaction,Transaction Management>>.
+
+[TIP]
+====
+
+You are strongly encouraged to look at the `'spring-tx.xsd'` file that ships with the
+Spring distribution. This file is (of course), the XML Schema for Spring's transaction
+configuration, and covers all of the various tags in the `tx` namespace, including
+attribute defaults and suchlike. This file is documented inline, and thus the
+information is not repeated here in the interests of adhering to the DRY (Don't Repeat
+Yourself) principle.
+====
+
+In the interest of completeness, to use the tags in the `tx` schema, you need to have
+the following preamble at the top of your Spring XML configuration file; the text in the
+following snippet references the correct schema so that the tags in the `tx` namespace
+are available to you.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<?xml version="1.0" encoding="UTF-8"?>
+	<beans xmlns="http://www.springframework.org/schema/beans"
+			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+			xmlns:aop="http://www.springframework.org/schema/aop"
+			__xmlns:tx="http://www.springframework.org/schema/tx"__ xsi:schemaLocation="
+			http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+			__http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd__
+			http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd"> <!-- bean definitions here -->
+
+	</beans>
+----
+
+[NOTE]
+====
+Often when using the tags in the `tx` namespace you will also be using the tags from the
+`aop` namespace (since the declarative transaction support in Spring is implemented
+using AOP). The above XML snippet contains the relevant lines needed to reference the
+`aop` schema so that the tags in the `aop` namespace are available to you.
+====
+
+
+
+[[xsd-schemas-jdbc]]
+=== The `jdbc` schema
+
+The `jdbc` tags allow you to quickly configure an embedded database or initialize an
+existing data source. These tags are documented in
+<<data-access.adoc#jdbc-embedded-database-support,Embedded database support>>
+and <<data-access.adoc#jdbc-initializing-datasource,Initializing a DataSource>> respectively.
+
+To use the tags in the `jdbc` schema, you need to have the following preamble at the top
+of your Spring XML configuration file; the text in the following snippet references the
+correct schema so that the tags in the `jdbc` namespace are available to you.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<?xml version="1.0" encoding="UTF-8"?>
+	<beans xmlns="http://www.springframework.org/schema/beans"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		__xmlns:jdbc="http://www.springframework.org/schema/jdbc"__ xsi:schemaLocation="
+			http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+			__http://www.springframework.org/schema/jdbc http://www.springframework.org/schema/jdbc/spring-jdbc.xsd"__> <!-- bean definitions here -->
+
+	</beans>
+----

src/docs/asciidoc/data-access.adoc

@@ -302,11 +302,8 @@ infrastructure.
 [NOTE]
 ====
 The above definition of the `dataSource` bean uses the `<jndi-lookup/>` tag from the
-`jee` namespace. For more information on schema-based configuration, see
-<<appendix.adoc#xsd-configuration, XML Schema-based configuration>>,
-and for more information on the `<jee/>`
-tags see the section entitled <<appendix.adoc#xsd-config-body-schemas-jee,
-the JEE schema>>.
+`jee` namespace. For more information see
+<<integration.adoc#xsd-schemas-jee, The JEE schema>>.
 ====
 
 You can also use Hibernate local transactions easily, as shown in the following
@@ -4929,9 +4926,7 @@ You can configure all of the supported features for O/R (object relational) mapp
 tools through Dependency Injection. They can participate in Spring's resource and
 transaction management, and they comply with Spring's generic transaction and DAO
 exception hierarchies. The recommended integration style is to code DAOs against plain
-Hibernate or JPA APIs. The older style of using Spring's DAO templates is no longer
-recommended; however, coverage of this style can be found in the
-<<appendix.adoc#classic-spring-orm, Classic ORM usage>> in the appendices.
+Hibernate or JPA APIs.
 
 Spring adds significant enhancements to the ORM layer of your choice when you create
 data access applications. You can leverage as much of the integration support as you
@@ -6680,3 +6675,6 @@ vulnerabilities do not get invoked.
 NOTE: Note that XStream is an XML serialization library, not a data binding library.
 Therefore, it has limited namespace support. As such, it is rather unsuitable for usage
 within Web services.
+
+
+include::data-access-appendix.adoc[leveloffset=+1]

src/docs/asciidoc/index.adoc

@@ -26,4 +26,3 @@ WebClient, WebSocket support.
 <<integration.adoc#spring-integration,Integration>> :: Remoting, JMS, JCA, JMX, Email,
 Tasks, Scheduling, Cache, Dynamic languages.
 <<kotlin.adoc#kotlin,Kotlin>> :: Extensions, Bean Definition DSL, WebFlux DSL
-<<appendix.adoc#spring-appendices,Appendix>> :: XML Schemas, JSP Tag Libraries

src/docs/asciidoc/integration-appendix.adoc

@@ -0,0 +1,346 @@
+= Appendix
+
+[[xsd-schemas]]
+== XML Schemas
+
+This part of the appendix lists XML schemas related to integration technologies.
+
+
+[[xsd-schemas-jee]]
+=== The jee schema
+
+The `jee` tags deal with Java EE (Java Enterprise Edition)-related configuration issues,
+such as looking up a JNDI object and defining EJB references.
+
+To use the tags in the `jee` schema, you need to have the following preamble at the top
+of your Spring XML configuration file; the text in the following snippet references the
+correct schema so that the tags in the `jee` namespace are available to you.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<?xml version="1.0" encoding="UTF-8"?>
+	<beans xmlns="http://www.springframework.org/schema/beans"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		__xmlns:jee="http://www.springframework.org/schema/jee"__ xsi:schemaLocation="
+			http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+			__http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee.xsd"__> <!-- bean definitions here -->
+
+	</beans>
+----
+
+
+[[xsd-schemas-jee-jndi-lookup]]
+==== <jee:jndi-lookup/> (simple)
+
+Before...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="**dataSource**" class="org.springframework.jndi.JndiObjectFactoryBean">
+		<property name="jndiName" value="jdbc/MyDataSource"/>
+	</bean>
+	<bean id="userDao" class="com.foo.JdbcUserDao">
+		<!-- Spring will do the cast automatically (as usual) -->
+		<property name="dataSource" ref="**dataSource**"/>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:jndi-lookup id="**dataSource**" jndi-name="jdbc/MyDataSource"/>
+
+	<bean id="userDao" class="com.foo.JdbcUserDao">
+		<!-- Spring will do the cast automatically (as usual) -->
+		<property name="dataSource" ref="**dataSource**"/>
+	</bean>
+----
+
+
+[[xsd-schemas-jee-jndi-lookup-environment-single]]
+==== <jee:jndi-lookup/> (with single JNDI environment setting)
+
+Before...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
+		<property name="jndiName" value="jdbc/MyDataSource"/>
+		<property name="jndiEnvironment">
+			<props>
+				<prop key="foo">bar</prop>
+			</props>
+		</property>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:jndi-lookup id="simple" jndi-name="jdbc/MyDataSource">
+		<jee:environment>foo=bar</jee:environment>
+	</jee:jndi-lookup>
+----
+
+
+[[xsd-schemas-jee-jndi-lookup-evironment-multiple]]
+==== <jee:jndi-lookup/> (with multiple JNDI environment settings)
+
+Before...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
+		<property name="jndiName" value="jdbc/MyDataSource"/>
+		<property name="jndiEnvironment">
+			<props>
+				<prop key="foo">bar</prop>
+				<prop key="ping">pong</prop>
+			</props>
+		</property>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:jndi-lookup id="simple" jndi-name="jdbc/MyDataSource">
+		<!-- newline-separated, key-value pairs for the environment (standard Properties format) -->
+		<jee:environment>
+			foo=bar
+			ping=pong
+		</jee:environment>
+	</jee:jndi-lookup>
+----
+
+
+[[xsd-schemas-jee-jndi-lookup-complex]]
+==== <jee:jndi-lookup/> (complex)
+
+Before...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="simple" class="org.springframework.jndi.JndiObjectFactoryBean">
+		<property name="jndiName" value="jdbc/MyDataSource"/>
+		<property name="cache" value="true"/>
+		<property name="resourceRef" value="true"/>
+		<property name="lookupOnStartup" value="false"/>
+		<property name="expectedType" value="com.myapp.DefaultFoo"/>
+		<property name="proxyInterface" value="com.myapp.Foo"/>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:jndi-lookup id="simple"
+			jndi-name="jdbc/MyDataSource"
+			cache="true"
+			resource-ref="true"
+			lookup-on-startup="false"
+			expected-type="com.myapp.DefaultFoo"
+			proxy-interface="com.myapp.Foo"/>
+----
+
+
+[[xsd-schemas-jee-local-slsb]]
+==== <jee:local-slsb/> (simple)
+
+The `<jee:local-slsb/>` tag configures a reference to an EJB Stateless SessionBean.
+
+Before...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="simple"
+			class="org.springframework.ejb.access.LocalStatelessSessionProxyFactoryBean">
+		<property name="jndiName" value="ejb/RentalServiceBean"/>
+		<property name="businessInterface" value="com.foo.service.RentalService"/>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:local-slsb id="simpleSlsb" jndi-name="ejb/RentalServiceBean"
+			business-interface="com.foo.service.RentalService"/>
+----
+
+
+[[xsd-schemas-jee-local-slsb-complex]]
+==== <jee:local-slsb/> (complex)
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="complexLocalEjb"
+			class="org.springframework.ejb.access.LocalStatelessSessionProxyFactoryBean">
+		<property name="jndiName" value="ejb/RentalServiceBean"/>
+		<property name="businessInterface" value="com.foo.service.RentalService"/>
+		<property name="cacheHome" value="true"/>
+		<property name="lookupHomeOnStartup" value="true"/>
+		<property name="resourceRef" value="true"/>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:local-slsb id="complexLocalEjb"
+			jndi-name="ejb/RentalServiceBean"
+			business-interface="com.foo.service.RentalService"
+			cache-home="true"
+			lookup-home-on-startup="true"
+			resource-ref="true">
+----
+
+
+[[xsd-schemas-jee-remote-slsb]]
+==== <jee:remote-slsb/>
+
+The `<jee:remote-slsb/>` tag configures a reference to a `remote` EJB Stateless
+SessionBean.
+
+Before...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="complexRemoteEjb"
+			class="org.springframework.ejb.access.SimpleRemoteStatelessSessionProxyFactoryBean">
+		<property name="jndiName" value="ejb/MyRemoteBean"/>
+		<property name="businessInterface" value="com.foo.service.RentalService"/>
+		<property name="cacheHome" value="true"/>
+		<property name="lookupHomeOnStartup" value="true"/>
+		<property name="resourceRef" value="true"/>
+		<property name="homeInterface" value="com.foo.service.RentalService"/>
+		<property name="refreshHomeOnConnectFailure" value="true"/>
+	</bean>
+----
+
+After...
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<jee:remote-slsb id="complexRemoteEjb"
+			jndi-name="ejb/MyRemoteBean"
+			business-interface="com.foo.service.RentalService"
+			cache-home="true"
+			lookup-home-on-startup="true"
+			resource-ref="true"
+			home-interface="com.foo.service.RentalService"
+			refresh-home-on-connect-failure="true">
+----
+
+
+
+[[xsd-schemas-lang]]
+=== The lang schema
+
+The `lang` tags deal with exposing objects that have been written in a dynamic language
+such as JRuby or Groovy as beans in the Spring container.
+
+These tags (and the dynamic language support) are comprehensively covered in the chapter
+entitled <<integration.adoc#dynamic-language,Dynamic language support>>.
+Please do consult that chapter for full details on this support and the `lang` tags themselves.
+
+In the interest of completeness, to use the tags in the `lang` schema, you need to have
+the following preamble at the top of your Spring XML configuration file; the text in the
+following snippet references the correct schema so that the tags in the `lang` namespace
+are available to you.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<?xml version="1.0" encoding="UTF-8"?>
+	<beans xmlns="http://www.springframework.org/schema/beans"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		__xmlns:lang="http://www.springframework.org/schema/lang"__ xsi:schemaLocation="
+			http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+			__http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang.xsd"__> <!-- bean definitions here -->
+
+	</beans>
+----
+
+
+
+[[xsd-schemas-jms]]
+=== The jms schema
+
+The `jms` tags deal with configuring JMS-related beans such as Spring's
+<<integration.adoc#jms-mdp,MessageListenerContainers>>. These tags are detailed in the
+section of the <<integration.adoc#jms,JMS chapter>> entitled <<integration.adoc#jms-namespace,
+JMS namespace support>>. Please do consult that chapter for full details on this support
+and the `jms` tags themselves.
+
+In the interest of completeness, to use the tags in the `jms` schema, you need to have
+the following preamble at the top of your Spring XML configuration file; the text in the
+following snippet references the correct schema so that the tags in the `jms` namespace
+are available to you.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<?xml version="1.0" encoding="UTF-8"?>
+	<beans xmlns="http://www.springframework.org/schema/beans"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		__xmlns:jms="http://www.springframework.org/schema/jms"__ xsi:schemaLocation="
+			http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+			__http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms.xsd"__> <!-- bean definitions here -->
+
+	</beans>
+----
+
+
+[[xsd-schemas-context-mbe]]
+=== <context:mbean-export/>
+
+This element is detailed in
+<<integration.adoc#jmx-context-mbeanexport, Configuring annotation based MBean export>>.
+
+
+
+[[xsd-schemas-cache]]
+=== The cache schema
+
+The `cache` tags can be used to enable support for Spring's `@CacheEvict`, `@CachePut`
+and `@Caching` annotations. It it also supports declarative XML-based caching. See
+<<integration.adoc#cache-annotation-enable,Enable caching annotations>> and
+<<integration.adoc#cache-declarative-xml,Declarative XML-based caching>> for details.
+
+To use the tags in the `cache` schema, you need to have the following preamble at the
+top of your Spring XML configuration file; the text in the following snippet references
+the correct schema so that the tags in the `cache` namespace are available to you.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<?xml version="1.0" encoding="UTF-8"?>
+	<beans xmlns="http://www.springframework.org/schema/beans"
+		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		__xmlns:cache="http://www.springframework.org/schema/cache"__ xsi:schemaLocation="
+			http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+			__http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd"__> <!-- bean definitions here -->
+
+	</beans>
+----

src/docs/asciidoc/integration.adoc

@@ -9033,3 +9033,6 @@ policies and different topologies which other solutions do not (take for example
 `ConcurrentHashMap`) - exposing that in the cache abstraction would be useless simply
 because there would no backing support. Such functionality should be controlled directly
 through the backing cache, when configuring it or through its native API.
+
+
+include::integration-appendix.adoc[leveloffset=+1]

src/docs/asciidoc/web/webmvc-view.adoc

@@ -574,10 +574,10 @@ earlier chapters. To facilitate the development of JSP pages in combination with
 data binding features, Spring provides a few tags that make things even easier. All
 Spring tags have__HTML escaping__ features to enable or disable escaping of characters.
 
-The tag library descriptor (TLD) is included in the `spring-webmvc.jar`. Further
-information about the individual tags can be found in the appendix entitled
-<<spring.tld>>.
-
+The tag library descriptor (TLD) is included in the `spring-webmvc.jar`. For information
+on individual tags, see the API reference for the
+{api-spring-framework}/web/servlet/tags/package-summary.html[spring tags] and the .
+{api-spring-framework}/web/servlet/tags/form/package-summary.html[spring-form tags]
 
 
 [[mvc-view-jsp-formtaglib]]