Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish ref docs

Browse Source 
- stop referring to Java Config as new
- stop referring to Struts 2.x as if it were new
- polish AOT documentation
- etc.
This commit is contained in:
Sam Brannen
2022-11-19 16:17:28 +01:00
parent c45f8b7072
commit da12481ef1
7 changed files with 53 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
framework-docs/src/docs/asciidoc/core/core-aot.adoc
View File

@@ -5,7 +5,7 @@ This chapter covers Spring's Ahead of Time (AOT) optimizations.
For AOT support specific to integration tests, see <<testing.adoc#testcontext-aot, Ahead of Time Support for Tests>>.
[[aot-introduction]]
[[core.aot.introduction]]
== Introduction to Ahead of Time Optimizations
Spring's support for AOT optimizations is meant to inspect an `ApplicationContext` at build time and apply decisions and discovery logic that usually happens at runtime.
@@ -263,30 +263,29 @@ The following example registers `Account` for serialization.
[[core.aot.hints.testing]]
=== Testing Runtime Hints
Spring Core also ships `RuntimeHintsPredicates`, an utility for checking that existing hints match a particular use case.
This can be used in your own tests, for validating that a `RuntimeHintsRegistrar` has the expected result.
We can write a test for our `SpellCheckService` and ensure that we can load a dictionary at runtime:
Spring Core also ships `RuntimeHintsPredicates`, a utility for checking that existing hints match a particular use case.
This can be used in your own tests to validate that a `RuntimeHintsRegistrar` contains the expected results.
We can write a test for our `SpellCheckService` and ensure that we will be able to load a dictionary at runtime:
include::code:SpellCheckServiceTests[tag=hintspredicates]
With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization or proxy generation hints.
With `RuntimeHintsPredicates`, we can check for reflection, resource, serialization, or proxy generation hints.
This approach works well for unit tests but implies that the runtime behavior of a component is well known.
You can learn more about the global runtime behavior of an application by running its test suite (or the app itself) with the {docs-graalvm}/native-image/metadata/AutomaticMetadataCollection/[GraalVM tracing agent].
This agent will record all relevant calls requiring GraalVM hints at runtime and write them out as JSON configuration files.
For more targeted discovery and testing, Spring Framework ships a dedicated module with core AOT testing utilities, `"org.springframework:spring-core-test"`.
This module contains the RuntimeHints Agent, a Java agent that all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations.
Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT phase.
This module contains the RuntimeHints Agent, a Java agent that records all method invocations that are related to runtime hints and helps you to assert that a given `RuntimeHints` instance covers all recorded invocations.
Let's consider a piece of infrastructure for which we'd like to test the hints we're contributing during the AOT processing phase.
include::code:SampleReflection[]
We can then write a Java test (no native compilation required!) that checks our contributed hints:
We can then write a unit test (no native compilation required) that checks our contributed hints:
include::code:SampleReflectionRuntimeHintsTests[]
If you forgot to contribute a hint, the test will fail and give some details on the invocation:
If you forgot to contribute a hint, the test will fail and provide some details about the invocation:
[source,txt,indent=0,subs="verbatim,quotes"]
----
@@ -303,6 +302,6 @@ io.spring.runtimehintstesting.SampleReflection#performReflection, Line 19
io.spring.runtimehintstesting.SampleReflectionRuntimeHintsTests#lambda$shouldRegisterReflectionHints$0, Line 25
----
There are various ways to configure this Java agent into your build, please refer to your build tool and test execution plugin documentation.
The agent itself can be configured to instrument some packages (by default, only `org.springframework` is instrumented).
You'll find more details in the https://github.com/spring-projects/spring-framework/blob/main/buildSrc/README.md[Spring Framework buildSrc README].
There are various ways to configure this Java agent in your build, so please refer to the documentation of your build tool and test execution plugin.
The agent itself can be configured to instrument specific packages (by default, only `org.springframework` is instrumented).
You'll find more details in the {spring-framework-main-code}/buildSrc/README.md[Spring Framework `buildSrc` README] file.

35
framework-docs/src/docs/asciidoc/core/core-beans.adoc
View File

