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

General doc revision: configuration updates, consistent formatting etc

Browse Source
This commit is contained in:
Juergen Hoeller
2019-03-05 13:08:34 +01:00
parent 3eb1042a53
commit 216e4eeba4
35 changed files with 1549 additions and 1624 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
src/docs/asciidoc/core/core-appendix.adoc
View File

@@ -5,6 +5,7 @@
[[xsd-schemas]]
== XML Schemas
@@ -38,7 +39,6 @@ correct schema so that the tags in the `util` namespace are available to you):
====
[[xsd-schemas-util-constant]]
==== Using `<util:constant/>`
@@ -78,8 +78,6 @@ developer's intent ("`inject this constant value`"), and it reads better:
----
====
[[xsd-schemas-util-frfb]]
===== Setting a Bean Property or Constructor Argument from a Field Value
@@ -139,10 +137,9 @@ described in the API documentation for the
class.
Injecting enumeration values into beans as either property or constructor arguments is
easy to do in Spring. You do not actually have to do anything or know
anything about the Spring internals (or even about classes such as the
`FieldRetrievingFactoryBean`). The following example enumeration shows how easy injecting an
enum value is:
easy to do in Spring. You do not actually have to do anything or know anything about
the Spring internals (or even about classes such as the `FieldRetrievingFactoryBean`).
The following example enumeration shows how easy injecting an enum value is:
====
[source,java,indent=0]
@@ -186,7 +183,6 @@ Now consider the following setter of type `PersistenceContextType` and the corre
====
[[xsd-schemas-util-property-path]]
==== Using `<util:property-path/>`
@@ -359,7 +355,6 @@ The following example uses a `util:properties` element to make a more concise re
====
[[xsd-schemas-util-list]]
==== Using `<util:list/>`
@@ -424,7 +419,6 @@ following configuration:
If no `list-class` attribute is supplied, the container chooses a `List` implementation.
[[xsd-schemas-util-map]]
==== Using `<util:map/>`
@@ -489,7 +483,6 @@ following configuration:
If no `'map-class'` attribute is supplied, the container chooses a `Map` implementation.
[[xsd-schemas-util-set]]
==== Using `<util:set/>`
@@ -612,69 +605,64 @@ available to you:
====
[[xsd-schemas-context-pphc]]
==== Using `<property-placeholder/>`
This element activates the replacement of `${...}` placeholders, which are resolved against a
specified properties file (as a <<core.adoc#resources,Spring resource location>>). This element is
specified properties file (as a <<core.adoc#resources, Spring resource location>>). This element is
a convenience mechanism that sets up a <<core.adoc#beans-factory-placeholderconfigurer,
`PropertyPlaceholderConfigurer`>> for you. If you need more control over the
`PropertyPlaceholderConfigurer`, you can explicitly define one yourself.
[[xsd-schemas-context-ac]]
==== Using `<annotation-config/>`
This element activates the Spring infrastructure to detect annotations in bean
classes:
This element activates the Spring infrastructure to detect annotations in bean classes:
* Spring's <<core.adoc#beans-required-annotation, `@Required`>> and
<<core.adoc#beans-annotation-config, `@Autowired`>>
* JSR 250's `@PostConstruct`,
`@PreDestroy` and `@Resource` (if available)
* JPA's `@PersistenceContext` and
`@PersistenceUnit` (if available).
* Spring's <<core.adoc#beans-factory-metadata, `@Configuration`>> model
* <<core.adoc#beans-annotation-config, `@Autowired`/`@Inject`>> and `@Value`
* JSR-250's `@Resource`, `@PostConstruct` and `@PreDestroy` (if available)
* JPA's `@PersistenceContext` and `@PersistenceUnit` (if available)
* Spring's <<core.adoc#context-functionality-events-annotation, `@EventListener`>>
Alternatively, you can choose to explicitly activate the
individual `BeanPostProcessors` for those annotations.
Alternatively, you can choose to explicitly activate the individual `BeanPostProcessors`
for those annotations.
NOTE: This element does not activate processing of Spring's
<<data-access.adoc#transaction-declarative-annotations, `@Transactional`>> annotation. You can use the
<<data-access.adoc#tx-decl-explained, `<tx:annotation-driven/>`>> element for that purpose.
<<data-access.adoc#transaction-declarative-annotations, `@Transactional`>> annotation;
you can use the <<data-access.adoc#tx-decl-explained, `<tx:annotation-driven/>`>>
element for that purpose. Similarly, Spring's
<<integration.adoc#cache-annotations, caching annotations>> need to be explicitly
<<integration.adoc#cache-annotation-enable, enabled>> as well.
[[xsd-schemas-context-component-scan]]
==== Using `<component-scan/>`
This element is detailed in <<core.adoc#beans-annotation-config,
Annotation-based container configuration>>.
This element is detailed in the section on <<core.adoc#beans-annotation-config,
annotation-based container configuration>>.
[[xsd-schemas-context-ltw]]
==== Using `<load-time-weaver/>`
This element is detailed in <<core.adoc#aop-aj-ltw,
Load-time weaving with AspectJ in the Spring Framework>>.
This element is detailed in the section on <<core.adoc#aop-aj-ltw,
load-time weaving with AspectJ in the Spring Framework>>.
[[xsd-schemas-context-sc]]
==== Using `<spring-configured/>`
This element is detailed in <<core.adoc#aop-atconfigurable,
Using AspectJ to dependency inject domain objects with Spring>>.
This element is detailed in the section on <<core.adoc#aop-atconfigurable,
using AspectJ to dependency inject domain objects with Spring>>.
[[xsd-schemas-context-mbe]]
==== Using `<mbean-export/>`
This element is detailed in <<integration.adoc#jmx-context-mbeanexport,
Configuring annotation based MBean export>>.
This element is detailed in the section on <<integration.adoc#jmx-context-mbeanexport,
configuring annotation-based MBean export>>.
@@ -684,8 +672,8 @@ Configuring annotation based MBean export>>.
Last but not least, we have the elements in the `beans` schema. These elements
have been in Spring since the very dawn of the framework. Examples of the various elements
in the `beans` schema are not shown here because they are quite comprehensively covered
in <<core.adoc#beans-factory-properties-detailed,Dependencies and configuration in detail>>
(and, indeed, in that entire <<core.adoc#beans,chapter>>).
in <<core.adoc#beans-factory-properties-detailed, dependencies and configuration in detail>>
(and, indeed, in that entire <<core.adoc#beans, chapter>>).
Note that you can add zero or more key-value pairs to `<bean/>` XML definitions.
What, if anything, is done with this extra metadata is totally up to your own custom
@@ -716,9 +704,9 @@ as it stands).
<1> This is the example `meta` element
====
In the case of the preceding example, you could assume that there is some logic that
consumes the bean definition and sets up some caching infrastructure that uses the supplied
metadata.
In the case of the preceding example, you could assume that there is some logic that consumes
the bean definition and sets up some caching infrastructure that uses the supplied metadata.
@@ -738,11 +726,11 @@ Spring distribution, you should first read the appendix entitled <<xsd-config>>.
To create new XML configuration extensions:
. <<xsd-custom-schema,Author>> an XML schema to describe your custom element(s).
. <<xsd-custom-namespacehandler,Code>> a custom `NamespaceHandler` implementation.
. <<xsd-custom-parser,Code>> one or more `BeanDefinitionParser` implementations
. <<xsd-custom-schema, Author>> an XML schema to describe your custom element(s).
. <<xsd-custom-namespacehandler, Code>> a custom `NamespaceHandler` implementation.
. <<xsd-custom-parser, Code>> one or more `BeanDefinitionParser` implementations
(this is where the real work is done).
. <<xsd-custom-registration,Register>> your new artifacts with Spring.
. <<xsd-custom-registration, Register>> your new artifacts with Spring.
For a unified example, we create an
XML extension (a custom XML element) that lets us configure objects of the type
@@ -864,7 +852,7 @@ The `NamespaceHandler` interface features three methods:
* `BeanDefinitionHolder decorate(Node, BeanDefinitionHolder, ParserContext)`: Called
when Spring encounters an attribute or nested element of a different namespace.
The decoration of one or more bean definitions is used (for example) with the
<<core.adoc#beans-factory-scopes,scopes that Spring supports>>.
<<core.adoc#beans-factory-scopes, scopes that Spring supports>>.
We start by highlighting a simple example, without using decoration, after which
we show decoration in a somewhat more advanced example.
@@ -964,6 +952,7 @@ is the extraction and setting of the bean definition's unique identifier.
[[xsd-custom-registration]]
=== Registering the Handler and the Schema
The coding is finished. All that remains to be done is to make the Spring XML
parsing infrastructure aware of our custom element. We do so by registering our custom
`namespaceHandler` and custom XSD file in two special-purpose properties files. These
@@ -973,7 +962,6 @@ XML parsing infrastructure automatically picks up your new extension by consumin
these special properties files, the formats of which are detailed in the next two sections.
[[xsd-custom-registration-spring-handlers]]
==== Writing `META-INF/spring.handlers`
@@ -996,7 +984,6 @@ namespace extension and needs to exactly match exactly the value of the `targetN
attribute, as specified in your custom XSD schema.
[[xsd-custom-registration-spring-schemas]]
==== Writing 'META-INF/spring.schemas'
@@ -1067,7 +1054,6 @@ in a Spring XML configuration file:
This section presents some more detailed examples of custom XML extensions.
[[xsd-custom-custom-nested]]
==== Nesting Custom Elements within Custom Elements
@@ -1135,7 +1121,6 @@ The following listing shows the `Component` class:
public void setName(String name) {
this.name = name;
}
}
----
====
@@ -1183,16 +1168,15 @@ setter property for the `components` property. The following listing shows such
public boolean isSingleton() {
return true;
}
}
----
====
This works nicely, but it exposes a lot of Spring plumbing to the
end user. What we are going to do is write a custom extension that hides away all of
this Spring plumbing. If we stick to <<xsd-custom-introduction,the steps described
previously>>, we start off by creating the XSD schema to define the structure of our
custom tag, as the following listing shows:
This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are
going to do is write a custom extension that hides away all of this Spring plumbing.
If we stick to <<xsd-custom-introduction, the steps described previously>>, we start off
by creating the XSD schema to define the structure of our custom tag, as the following
listing shows:
====
[source,xml,indent=0]
@@ -1220,7 +1204,8 @@ custom tag, as the following listing shows:
----
====
Again following <<xsd-custom-introduction,the process described earlier>>, we then create a custom `NamespaceHandler`:
Again following <<xsd-custom-introduction, the process described earlier>>,
we then create a custom `NamespaceHandler`:
====
[source,java,indent=0]
@@ -1235,14 +1220,13 @@ Again following <<xsd-custom-introduction,the process described earlier>>, we th
public void init() {
registerBeanDefinitionParser("component", new ComponentBeanDefinitionParser());
}
}
----
====
Next up is the custom `BeanDefinitionParser`. Remember that we are creating
`BeanDefinition` that describes a `ComponentFactoryBean`. The following listing shows our
custom `BeanDefinitionParser`:
a `BeanDefinition` that describes a `ComponentFactoryBean`. The following
listing shows our custom `BeanDefinitionParser` implementation:
====
[source,java,indent=0]
@@ -1292,7 +1276,6 @@ custom `BeanDefinitionParser`:
}
factory.addPropertyValue("children", children);
}
}
----
====
@@ -1317,21 +1300,20 @@ http\://www.foo.com/schema/component/component.xsd=com/foo/component.xsd
====
[[xsd-custom-custom-just-attributes]]
==== Custom Attributes on "`Normal`" Elements
Writing your own custom parser and the associated artifacts is not hard. However, it is sometimes
not the right thing to do. Consider a scenario where you need to add metadata to
already existing bean definitions. In this case, you certainly do not want to have to
write your own entire custom extension. Rather, you merely want to add an
additional attribute to the existing bean definition element.
Writing your own custom parser and the associated artifacts is not hard. However,
it is sometimes not the right thing to do. Consider a scenario where you need to
add metadata to already existing bean definitions. In this case, you certainly
do not want to have to write your own entire custom extension. Rather, you merely
want to add an additional attribute to the existing bean definition element.
By way of another example, suppose that you define a bean
definition for a service object that (unknown to it) accesses a clustered
http://jcp.org/en/jsr/detail?id=107[JCache], and you want to ensure that the named
JCache instance is eagerly started within the surrounding cluster. The following
listing shows such a definition:
By way of another example, suppose that you define a bean definition for a
service object that (unknown to it) accesses a clustered
http://jcp.org/en/jsr/detail?id=107[JCache], and you want to ensure that the
named JCache instance is eagerly started within the surrounding cluster.
The following listing shows such a definition:
====
[source,xml,indent=0]
@@ -1367,13 +1349,12 @@ JCache-initializing `BeanDefinition`. The following listing shows our `JCacheIni
public void initialize() {
// lots of JCache API calls to initialize the named cache...
}
}
----
====
Now we can move onto the custom extension. First, we need to author the XSD schema that describes the
custom attribute, as follows:
Now we can move onto the custom extension. First, we need to author
the XSD schema that describes the custom attribute, as follows:
====
[source,xml,indent=0]
@@ -1413,9 +1394,9 @@ Next, we need to create the associated `NamespaceHandler`, as follows:
----
====
Next, we need to create the parser. Note that, in this case, because we are going to parse an XML
attribute, we write a `BeanDefinitionDecorator` rather than a `BeanDefinitionParser`.
The following listing shows our `BeanDefinitionDecorator`:
Next, we need to create the parser. Note that, in this case, because we are going to parse
an XML attribute, we write a `BeanDefinitionDecorator` rather than a `BeanDefinitionParser`.
The following listing shows our `BeanDefinitionDecorator` implementation:
====
[source,java,indent=0]
@@ -1470,7 +1451,6 @@ The following listing shows our `BeanDefinitionDecorator`:
}
return beanName;
}
}
----
====

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

