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

Stop referring to "Spring 3.x" features in documentation and code

Browse Source
This commit is contained in:
Sam Brannen
2023-01-20 11:44:34 +01:00
parent 8f94c4e933
commit 24f18275dd
39 changed files with 225 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
framework-docs/src/docs/asciidoc/core/core-aop-api.adoc
View File

@@ -1100,12 +1100,15 @@ subclass is used to implement the Decorator pattern, weaving in the advice.
CGLIB proxying should generally be transparent to users. However, there are some issues
to consider:
* `Final` methods cannot be advised, as they cannot be overridden.
* There is no need to add CGLIB to your classpath. As of Spring 3.2, CGLIB is repackaged
and included in the spring-core JAR. In other words, CGLIB-based AOP works "`out of
the box`", as do JDK dynamic proxies.
* `final` classes cannot be proxied, because they cannot be extended.
* `final` methods cannot be advised, because they cannot be overridden.
* `private` methods cannot be advised, because they cannot be overridden.
There is little performance difference between CGLIB proxying and dynamic proxies.
NOTE: There is no need to add CGLIB to your classpath. CGLIB is repackaged and included
in the `spring-core` JAR. In other words, CGLIB-based AOP works "out of the box", as do
JDK dynamic proxies.
There is little performance difference between CGLIB proxies and dynamic proxies.
Performance should not be a decisive consideration in this case.

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

@@ -524,15 +524,13 @@ container that hosts the bean. A bean usually has only one identifier. However,
requires more than one, the extra ones can be considered aliases.
In XML-based configuration metadata, you use the `id` attribute, the `name` attribute, or
both to specify the bean identifiers. The `id` attribute lets you specify
exactly one id. Conventionally, these names are alphanumeric ('myBean',
'someService', etc.), but they can contain special characters as well. If you want to
introduce other aliases for the bean, you can also specify them in the `name`
attribute, separated by a comma (`,`), semicolon (`;`), or white space. As a
historical note, in versions prior to Spring 3.1, the `id` attribute was
defined as an `xsd:ID` type, which constrained possible characters. As of 3.1,
it is defined as an `xsd:string` type. Note that bean `id` uniqueness is still
enforced by the container, though no longer by XML parsers.
both to specify bean identifiers. The `id` attribute lets you specify exactly one `id`.
Conventionally, these names are alphanumeric ('myBean', 'someService', etc.), but they
can contain special characters as well. If you want to introduce other aliases for the
bean, you can also specify them in the `name` attribute, separated by a comma (`,`),
semicolon (`;`), or white space. Although the `id` attribute is defined as an
`xsd:string` type, bean `id` uniqueness is enforced by the container, though not by XML
parsers.
You are not required to supply a `name` or an `id` for a bean. If you do not supply a
`name` or `id` explicitly, the container generates a unique name for that bean. However,
@@ -2704,8 +2702,8 @@ The following table describes the supported scopes:
the context of a web-aware Spring `ApplicationContext`.
|===
NOTE: As of Spring 3.0, a thread scope is available but is not registered by default. For
more information, see the documentation for
NOTE: A thread scope is available but is not registered by default. For more information,
see the documentation for
{api-spring-framework}/context/support/SimpleThreadScope.html[`SimpleThreadScope`].
For instructions on how to register this or any other custom scope, see
<<beans-factory-scopes-custom-using>>.
@@ -4590,26 +4588,24 @@ configuration becomes decentralized and harder to control.
No matter the choice, Spring can accommodate both styles and even mix them together.
It is worth pointing out that through its <<beans-java, JavaConfig>> option, Spring lets
annotations be used in a non-invasive way, without touching the target components
source code and that, in terms of tooling, all configuration styles are supported by the
https://spring.io/tools[Spring Tools for Eclipse].
annotations be used in a non-invasive way, without touching the target components'
source code and that, in terms of tooling, all configuration styles are supported by
https://spring.io/tools[Spring Tools] for Eclipse, Visual Studio Code, and Theia.
****
An alternative to XML setup is provided by annotation-based configuration, which relies
on the bytecode metadata for wiring up components instead of angle-bracket declarations.
Instead of using XML to describe a bean wiring, the developer moves the configuration
into the component class itself by using annotations on the relevant class, method, or
field declaration. As mentioned in <<beans-factory-extension-bpp-examples-aabpp>>, using
a `BeanPostProcessor` in conjunction with annotations is a common means of extending the
Spring IoC container. For example, Spring 2.5 introduced an annotation-based approach to
drive Spring's dependency injection. Essentially, the <<beans-autowired-annotation,
`@Autowired`>> annotation provides the same capabilities as described in
<<beans-factory-autowire>> but with more fine-grained control and wider applicability.
Spring 2.5 also added support for JSR-250 annotations, such as `@PostConstruct` and
`@PreDestroy`. Spring 3.0 added support for JSR-330 (Dependency Injection for Java)
annotations contained in the `jakarta.inject` package such as `@Inject` and `@Named`.
Details about those annotations can be found in the <<beans-standard-annotations,
relevant section>>.
on bytecode metadata for wiring up components instead of XML declarations. Instead of
using XML to describe a bean wiring, the developer moves the configuration into the
component class itself by using annotations on the relevant class, method, or field
declaration. As mentioned in <<beans-factory-extension-bpp-examples-aabpp>>, using a
`BeanPostProcessor` in conjunction with annotations is a common means of extending the
Spring IoC container. For example, the <<beans-autowired-annotation, `@Autowired`>>
annotation provides the same capabilities as described in <<beans-factory-autowire>> but
with more fine-grained control and wider applicability. In addition, Spring provides
support for JSR-250 annotations, such as `@PostConstruct` and `@PreDestroy`, as well as
support for JSR-330 (Dependency Injection for Java) annotations contained in the
`jakarta.inject` package such as `@Inject` and `@Named`. Details about those annotations
can be found in the <<beans-standard-annotations, relevant section>>.
[NOTE]
====
@@ -6237,7 +6233,7 @@ simply to be added to the application's classpath like any other library.
Most examples in this chapter use XML to specify the configuration metadata that produces
each `BeanDefinition` within the Spring container. The previous section
(<<beans-annotation-config>>) demonstrates how to provide a lot of the configuration
metadata through source-level annotations. Even in those examples, however, the "`base`"
metadata through source-level annotations. Even in those examples, however, the "base"
bean definitions are explicitly defined in the XML file, while the annotations drive only
the dependency injection. This section describes an option for implicitly detecting the
candidate components by scanning the classpath. Candidate components are classes that
@@ -6249,10 +6245,9 @@ the container.
[NOTE]
====
Starting with Spring 3.0, many features provided by the Spring JavaConfig project are
part of the core Spring Framework. This allows you to define beans using Java rather
than using the traditional XML files. Take a look at the `@Configuration`, `@Bean`,
`@Import`, and `@DependsOn` annotations for examples of how to use these new features.
You can define beans using Java rather than using XML files. Take a look at the
`@Configuration`, `@Bean`, `@Import`, and `@DependsOn` annotations for examples of how to
use these features.
====
@@ -7172,9 +7167,9 @@ arrangement (as though no index were present at all) by setting `spring.index.ig
[[beans-standard-annotations]]
== Using JSR 330 Standard Annotations
Starting with Spring 3.0, Spring offers support for JSR-330 standard annotations
(Dependency Injection). Those annotations are scanned in the same way as the Spring
annotations. To use them, you need to have the relevant jars in your classpath.
Spring offers support for JSR-330 standard annotations (Dependency Injection). Those
annotations are scanned in the same way as the Spring annotations. To use them, you need
to have the relevant jars in your classpath.
[NOTE]
=====
@@ -8611,22 +8606,24 @@ about singletons here.
[NOTE]
====
As of Spring 3.2, it is no longer necessary to add CGLIB to your classpath because CGLIB
classes have been repackaged under `org.springframework.cglib` and included directly
within the spring-core JAR.
It is not necessary to add CGLIB to your classpath because CGLIB classes are repackaged
under the `org.springframework.cglib` package and included directly within the
`spring-core` JAR.
====
[TIP]
====
There are a few restrictions due to the fact that CGLIB dynamically adds features at
startup-time. In particular, configuration classes must not be final. However, as
of 4.3, any constructors are allowed on configuration classes, including the use of
`@Autowired` or a single non-default constructor declaration for default injection.
startup-time. In particular, configuration classes must not be final. However, any
constructors are allowed on configuration classes, including the use of `@Autowired` or a
single non-default constructor declaration for default injection.
If you prefer to avoid any CGLIB-imposed limitations, consider declaring your `@Bean`
methods on non-`@Configuration` classes (for example, on plain `@Component` classes instead).
Cross-method calls between `@Bean` methods are not then intercepted, so you have
to exclusively rely on dependency injection at the constructor or method level there.
methods on non-`@Configuration` classes (for example, on plain `@Component` classes
instead) or by annotating your configuration class with
`@Configuration(proxyBeanMethods = false)`. Cross-method calls between `@Bean` methods
are then not intercepted, so you have to exclusively rely on dependency injection at the
constructor or method level there.
====

