root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

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
This commit is contained in:
Rossen Stoyanchev 2017-10-05 07:23:18 -04:00
parent d04d4bfb4d
commit e5a5677fcd
11 changed files with 1831 additions and 3997 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3974
src/docs/asciidoc/appendix.adoc
View File

File diff suppressed because it is too large Load Diff

1
src/docs/asciidoc/core.adoc
View File

@ -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]

16
src/docs/asciidoc/core/core-aop.adoc
View File

@ -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"]

1376
src/docs/asciidoc/core/core-appendix.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

9
src/docs/asciidoc/core/core-beans.adoc
View File

@ -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]]

80
src/docs/asciidoc/data-access-appendix.adoc Normal file
View File

@ -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>
----

14
src/docs/asciidoc/data-access.adoc
View File

@ -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]

1
src/docs/asciidoc/index.adoc
View File

@ -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

346
src/docs/asciidoc/integration-appendix.adoc Normal file
View File

@ -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>
----

3
src/docs/asciidoc/integration.adoc
View File

@ -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]

8
src/docs/asciidoc/web/webmvc-view.adoc
View File

@ -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]]