@@ -104,13 +104,13 @@ Spring IoC container.
NOTE: XML-based metadata is not the only allowed form of configuration metadata.
The Spring IoC container itself is totally decoupled from the format in which this
configuration metadata is actually written. These days, many developers choose
<<beans-java,Java-based configuration>> for their Spring applications.
<<beans-java, Java-based configuration>> for their Spring applications.
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
* <<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
@@ -265,7 +265,7 @@ XML configuration file represents a logical layer or module in your architecture
You can use the application context constructor to load bean definitions from all these
XML fragments. This constructor takes multiple `Resource` locations, as was shown in the
<<beans-factory-instantiation,previous section>>. Alternatively, use one or more
<<beans-factory-instantiation, previous section>>. Alternatively, use one or more
occurrences of the `<import/>` element to load bean definitions from another file or
files. The following example shows how to do so:
@@ -1024,8 +1024,8 @@ example shows:
Keep in mind that, to make this work out of the box, your code must be compiled with the
debug flag enabled so that Spring can look up the parameter name from the constructor.
If you cannot or do not want to compile your code with the debug flag, you can use
http://download.oracle.com/javase/6/docs/api/java/beans/ConstructorProperties.html[@ConstructorProperties]
If you cannot or do not want to compile your code with the debug flag, you can use the
http://download.oracle.com/javase/8/docs/api/java/beans/ConstructorProperties.html[@ConstructorProperties]
JDK annotation to explicitly name your constructor arguments. The sample class would
then have to look as follows:
@@ -1096,7 +1096,7 @@ load an entire Spring IoC container instance.
****
Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to
use constructors for mandatory dependencies and setter methods or configuration methods
for optional dependencies. Note that use of the <<beans-required-annotation,@Required>>
for optional dependencies. Note that use of the <<beans-required-annotation, @Required>>
annotation on a setter method can be used to make the property be a required dependency;
however, constructor injection with programmatic validation of arguments is preferable.
@@ -1189,7 +1189,7 @@ to being injected into the dependent bean. This means that, if bean A has a depe
bean B, the Spring IoC container completely configures bean B prior to invoking the
setter method on bean A. In other words, the bean is instantiated (if it is not a
pre-instantiated singleton), its dependencies are set, and the relevant lifecycle
methods (such as a <<beans-factory-lifecycle-initializingbean,configured init method>>
methods (such as a <<beans-factory-lifecycle-initializingbean, configured init method>>
or the <<beans-factory-lifecycle-initializingbean,InitializingBean callback method>>)
are invoked.
@@ -1358,7 +1358,7 @@ do not discuss those details here.
[[beans-factory-properties-detailed]]
=== Dependencies and Configuration in Detail
As mentioned in the <<beans-factory-collaborators,previous section>>, you can define bean
As mentioned in the <<beans-factory-collaborators, previous section>>, you can define bean
properties and constructor arguments as references to other managed beans (collaborators)
or as values defined inline. Spring's XML-based configuration metadata supports
sub-element types within its `<property/>` and `<constructor-arg/>` elements for this
@@ -2195,11 +2195,11 @@ In the latter scenario, you have several options:
* Abandon autowiring in favor of explicit wiring.
* Avoid autowiring for a bean definition by setting its `autowire-candidate` attributes
to `false`, as described in the <<beans-factory-autowire-candidate,next section>>.
to `false`, as described in the <<beans-factory-autowire-candidate, next section>>.
* Designate a single bean definition as the primary candidate by setting the
`primary` attribute of its `<bean/>` element to `true`.
* Implement the more fine-grained control available
with annotation-based configuration, as described in <<beans-annotation-config>>.
* Implement the more fine-grained control available with annotation-based configuration,
as described in <<beans-annotation-config>>.
@@ -2304,7 +2304,7 @@ https://spring.io/blog/2004/08/06/method-injection/[this blog entry].
Lookup method injection is the ability of the container to override methods on
container-managed beans and return the lookup result for another named bean in the
container. The lookup typically involves a prototype bean, as in the scenario described
in <<beans-factory-method-injection,the preceding section>>. The Spring Framework
in <<beans-factory-method-injection, the preceding section>>. The Spring Framework
implements this method injection by using bytecode generation from the CGLIB library to
dynamically generate a subclass that overrides the method.
@@ -3524,7 +3524,7 @@ configured with a different method name, then each configured method is executed
order listed after this note. However, if the same method name is configured -- for example,
`init()` for an initialization method -- for more than one of these lifecycle mechanisms,
that method is executed once, as explained in the
<<beans-factory-lifecycle-default-init-destroy-methods,preceding section>>.
<<beans-factory-lifecycle-default-init-destroy-methods, preceding section>>.
Multiple lifecycle mechanisms configured for the same bean, with different
initialization methods, are called as follows:
@@ -3789,7 +3789,7 @@ init-method.
[[aware-list]]
=== Other `Aware` Interfaces
Besides `ApplicationContextAware` and `BeanNameAware` (discussed <<beans-factory-aware,earlier>>),
Besides `ApplicationContextAware` and `BeanNameAware` (discussed <<beans-factory-aware, earlier>>),
Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container
that they require a certain infrastructure dependency. As a general rule, the name indicates the
dependency type. The following table summarizes the most important `Aware` interfaces:
@@ -4459,7 +4459,7 @@ while others argue that annotated classes are no longer POJOs and, furthermore,
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
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/sts[Spring Tool Suite].
@@ -4864,7 +4864,7 @@ an `ApplicationContext` object:
[NOTE]
====
The `@Autowired`, `@Inject`, `@Resource`, and `@Value` annotations are handled by Spring
The `@Autowired`, `@Inject`, `@Value`, and `@Resource` annotations are handled by Spring
`BeanPostProcessor` implementations. This means that you cannot apply these annotations
within your own `BeanPostProcessor` or `BeanFactoryPostProcessor` types (if any).
These types must be 'wired up' explicitly by using XML or a Spring `@Bean` method.
@@ -5648,9 +5648,9 @@ supported as a marker for automatic exception translation in your persistence la
=== Using Meta-annotations and Composed Annotations
Many of the annotations provided by Spring can be used as meta-annotations in your
own code. A meta-annotation is an annotation that can be applied to another
annotation. For example, the `@Service` annotation mentioned <<beans-stereotype-annotations,earlier>> is meta-annotated with
`@Component`, as the following example shows:
own code. A meta-annotation is an annotation that can be applied to another annotation.
For example, the `@Service` annotation mentioned <<beans-stereotype-annotations, earlier>>
is meta-annotated with `@Component`, as the following example shows:
====
[source,java,indent=0]
@@ -5814,16 +5814,16 @@ TIP: The use of `<context:component-scan>` implicitly enables the functionality
====
The scanning of classpath packages requires the presence of corresponding directory
entries in the classpath. When you build JARs with Ant, make sure that you do not
activate the files-only switch of the JAR task. Also, classpath directories may not
be exposed based on security policies in some environments -- for example, standalone apps on
activate the files-only switch of the JAR task. Also, classpath directories may not be
exposed based on security policies in some environments -- for example, standalone apps on
JDK 1.7.0_45 and higher (which requires 'Trusted-Library' setup in your manifests -- see
http://stackoverflow.com/questions/19394570/java-jre-7u45-breaks-classloader-getresources).
On JDK 9's module path (Jigsaw), Spring's classpath scanning generally works as expected.
However, make sure that your component classes are exported in your `module-info`
descriptors. If you expect Spring to invoke non-public members of your classes, make
sure that they are 'opened' (that is, that they use an `opens` declaration instead of an `exports`
declaration in your `module-info` descriptor).
sure that they are 'opened' (that is, that they use an `opens` declaration instead of an
`exports` declaration in your `module-info` descriptor).
====
Furthermore, the `AutowiredAnnotationBeanPostProcessor` and
@@ -6855,7 +6855,7 @@ following example shows:
----
====
NOTE: Remember that `@Configuration` classes are <<beans-meta-annotations,meta-annotated>>
NOTE: Remember that `@Configuration` classes are <<beans-meta-annotations, meta-annotated>>
with `@Component`, so they are candidates for component-scanning. In the preceding example,
assuming that `AppConfig` is declared within the `com.acme` package (or any package
underneath), it is picked up during the call to `scan()`. Upon `refresh()`, all its `@Bean`
@@ -6935,8 +6935,8 @@ init-param):
`@Bean` is a method-level annotation and a direct analog of the XML `<bean/>` element.
The annotation supports some of the attributes offered by `<bean/>`, such as:
* <<beans-factory-lifecycle-initializingbean,init-method>>
* <<beans-factory-lifecycle-disposablebean,destroy-method>>
* <<beans-factory-lifecycle-initializingbean, init-method>>
* <<beans-factory-lifecycle-disposablebean, destroy-method>>
* <<beans-factory-autowire,autowiring>>
* `name`.
@@ -7048,7 +7048,7 @@ parameter, as the following example shows:
====
The resolution mechanism is pretty much identical to constructor-based dependency
injection. See <<beans-constructor-injection,the relevant section>> for more details.
injection. See <<beans-constructor-injection, the relevant section>> for more details.
[[beans-java-lifecycle-callbacks]]
@@ -7056,17 +7056,17 @@ injection. See <<beans-constructor-injection,the relevant section>> for more det
Any classes defined with the `@Bean` annotation support the regular lifecycle callbacks
and can use the `@PostConstruct` and `@PreDestroy` annotations from JSR-250. See
<<beans-postconstruct-and-predestroy-annotations,JSR-250 annotations>> for further
<<beans-postconstruct-and-predestroy-annotations, JSR-250 annotations>> for further
details.
The regular Spring <<beans-factory-nature,lifecycle>> callbacks are fully supported as
The regular Spring <<beans-factory-nature, lifecycle>> callbacks are fully supported as
well. If a bean implements `InitializingBean`, `DisposableBean`, or `Lifecycle`, their
respective methods are called by the container.
The standard set of `*Aware` interfaces (such as <<beans-beanfactory,BeanFactoryAware>>,
<<beans-factory-aware,BeanNameAware>>,
<<context-functionality-messagesource,MessageSourceAware>>,
<<beans-factory-aware,ApplicationContextAware>>, and so on) are also fully supported.
The standard set of `*Aware` interfaces (such as <<beans-beanfactory, BeanFactoryAware>>,
<<beans-factory-aware, BeanNameAware>>,
<<context-functionality-messagesource, MessageSourceAware>>,
<<beans-factory-aware, ApplicationContextAware>>, and so on) are also fully supported.
The `@Bean` annotation supports specifying arbitrary initialization and destruction
callback methods, much like Spring XML's `init-method` and `destroy-method` attributes
@@ -7176,7 +7176,7 @@ Spring includes the `@Scope` annotation so that you can specify the scope of a b
You can specify that your beans defined with the `@Bean` annotation should have a
specific scope. You can use any of the standard scopes specified in the
<<beans-factory-scopes,Bean Scopes>> section.
<<beans-factory-scopes, Bean Scopes>> section.
The default scope is `singleton`, but you can override this with the `@Scope` annotation,
as the following example shows:
@@ -7201,14 +7201,15 @@ as the following example shows:
===== `@Scope` and `scoped-proxy`
Spring offers a convenient way of working with scoped dependencies through
<<beans-factory-scopes-other-injection,scoped proxies>>. The easiest way to create such
a proxy when using the XML configuration is the `<aop:scoped-proxy/>` element.
Configuring your beans in Java with a `@Scope` annotation offers equivalent support with
the `proxyMode` attribute. The default is no proxy (`ScopedProxyMode.NO`), but you can
specify `ScopedProxyMode.TARGET_CLASS` or `ScopedProxyMode.INTERFACES`.
<<beans-factory-scopes-other-injection, scoped proxies>>. The easiest way to create
such a proxy when using the XML configuration is the `<aop:scoped-proxy/>` element.
Configuring your beans in Java with a `@Scope` annotation offers equivalent support
with the `proxyMode` attribute. The default is no proxy (`ScopedProxyMode.NO`),
but you can specify `ScopedProxyMode.TARGET_CLASS` or `ScopedProxyMode.INTERFACES`.
If you port the scoped proxy example from the XML reference documentation (see
<<beans-factory-scopes-other-injection,scoped proxies>>) to our `@Bean` using Java, it resembles the following:
<<beans-factory-scopes-other-injection, scoped proxies>>) to our `@Bean` using Java,
it resembles the following:
====
[source,java,indent=0]
@@ -7354,7 +7355,7 @@ by using plain `@Component` classes.
[[beans-java-method-injection]]
==== Lookup Method Injection
As noted earlier, <<beans-factory-method-injection,lookup method injection>> is an
As noted earlier, <<beans-factory-method-injection, lookup method injection>> is an
advanced feature that you should use rarely. It is useful in cases where a
singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java for this
type of configuration provides a natural means for implementing this pattern. The
@@ -7552,7 +7553,7 @@ issue, because no compiler is involved, and you can declare
When using `@Configuration` classes, the Java compiler places constraints on
the configuration model, in that references to other beans must be valid Java syntax.
Fortunately, solving this problem is simple. As <<beans-java-dependencies,we already discussed>>,
Fortunately, solving this problem is simple. As <<beans-java-dependencies, we already discussed>>,
a `@Bean` method can have an arbitrary number of parameters that describe the bean
dependencies. Consider the following more real-world scenario with several `@Configuration`
classes, each depending on beans declared in the others:
@@ -8030,8 +8031,8 @@ jdbc.password=
The {api-spring-framework}/core/env/Environment.html[`Environment`] interface
is an abstraction integrated in the container that models two key
aspects of the application environment: <<beans-definition-profiles,profiles>>
and <<beans-property-source-abstraction,properties>>.
aspects of the application environment: <<beans-definition-profiles, profiles>>
and <<beans-property-source-abstraction, properties>>.
A profile is a named, logical group of bean definitions to be registered with the
container only if the given profile is active. Beans may be assigned to a profile
@@ -8174,7 +8175,7 @@ NOTE: You cannot mix the `&` and `|` operators without using parentheses. For ex
`production & us-east | eu-central` is not a valid expression. It must be expressed as
`production & (us-east | eu-central)`.
You can use `@Profile` as a <<beans-meta-annotations,meta-annotation>> for the purpose
You can use `@Profile` as a <<beans-meta-annotations, meta-annotation>> for the purpose
of creating a custom composed annotation. The following example defines a custom
`@Production` annotation that you can use as a drop-in replacement for
`@Profile("production")`:
@@ -8382,9 +8383,9 @@ In addition, you can also declaratively activate profiles through the
`spring.profiles.active` property, which may be specified through system environment
variables, JVM system properties, servlet context parameters in `web.xml`, or even as an
entry in JNDI (see <<beans-property-source-abstraction>>). In integration tests, active
profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test` module
(see <<testing.adoc#testcontext-ctx-management-env-profiles,
Context configuration with environment profiles>>).
profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test`
module (see <<testing.adoc#testcontext-ctx-management-env-profiles,
context configuration with environment profiles>>).
Note that profiles are not an "`either-or`" proposition. You can activate multiple
profiles at once. Programmatically, you can provide multiple profile names to the
@@ -8656,9 +8657,10 @@ Alternatively, for XML configuration, you can use the `context:load-time-weaver`
Once configured for the `ApplicationContext`, any bean within that `ApplicationContext`
may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-time
weaver instance. This is particularly useful in combination with
<<data-access.adoc#orm-jpa,Spring's JPA support>> where load-time weaving may be necessary
for JPA class transformation.
Consult the {api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`]
<<data-access.adoc#orm-jpa, Spring's JPA support>> where load-time weaving may be
necessary for JPA class transformation.
Consult the
{api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`]
javadoc for more detail. For more on AspectJ load-time weaving, see <<aop-aj-ltw>>.
@@ -8667,7 +8669,7 @@ javadoc for more detail. For more on AspectJ load-time weaving, see <<aop-aj-ltw
[[context-introduction]]
== Additional Capabilities of the `ApplicationContext`
As discussed in the <<beans,chapter introduction>>, the `org.springframework.beans.factory`
As discussed in the <<beans, chapter introduction>>, the `org.springframework.beans.factory`
package provides basic functionality for managing and manipulating beans, including in a
programmatic way. The `org.springframework.context` package adds the
{api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`]
@@ -8919,7 +8921,7 @@ class and the `ApplicationListener` interface. If a bean that implements the
Essentially, this is the standard Observer design pattern.
TIP: As of Spring 4.2, the event infrastructure has been significantly improved and offers
an <<context-functionality-events-annotation,annotation-based model>> as well as the
an <<context-functionality-events-annotation, annotation-based model>> as well as the
ability to publish any arbitrary event (that is, an object that does not necessarily
extend from `ApplicationEvent`). When such an object is published, we wrap it in an
event for you.
@@ -9149,12 +9151,12 @@ following example shows how to do so:
----
====
It is also possible to add additional runtime filtering by using the `condition` attribute of the
annotation that defines a <<expressions,`SpEL` expression>> , which should match to actually
invoke the method for a particular event.
It is also possible to add additional runtime filtering by using the `condition` attribute
of the annotation that defines a <<expressions, `SpEL` expression>> , which should match
to actually invoke the method for a particular event.
The following example shows how our notifier can be rewritten to be invoked only if the `content` attribute
of the event is equal to `my-event`:
The following example shows how our notifier can be rewritten to be invoked only if the
`content` attribute of the event is equal to `my-event`:
====
[source,java,indent=0]
@@ -9211,8 +9213,8 @@ method signature to return the event that should be published, as the following
----
====
NOTE: This feature is not supported for <<context-functionality-events-async,asynchronous
listeners>>.
NOTE: This feature is not supported for
<<context-functionality-events-async, asynchronous listeners>>.
This new method publishes a new `ListUpdateEvent` for every `BlackListEvent` handled by the
method above. If you need to publish several events, you can return a `Collection` of events
@@ -9223,8 +9225,8 @@ instead.
==== Asynchronous Listeners
If you want a particular listener to process events asynchronously, you can reuse the
<<integration.adoc#scheduling-annotation-support-async,regular `@Async` support>>. The
following example shows how to do so:
<<integration.adoc#scheduling-annotation-support-async, regular `@Async` support>>.
The following example shows how to do so:
====
[source,java,indent=0]
@@ -9243,8 +9245,9 @@ Be aware of the following limitations when using asynchronous events:
* If the event listener throws an `Exception`, it is not propagated to the caller
See `AsyncUncaughtExceptionHandler` for more details.
* Such event listener cannot send replies. If you need to send another event as the
result of the processing, inject {api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`ApplicationEventPublisher`] to send the event
manually.
result of the processing, inject
{api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`ApplicationEventPublisher`]
to send the event manually.
[[context-functionality-events-order]]
@@ -9320,9 +9323,8 @@ an event.
[[context-functionality-resources]]
=== Convenient Access to Low-level Resources
For optimal usage and understanding of application contexts, you should
familiarize yourself with Spring's `Resource` abstraction, as described in
<<resources>>.
For optimal usage and understanding of application contexts, you should familiarize
yourself with Spring's `Resource` abstraction, as described in <<resources>>.
An application context is a `ResourceLoader`, which can be used to load `Resource` objects.
A `Resource` is essentially a more feature rich version of the JDK `java.net.URL` class.
@@ -9478,11 +9480,11 @@ by convention (that is, by bean name or by bean type -- in particular, post-proc
while a plain `DefaultListableBeanFactory` is agnostic about any special beans.
For many extended container features, such as annotation processing and AOP proxying,
the <<beans-factory-extension-bpp,`BeanPostProcessor` extension point>> is essential.
the <<beans-factory-extension-bpp, `BeanPostProcessor` extension point>> is essential.
If you use only a plain `DefaultListableBeanFactory`, such post-processors do not
get detected and activated by default. This situation could be confusing, because
nothing is actually wrong with your bean configuration. Rather, in such a scenario, the
container needs to be fully bootstrapped through additional setup.
nothing is actually wrong with your bean configuration. Rather, in such a scenario,
the container needs to be fully bootstrapped through additional setup.
The following table lists features provided by the `BeanFactory` and
`ApplicationContext` interfaces and implementations.

7
src/docs/asciidoc/core/core-databuffer-codec.adoc
View File

@@ -10,7 +10,7 @@ APIs as follows:
* <<databuffers-factory>> abstracts the creation of a data buffer.
* <<databuffers-buffer>> represents a byte buffer, which may be
<<databuffers-buffer-pooled,pooled>>.
<<databuffers-buffer-pooled, pooled>>.
* <<databuffers-utils>> offers utility methods for data buffers.
* <<Codecs>> decode or encode streams data buffer streams into higher level objects.
@@ -93,7 +93,6 @@ composite buffers, if that's supported by the underlying byte buffer API.
[[codecs]]
== Codecs
@@ -105,7 +104,7 @@ The `org.springframework.core.codec` package provides the following strategy int
The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and
`String` encoder and decoder implementations. The `spring-web` module adds Jackson JSON,
Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See
<<web-reactive.adoc#webflux-codecs,Codecs>> in the WebFlux section.
<<web-reactive.adoc#webflux-codecs, Codecs>> in the WebFlux section.
@@ -114,7 +113,7 @@ Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See
== Using `DataBuffer`
When working with data buffers, special care must be taken to ensure buffers are released
since they may be <<databuffers-buffer-pooled,pooled>>. We'll use codecs to illustrate
since they may be <<databuffers-buffer-pooled, pooled>>. We'll use codecs to illustrate
how that works but the concepts apply more generally. Let's see what codecs must do
internally to manage data buffers.

31
src/docs/asciidoc/core/core-expressions.adoc
View File

@@ -10,8 +10,8 @@ While there are several other Java expression languages available -- OGNL, MVEL,
EL, to name a few -- the Spring Expression Language was created to provide the Spring
community with a single well supported expression language that can be used across all
the products in the Spring portfolio. Its language features are driven by the
requirements of the projects in the Spring portfolio, including tooling requirements for
code completion support within the Eclipse-based Spring Tool Suite. That said,
requirements of the projects in the Spring portfolio, including tooling requirements
for code completion support within the Eclipse-based Spring Tool Suite. That said,
SpEL is based on a technology-agnostic API that lets other expression language
implementations be integrated, should the need arise.
@@ -20,14 +20,14 @@ portfolio, it is not directly tied to Spring and can be used independently. To
be self contained, many of the examples in this chapter use SpEL as if it were an
independent expression language. This requires creating a few bootstrapping
infrastructure classes, such as the parser. Most Spring users need not deal with
this infrastructure and can, instead, author only expression strings for evaluation. An
example of this typical use is the integration of SpEL into creating XML or annotation-based
bean definitions, as shown in <<expressions-beandef,Expression support
for defining bean definitions>>.
this infrastructure and can, instead, author only expression strings for evaluation.
An example of this typical use is the integration of SpEL into creating XML or
annotation-based bean definitions, as shown in
<<expressions-beandef, Expression support for defining bean definitions>>.
This chapter covers the features of the expression language, its API, and its language
syntax. In several places, `Inventor` and `Society` classes are used as the
target objects for expression evaluation. These class declarations and the data used to
syntax. In several places, `Inventor` and `Society` classes are used as the target
objects for expression evaluation. These class declarations and the data used to
populate them are listed at the end of the chapter.
The expression language supports the following functionality:
@@ -60,7 +60,7 @@ The expression language supports the following functionality:
This section introduces the simple use of SpEL interfaces and its expression language.
The complete language reference can be found in
<<expressions-language-ref,Language Reference>>.
<<expressions-language-ref, Language Reference>>.
The following code introduces the SpEL API to evaluate the literal string expression,
`Hello World`.
@@ -332,13 +332,14 @@ interpreter and only 3ms using the compiled version of the expression.
[[expressions-compiler-configuration]]
==== Compiler Configuration
The compiler is not turned on by default, but you can turn it on in either of two different ways.
You can turn it on by using the parser configuration process (<<expressions-parser-configuration,discussed earlier>>)
or by using a system property when SpEL usage is embedded inside another component. This section
The compiler is not turned on by default, but you can turn it on in either of two
different ways. You can turn it on by using the parser configuration process
(<<expressions-parser-configuration, discussed earlier>>) or by using a system
property when SpEL usage is embedded inside another component. This section
discusses both of these options.
The compiler can operate in one of three modes, which are captured
in the `org.springframework.expression.spel.SpelCompilerMode` enum. The modes are as follows:
The compiler can operate in one of three modes, which are captured in the
`org.springframework.expression.spel.SpelCompilerMode` enum. The modes are as follows:
* `OFF` (default): The compiler is switched off.
* `IMMEDIATE`: In immediate mode, the expressions are compiled as soon as possible. This
@@ -641,7 +642,7 @@ By default, real numbers are parsed by using Double.parseDouble().
Navigating with property references is easy. To do so, use a period to indicate a nested
property value. The instances of the `Inventor` class, `pupin` and `tesla`, were populated with
data listed in the <<expressions-example-classes,Classes used in the examples>> section.
data listed in the <<expressions-example-classes, Classes used in the examples>> section.
To navigate "`down`" and get Tesla's year of birth and Pupin's city of birth, we use the following
expressions:

62
src/docs/asciidoc/core/core-null-safety.adoc
View File

@@ -1,29 +1,31 @@
[[null-safety]]
[-[null-safety]]
= Null-safety
Although Java does not let you express null-safety with its type system, Spring Framework
now provides the following annotations in the `org.springframework.lang` package to let you declare
nullability of APIs and fields:
Although Java does not let you express null-safety with its type system, the Spring Framework
now provides the following annotations in the `org.springframework.lang` package to let you
declare nullability of APIs and fields:
* {api-spring-framework}/lang/NonNull.html[`@NonNull`]: Annotation to indicate that a specific parameter,
return value, or field cannot be `null` (not needed on parameter and return value
where `@NonNullApi` and `@NonNullFields` apply) .
* {api-spring-framework}/lang/Nullable.html[`@Nullable`]: Annotation to indicate that a specific
parameter, return value, or field can be `null`.
* {api-spring-framework}/lang/Nullable.html[`@Nullable`]: Annotation to indicate that a
specific parameter, return value, or field can be `null`.
* {api-spring-framework}/lang/NonNull.html[`@NonNull`]: Annotation to indicate that a specific
parameter, return value, or field cannot be `null` (not needed on parameters / return values
and fields where `@NonNullApi` and `@NonNullFields` apply, respectively).
* {api-spring-framework}/lang/NonNullApi.html[`@NonNullApi`]: Annotation at the package level
that declares non-null as the default behavior for parameters and return values.
that declares non-null as the default semantics for parameters and return values.
* {api-spring-framework}/lang/NonNullFields.html[`@NonNullFields`]: Annotation at the package
level that declares non-null as the default behavior for fields.
level that declares non-null as the default semantics for fields.
Spring Framework leverages itself these annotations, but they can also be used in any Spring based
Java project to declare null-safe APIs and optionally null-safe fields. Generic type arguments,
varargs and array elements nullability are not supported yet, but should be in an upcoming
release, see https://jira.spring.io/browse/SPR-15942[SPR-15942] for up-to-date information.
Nullability declaration are expected to be fine-tuned between Spring Framework release,
including minor ones. Nullability of types used inside method bodies is outside of the
scope of this feature.
The Spring Framework itself leverages these annotations, but they can also be used in any
Spring-based Java project to declare null-safe APIs and optionally null-safe fields.
Generic type arguments, varargs and array elements nullability are not supported yet but
should be in an upcoming release, see https://jira.spring.io/browse/SPR-15942[SPR-15942]
for up-to-date information. Nullability declarations are expected to be fine-tuned between
Spring Framework releases, including minor ones. Nullability of types used inside method
bodies is outside of the scope of this feature.
NOTE: Libraries like Reactor or Spring Data provide null-safe APIs that use this feature.
NOTE: Other common libraries such as Reactor and Spring Data provide null-safe APIs that
use a similar nullability arrangement, delivering a consistent overall experience for
Spring application developers.
@@ -32,25 +34,23 @@ NOTE: Libraries like Reactor or Spring Data provide null-safe APIs that use this
In addition to providing an explicit declaration for Spring Framework API nullability,
these annotations can be used by an IDE (such as IDEA or Eclipse) to provide useful
warnings related to null-safety in order to avoid `NullPointerException`
at runtime.
warnings related to null-safety in order to avoid `NullPointerException` at runtime.
They are also used to make Spring API null-safe in Kotlin projects, since Kotlin natively
supports https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details
are available in the <<languages#kotlin-null-safety,Kotlin support documentation>>.
are available in the <<languages#kotlin-null-safety, Kotlin support documentation>>.
== JSR 305 meta-annotations
== JSR-305 meta-annotations
Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305]
annotations (a dormant but widely spread JSR). JSR 305 meta-annotations let tooling vendors
like IDEA or Kotlin provide null-safety support in a generic way, without having to hard-code
support for Spring annotations.
annotations (a dormant but wide-spread JSR). JSR-305 meta-annotations let tooling vendors
like IDEA or Kotlin provide null-safety support in a generic way, without having to
hard-code support for Spring annotations.
It is not necessary nor recommended to add JSR 305 dependency in the project classpath to
take advantage of Spring null-safe API. Only projects such as
Spring-based libraries that use null-safety annotations in their codebase should add
`com.google.code.findbugs:jsr305:3.0.2` with `compileOnly` Gradle configuration or Maven
`provided` scope to avoid compile warnings.
It is not necessary nor recommended to add a JSR-305 dependency to the project classpath to
take advantage of Spring null-safe API. Only projects such as Spring-based libraries that use
null-safety annotations in their codebase should add `com.google.code.findbugs:jsr305:3.0.2`
with `compileOnly` Gradle configuration or Maven `provided` scope to avoid compile warnings.

8
src/docs/asciidoc/core/core-resources.adoc
View File

@@ -351,10 +351,10 @@ interface if that is all you need. The code would be coupled only to the resourc
interface (which can be considered a utility interface) and not to the whole Spring
`ApplicationContext` interface.
As of Spring 2.5, you can rely upon autowiring of the `ResourceLoader` as an alternative
to implementing the `ResourceLoaderAware` interface. The "`traditional`" `constructor` and
`byType` autowiring modes (as described in <<beans-factory-autowire>>) are now capable of
providing a dependency of type `ResourceLoader` for either a constructor argument or a
In application components, you may also rely upon autowiring of the `ResourceLoader` as
an alternative to implementing the `ResourceLoaderAware` interface. The "`traditional`"
`constructor` and `byType` autowiring modes (as described in <<beans-factory-autowire>>)
are capable of providing a `ResourceLoader` for either a constructor argument or a
setter method parameter, respectively. For more flexibility (including the ability to
autowire fields and multiple parameter methods), consider using the annotation-based
autowiring features. In that case, the `ResourceLoader` is autowired into a field,

88
src/docs/asciidoc/core/core-validation.adoc
View File

@@ -20,18 +20,19 @@ directly. Because this is reference documentation, however, we felt that some ex
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` interfaces 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.
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.
.JSR-303/JSR-349 Bean Validation
****
As of version 4.0, Spring Framework supports Bean Validation 1.0 (JSR-303) and Bean Validation 1.1
(JSR-349) for setup support and adapting them to Spring's `Validator` interface.
As of version 4.0, Spring Framework supports Bean Validation 1.0 (JSR-303) and
Bean Validation 1.1 (JSR-349) for setup support and adapting them to Spring's
`Validator` interface.
An application can choose to enable Bean Validation once globally, as described in
<<validation-beanvalidation>>, and use it exclusively for all validation needs.
@@ -173,22 +174,21 @@ methods it offers can be found in the {api-spring-framework}validation/Errors.ht
[[validation-conversion]]
== Resolving Codes to Error Messages
We covered databinding and validation. This section covers outputting messages that correspond to
validation errors. In the example shown in the <<validator,preceding section>>,
we rejected the `name` and `age` fields. If we want to output the error
messages by using a `MessageSource`, we can do so using the error code we provide when
rejecting the field ('name' and 'age' in this case). When you call (either directly, or
indirectly, by using, for example, the `ValidationUtils` class) `rejectValue` or one of the
other `reject` methods from the `Errors` interface, the underlying implementation
not only registers the code you passed in but also registers a number of additional error
codes. The `MessageCodesResolver` determines which error codes the `Errors` interface registers.
By default, the `DefaultMessageCodesResolver` is used, which (for example) not only
registers a message with the code you gave but also registers messages that include the field
name you passed to the reject method. So, if you reject a field by using
`rejectValue("age", "too.darn.old")`, apart from the `too.darn.old` code, Spring
also registers `too.darn.old.age` and `too.darn.old.age.int` (the first includes
the field name and the second includes the type of the field). This is done as a
convenience to aid developers when targeting error messages.
We covered databinding and validation. This section covers outputting messages that correspond
to validation errors. In the example shown in the <<validator, preceding section>>,
we rejected the `name` and `age` fields. If we want to output the error messages by using a
`MessageSource`, we can do so using the error code we provide when rejecting the field
('name' and 'age' in this case). When you call (either directly, or indirectly, by using,
for example, the `ValidationUtils` class) `rejectValue` or one of the other `reject` methods
from the `Errors` interface, the underlying implementation not only registers the code you
passed in but also registers a number of additional error codes. The `MessageCodesResolver`
determines which error codes the `Errors` interface registers. By default, the
`DefaultMessageCodesResolver` is used, which (for example) not only registers a message
with the code you gave but also registers messages that include the field name you passed
to the reject method. So, if you reject a field by using `rejectValue("age", "too.darn.old")`,
apart from the `too.darn.old` code, Spring also registers `too.darn.old.age` and
`too.darn.old.age.int` (the first includes the field name and the second includes the type
of the field). This is done as a convenience to aid developers when targeting error messages.
More information on the `MessageCodesResolver` and the default strategy can be found
in the javadoc of
@@ -259,8 +259,8 @@ object. The following table shows some examples of these conventions:
(This next section is not vitally important to you if you do not plan to work with
the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory`
and their default implementations, you should skip ahead to the <<beans-beans-conversion,section about
`PropertyEditors`>>.)
and their default implementations, you should skip ahead to the
<<beans-beans-conversion, section on `PropertyEditors`>>.)
The following two example classes use the `BeanWrapper` to get and set
properties:
@@ -537,17 +537,17 @@ where it can be automatically detected and applied.
Note that all bean factories and application contexts automatically use a number of
built-in property editors, through their use a `BeanWrapper` to
handle property conversions. The standard property editors that the `BeanWrapper`
registers are listed in <<beans-beans-conversion,the previous section>>. Additionally,
`ApplicationContexts` also override or add additional editors to handle
registers are listed in the <<beans-beans-conversion, previous section>>.
Additionally, `ApplicationContexts` also override or add additional editors to handle
resource lookups in a manner appropriate to the specific application context type.
Standard JavaBeans `PropertyEditor` instances are used to convert property values
expressed as strings to the actual complex type of the property.
You can use `CustomEditorConfigurer`, a bean factory post-processor, to conveniently add
expressed as strings to the actual complex type of the property. You can use
`CustomEditorConfigurer`, a bean factory post-processor, to conveniently add
support for additional `PropertyEditor` instances to an `ApplicationContext`.
Consider the following example, which defines a user class called `ExoticType` and another class called `DependsOnExoticType`, which needs
`ExoticType` set as a property:
Consider the following example, which defines a user class called `ExoticType` and
another class called `DependsOnExoticType`, which needs `ExoticType` set as a property:
====
[source,java,indent=0]
@@ -629,14 +629,15 @@ Finally, the following example shows how to use `CustomEditorConfigurer` to regi
Another mechanism for registering property editors with the Spring container is to
create and use a `PropertyEditorRegistrar`. This interface is particularly useful when
you need to use the same set of property editors in several different situations. You can write
a corresponding registrar and reuse it in each case. `PropertyEditorRegistrar` instances work
in conjunction with an interface called `PropertyEditorRegistry`, an interface that is
implemented by the Spring `BeanWrapper` (and `DataBinder`). `PropertyEditorRegistrar` instances
are particularly convenient when used in conjunction with `CustomEditorConfigurer`
(described <<beans-beans-conversion-customeditor-registration,here>>), which exposes a
property called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added to a
`CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and
you need to use the same set of property editors in several different situations.
You can write a corresponding registrar and reuse it in each case.
`PropertyEditorRegistrar` instances work in conjunction with an interface called
`PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper`
(and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient
when used in conjunction with `CustomEditorConfigurer` (described
<<beans-beans-conversion-customeditor-registration, here>>), which exposes a property
called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added
to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and
Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom
editors: A `PropertyEditorRegistrar` is expected to create fresh `PropertyEditor`
instances for each bean creation attempt.
@@ -687,7 +688,7 @@ The next example shows how to configure a `CustomEditorConfigurer` and inject an
====
Finally (and in a bit of a departure from the focus of this chapter for those of you
using <<web.adoc#mvc,Spring's MVC web framework>>), using `PropertyEditorRegistrars` in
using <<web.adoc#mvc, Spring's MVC web framework>>), using `PropertyEditorRegistrars` in
conjunction with data-binding `Controllers` (such as `SimpleFormController`) can be very
convenient. The following example uses a `PropertyEditorRegistrar` in the
implementation of an `initBinder(..)` method:
@@ -1002,8 +1003,7 @@ It is also common to use a `ConversionService` within a Spring MVC application.
<<web.adoc#mvc-config-conversion, Conversion and Formatting>> in the Spring MVC chapter.
In certain situations, you may wish to apply formatting during conversion. See
<<format-FormatterRegistry-SPI>> for details on using
`FormattingConversionServiceFactoryBean`.
<<format-FormatterRegistry-SPI>> for details on using `FormattingConversionServiceFactoryBean`.