@@ -107,12 +107,10 @@ configuration metadata is actually written. These days, many developers choose
For information about using other forms of metadata with the Spring container, see:
* <<beans-annotation-config,Annotation-based configuration>>: Spring 2.5 introduced
support for annotation-based configuration metadata.
* <<beans-java, Java-based configuration>>: Starting with Spring 3.0, many features
provided by the Spring JavaConfig project became part of the core Spring Framework.
Thus, you can define beans external to your application classes by using Java rather
than XML files. To use these new features, see the
* <<beans-annotation-config,Annotation-based configuration>>: define beans using
annotation-based configuration metadata.
* <<beans-java, Java-based configuration>>: define beans external to your application
classes by using Java rather than XML files. To use these features, see the
{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`],
{api-spring-framework}/context/annotation/Bean.html[`@Bean`],
{api-spring-framework}/context/annotation/Import.html[`@Import`],
@@ -124,14 +122,12 @@ beans as `<bean/>` elements inside a top-level `<beans/>` element. Java
configuration typically uses `@Bean`-annotated methods within a `@Configuration` class.
These bean definitions correspond to the actual objects that make up your application.
Typically, you define service layer objects, data access objects (DAOs), presentation
objects such as Struts `Action` instances, infrastructure objects such as Hibernate
`SessionFactories`, JMS `Queues`, and so forth. Typically, one does not configure
fine-grained domain objects in the container, because it is usually the responsibility
of DAOs and business logic to create and load domain objects. However, you can use
Spring's integration with AspectJ to configure objects that have been created outside
the control of an IoC container. See <<aop-atconfigurable,Using AspectJ to
dependency-inject domain objects with Spring>>.
Typically, you define service layer objects, persistence layer objects such as
repositories or data access objects (DAOs), presentation objects such as Web controllers,
infrastructure objects such as a JPA `EntityManagerFactory`, JMS queues, and so forth.
Typically, one does not configure fine-grained domain objects in the container, because
it is usually the responsibility of repositories and business logic to create and load
domain objects.
The following example shows the basic structure of XML-based configuration metadata:
@@ -157,12 +153,11 @@ The following example shows the basic structure of XML-based configuration metad
----
<1> The `id` attribute is a string that identifies the individual bean definition.
<2> The `class` attribute defines the type of the bean and uses the fully qualified
classname.
class name.
The value of the `id` attribute refers to collaborating objects. The XML for
referring to collaborating objects is not shown in this example. See
The value of the `id` attribute can be used to refer to collaborating objects. The XML
for referring to collaborating objects is not shown in this example. See
<<beans-dependencies,Dependencies>> for more information.
@@ -2839,7 +2834,7 @@ processed by the Spring `DispatcherServlet`, no special setup is necessary.
`DispatcherServlet` already exposes all relevant state.
If you use a Servlet web container, with requests processed outside of Spring's
`DispatcherServlet` (for example, when using JSF or Struts), you need to register the
`DispatcherServlet` (for example, when using JSF), you need to register the
`org.springframework.web.context.request.RequestContextListener` `ServletRequestListener`.
This can be done programmatically by using the `WebApplicationInitializer` interface.
Alternatively, add the following declaration to your web application's `web.xml` file:
@@ -7515,7 +7510,7 @@ container. It includes the following topics:
[[beans-java-basic-concepts]]
=== Basic Concepts: `@Bean` and `@Configuration`
The central artifacts in Spring's new Java-configuration support are
The central artifacts in Spring's Java configuration support are
`@Configuration`-annotated classes and `@Bean`-annotated methods.
The `@Bean` annotation is used to indicate that a method instantiates, configures, and

39
framework-docs/src/docs/asciidoc/web/integration.adoc
View File

@@ -23,21 +23,21 @@ first take a look at common Spring configuration that is not specific to any one
framework. (This section is equally applicable to Spring's own web framework variants.)
One of the concepts (for want of a better word) espoused by Spring's lightweight
application model is that of a layered architecture. Remember that in a "`classic`"
application model is that of a layered architecture. Remember that in a "classic"
layered architecture, the web layer is but one of many layers. It serves as one of the
entry points into a server-side application, and it delegates to service objects
(facades) that are defined in a service layer to satisfy business-specific (and
presentation-technology agnostic) use cases. In Spring, these service objects, any other
business-specific objects, data-access objects, and others exist in a distinct "`business
context`", which contains no web or presentation layer objects (presentation objects,
such as Spring MVC controllers, are typically configured in a distinct "`presentation
context`"). This section details how you can configure a Spring container (a
business-specific objects, data-access objects, and others exist in a distinct "business
context", which contains no web or presentation layer objects (presentation objects,
such as Spring MVC controllers, are typically configured in a distinct "presentation
context"). This section details how you can configure a Spring container (a
`WebApplicationContext`) that contains all of the 'business beans' in your application.
Moving on to specifics, all you need to do is declare a
{api-spring-framework}/web/context/ContextLoaderListener.html[`ContextLoaderListener`]
in the standard Jakarta EE servlet `web.xml` file of your web application and add a
`contextConfigLocation`<context-param/> section (in the same file) that defines which
`contextConfigLocation` `<context-param/>` section (in the same file) that defines which
set of Spring XML configuration files to load.
Consider the following `<listener/>` configuration:
@@ -67,7 +67,7 @@ object based on the bean definitions and stores it in the `ServletContext` of th
application.
All Java web frameworks are built on top of the Servlet API, so you can use the
following code snippet to get access to this "`business context`" `ApplicationContext`
following code snippet to get access to this "business context" `ApplicationContext`
created by the `ContextLoaderListener`.
The following example shows how to get the `WebApplicationContext`:
@@ -119,7 +119,7 @@ The key element in Spring's JSF integration is the JSF `ELResolver` mechanism.
`SpringBeanFacesELResolver` is a JSF compliant `ELResolver` implementation,
integrating with the standard Unified EL as used by JSF and JSP. It delegates to
Spring's "`business context`" `WebApplicationContext` first and then to the
Spring's "business context" `WebApplicationContext` first and then to the
default resolver of the underlying JSF implementation.
Configuration-wise, you can define `SpringBeanFacesELResolver` in your JSF
@@ -157,27 +157,26 @@ The following example shows how to use `FacesContextUtils`:
[[struts]]
== Apache Struts 2.x
== Apache Struts
Invented by Craig McClanahan, https://struts.apache.org[Struts] is an open-source project
hosted by the Apache Software Foundation. At the time, it greatly simplified the
hosted by the Apache Software Foundation. Struts 1.x greatly simplified the
JSP/Servlet programming paradigm and won over many developers who were using proprietary
frameworks. It simplified the programming model, it was open source (and thus free as in
beer), and it had a large community, which let the project grow and become popular among
Java web developers.
frameworks. It simplified the programming model; it was open source; and it had a large
community, which let the project grow and become popular among Java web developers.
As a successor to the original Struts 1.x, check out Struts 2.x and the Struts-provided
https://struts.apache.org/release/2.3.x/docs/spring-plugin.html[Spring Plugin] for the
built-in Spring integration.
As a successor to the original Struts 1.x, check out Struts 2.x or more recent versions
as well as the Struts-provided
https://struts.apache.org/plugins/spring/[Spring Plugin] for built-in Spring integration.
[[tapestry]]
== Apache Tapestry 5.x
== Apache Tapestry
https://tapestry.apache.org/[Tapestry] is a ""Component oriented framework for creating
dynamic, robust, highly scalable web applications in Java.""
https://tapestry.apache.org/[Tapestry] is a "Component oriented framework for creating
dynamic, robust, highly scalable web applications in Java."
While Spring has its own <<mvc, powerful web layer>>, there are a number of unique
advantages to building an enterprise Java application by using a combination of Tapestry
@@ -195,6 +194,6 @@ https://tapestry.apache.org/integrating-with-spring-framework.html[integration m
The following links go to further resources about the various web frameworks described in
this chapter.
* The https://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[JSF] homepage
* The https://www.oracle.com/java/technologies/javaserverfaces.html[JSF] homepage
* The https://struts.apache.org/[Struts] homepage
* The https://tapestry.apache.org/[Tapestry] homepage