41
framework-docs/src/docs/asciidoc/core/core-validation.adoc
View File

@@ -2,7 +2,7 @@
= Validation, Data Binding, and Type Conversion
There are pros and cons for considering validation as business logic, and Spring offers
a design for validation (and data binding) that does not exclude either one of them.
a design for validation and data binding that does not exclude either one of them.
Specifically, validation should not be tied to the web tier and should be easy to localize,
and it should be possible to plug in any available validator. Considering these concerns,
Spring provides a `Validator` contract that is both basic and eminently usable
@@ -15,18 +15,18 @@ provides the aptly named `DataBinder` to do exactly that. The `Validator` and th
limited to the web layer.
The `BeanWrapper` is a fundamental concept in the Spring Framework and is used in a lot
of places. However, you probably do not need to use the `BeanWrapper`
directly. Because this is reference documentation, however, we felt that some explanation
might be in order. We explain the `BeanWrapper` in this chapter, since, if you are
going to use it at all, you are most likely do so when trying to bind data to objects.
of places. However, you probably do not need to use the `BeanWrapper` directly. Because
this is reference documentation, however, we feel that some explanation might be in
order. We explain the `BeanWrapper` in this chapter, since, if you are going to use it at
all, you are most likely do so when trying to bind data to objects.
Spring's `DataBinder` and the lower-level `BeanWrapper` both use `PropertyEditorSupport`
implementations to parse and format property values. The `PropertyEditor` and
`PropertyEditorSupport` types are part of the JavaBeans specification and are also
explained in this chapter. Spring 3 introduced a `core.convert` package that provides a
general type conversion facility, as well as a higher-level "`format`" package for
formatting UI field values. You can use these packages as simpler alternatives to
`PropertyEditorSupport` implementations. They are also discussed in this chapter.
explained in this chapter. Spring's `core.convert` package provides a general type
conversion facility, as well as a higher-level `format` package for formatting UI field
values. You can use these packages as simpler alternatives to `PropertyEditorSupport`
implementations. They are also discussed in this chapter.
Spring supports Java Bean Validation through setup infrastructure and an adaptor to
Spring's own `Validator` contract. Applications can enable Bean Validation once globally,
@@ -861,12 +861,12 @@ as needed.
[[core-convert]]
== Spring Type Conversion
Spring 3 introduced a `core.convert` package that provides a general type conversion
system. The system defines an SPI to implement type conversion logic and an API
to perform type conversions at runtime. Within a Spring container, you can use this system
as an alternative to `PropertyEditor` implementations to convert externalized bean property value
strings to the required property types. You can also use the public API anywhere in your
application where type conversion is needed.
The `core.convert` package provides a general type conversion system. The system defines
an SPI to implement type conversion logic and an API to perform type conversions at
runtime. Within a Spring container, you can use this system as an alternative to
`PropertyEditor` implementations to convert externalized bean property value strings to
the required property types. You can also use the public API anywhere in your application
where type conversion is needed.
@@ -1205,8 +1205,9 @@ web or desktop application. In such environments, you typically convert from `St
to support the client postback process, as well as back to `String` to support the
view rendering process. In addition, you often need to localize `String` values. The more
general `core.convert` `Converter` SPI does not address such formatting requirements
directly. To directly address them, Spring 3 introduced a convenient `Formatter` SPI that
provides a simple and robust alternative to `PropertyEditor` implementations for client environments.
directly. To directly address them, Spring provides a convenient `Formatter` SPI that
provides a simple and robust alternative to `PropertyEditor` implementations for client
environments.
In general, you can use the `Converter` SPI when you need to implement general-purpose type
conversion logic -- for example, for converting between a `java.util.Date` and a `Long`.
@@ -1956,9 +1957,9 @@ javadoc for more information on these options.
[[validation-binder]]
=== Configuring a `DataBinder`
Since Spring 3, you can configure a `DataBinder` instance with a `Validator`. Once
configured, you can invoke the `Validator` by calling `binder.validate()`. Any validation
`Errors` are automatically added to the binder's `BindingResult`.
You can configure a `DataBinder` instance with a `Validator`. Once configured, you can
invoke the `Validator` by calling `binder.validate()`. Any validation `Errors` are
automatically added to the binder's `BindingResult`.
The following example shows how to use a `DataBinder` programmatically to invoke validation
logic after binding to a target object:

21
framework-docs/src/docs/asciidoc/integration/scheduling.adoc
View File

@@ -136,14 +136,16 @@ To configure the rules that the `TaskExecutor` uses, we expose simple bean prope
[[scheduling-task-scheduler]]
== The Spring `TaskScheduler` Abstraction
In addition to the `TaskExecutor` abstraction, Spring 3.0 introduced a `TaskScheduler`
with a variety of methods for scheduling tasks to run at some point in the future.
The following listing shows the `TaskScheduler` interface definition:
In addition to the `TaskExecutor` abstraction, Spring has a `TaskScheduler` SPI with a
variety of methods for scheduling tasks to run at some point in the future. The following
listing shows the `TaskScheduler` interface definition:
[source,java,indent=0,subs="verbatim,quotes"]
----
public interface TaskScheduler {
Clock getClock();
ScheduledFuture schedule(Runnable task, Trigger trigger);
ScheduledFuture schedule(Runnable task, Instant startTime);
@@ -168,12 +170,11 @@ much more flexible.
[[scheduling-trigger-interface]]
=== `Trigger` Interface
The `Trigger` interface is essentially inspired by JSR-236 which, as of Spring 3.0,
was not yet officially implemented. The basic idea of the `Trigger` is that execution
times may be determined based on past execution outcomes or even arbitrary conditions.
If these determinations take into account the outcome of the preceding execution,
that information is available within a `TriggerContext`. The `Trigger` interface itself
is quite simple, as the following listing shows:
The `Trigger` interface is essentially inspired by JSR-236. The basic idea of the
`Trigger` is that execution times may be determined based on past execution outcomes or
even arbitrary conditions. If these determinations take into account the outcome of the
preceding execution, that information is available within a `TriggerContext`. The
`Trigger` interface itself is quite simple, as the following listing shows:
[source,java,indent=0,subs="verbatim,quotes"]
----
@@ -192,6 +193,8 @@ default). The following listing shows the available methods for `Trigger` implem
----
public interface TriggerContext {
Clock getClock();
Instant lastScheduledExecution();
Instant lastActualExecution();