diff --git a/spring-orm/src/test/java/org/springframework/orm/jpa/AbstractContainerEntityManagerFactoryIntegrationTests.java b/spring-orm/src/test/java/org/springframework/orm/jpa/AbstractContainerEntityManagerFactoryIntegrationTests.java index 15c27ccc5f0..8885d6eb7e0 100644 --- a/spring-orm/src/test/java/org/springframework/orm/jpa/AbstractContainerEntityManagerFactoryIntegrationTests.java +++ b/spring-orm/src/test/java/org/springframework/orm/jpa/AbstractContainerEntityManagerFactoryIntegrationTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2019 the original author or authors. + * Copyright 2002-2021 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -224,8 +224,7 @@ public abstract class AbstractContainerEntityManagerFactoryIntegrationTests q.setFlushMode(FlushModeType.AUTO); List people = q.getResultList(); assertThat(people.size()).isEqualTo(0); - assertThatExceptionOfType(Exception.class).isThrownBy(() -> - q.getSingleResult()) + assertThatExceptionOfType(Exception.class).isThrownBy(q::getSingleResult) .withMessageContaining("closed"); // We would typically expect an IllegalStateException, but Hibernate throws a // PersistenceException. So we assert the contents of the exception message instead. diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdvice.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdvice.java index c8c7bc4c742..a50872583b8 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdvice.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdvice.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 the original author or authors. + * Copyright 2002-2021 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -57,7 +57,7 @@ public interface RequestBodyAdvice { * @param targetType the target type, not necessarily the same as the method * parameter type, e.g. for {@code HttpEntity}. * @param converterType the converter used to deserialize the body - * @return the input request or a new instance, never {@code null} + * @return the input request or a new instance (never {@code null}) */ HttpInputMessage beforeBodyRead(HttpInputMessage inputMessage, MethodParameter parameter, Type targetType, Class> converterType) throws IOException; @@ -83,8 +83,8 @@ public interface RequestBodyAdvice { * @param targetType the target type, not necessarily the same as the method * parameter type, e.g. for {@code HttpEntity}. * @param converterType the selected converter type - * @return the value to use or {@code null} which may then raise an - * {@code HttpMessageNotReadableException} if the argument is required. + * @return the value to use, or {@code null} which may then raise an + * {@code HttpMessageNotReadableException} if the argument is required */ @Nullable Object handleEmptyBody(@Nullable Object body, HttpInputMessage inputMessage, MethodParameter parameter, diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdviceAdapter.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdviceAdapter.java index 0e8ade00d8c..cdb68a7975a 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdviceAdapter.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestBodyAdviceAdapter.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2015 the original author or authors. + * Copyright 2002-2021 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -13,6 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + package org.springframework.web.servlet.mvc.method.annotation; import java.io.IOException; @@ -25,10 +26,10 @@ import org.springframework.lang.Nullable; /** * A convenient starting point for implementing - * {@link org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice - * ResponseBodyAdvice} with default method implementations. + * {@link org.springframework.web.servlet.mvc.method.annotation.RequestBodyAdvice + * RequestBodyAdvice} with default method implementations. * - *

Sub-classes are required to implement {@link #supports} to return true + *

Subclasses are required to implement {@link #supports} to return true * depending on when the advice applies. * * @author Rossen Stoyanchev @@ -41,8 +42,7 @@ public abstract class RequestBodyAdviceAdapter implements RequestBodyAdvice { */ @Override public HttpInputMessage beforeBodyRead(HttpInputMessage inputMessage, MethodParameter parameter, - Type targetType, Class> converterType) - throws IOException { + Type targetType, Class> converterType) throws IOException { return inputMessage; } @@ -62,9 +62,8 @@ public abstract class RequestBodyAdviceAdapter implements RequestBodyAdvice { */ @Override @Nullable - public Object handleEmptyBody(@Nullable Object body, HttpInputMessage inputMessage, - MethodParameter parameter, Type targetType, - Class> converterType) { + public Object handleEmptyBody(@Nullable Object body, HttpInputMessage inputMessage, MethodParameter parameter, + Type targetType, Class> converterType) { return body; } diff --git a/src/docs/asciidoc/core/core-appendix.adoc b/src/docs/asciidoc/core/core-appendix.adoc index 67b078e3b9f..6205a417387 100644 --- a/src/docs/asciidoc/core/core-appendix.adoc +++ b/src/docs/asciidoc/core/core-appendix.adoc @@ -568,8 +568,9 @@ is a convenience mechanism that sets up a <> model -* <> and `@Value` -* JSR-250's `@Resource`, `@PostConstruct` and `@PreDestroy` (if available) +* <>, `@Value`, and `@Lookup` +* JSR-250's `@Resource`, `@PostConstruct`, and `@PreDestroy` (if available) +* JAX-WS's `@WebServiceRef` and EJB 3's `@EJB` (if available) * JPA's `@PersistenceContext` and `@PersistenceUnit` (if available) * Spring's <> @@ -682,8 +683,7 @@ XML extension (a custom XML element) that lets us configure objects of the type `SimpleDateFormat` (from the `java.text` package). When we are done, we will be able to define bean definitions of type `SimpleDateFormat` as follows: -[source,xml,indent=0] -[subs="verbatim,quotes"] +[source,xml,indent=0,subs="verbatim,quotes"] ---- >. The following example shows the basic structure of XML-based configuration metadata: -[source,xml,indent=0] -[subs="verbatim,quotes"] +[source,xml,indent=0,subs="verbatim,quotes"] ---- ` -element. +Assuming that the `ThingTwo` and `ThingThree` classes are not related by inheritance, no +potential ambiguity exists. Thus, the following configuration works fine, and you do not +need to specify the constructor argument indexes or types explicitly in the +`` element. [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -1008,10 +1006,10 @@ by type without help. Consider the following class: public class ExampleBean { // Number of years to calculate the Ultimate Answer - private int years; + private final int years; // The Answer to Life, the Universe, and Everything - private String ultimateAnswer; + private final String ultimateAnswer; public ExampleBean(int years, String ultimateAnswer) { this.years = years; @@ -1033,7 +1031,7 @@ by type without help. Consider the following class: .[[beans-factory-ctor-arguments-type]]Constructor argument type matching -- In the preceding scenario, the container can use type matching with simple types if -you explicitly specify the type of the constructor argument by using the `type` attribute. +you explicitly specify the type of the constructor argument by using the `type` attribute, as the following example shows: [source,xml,indent=0,subs="verbatim,quotes"] @@ -1253,7 +1251,8 @@ visibility of some configuration issues is why `ApplicationContext` implementati default pre-instantiate singleton beans. At the cost of some upfront time and memory to create these beans before they are actually needed, you discover configuration issues when the `ApplicationContext` is created, not later. You can still override this default -behavior so that singleton beans initialize lazily, rather than being pre-instantiated. +behavior so that singleton beans initialize lazily, rather than being eagerly +pre-instantiated. If no circular dependencies exist, when one or more collaborating beans are being injected into a dependent bean, each collaborating bean is totally configured prior @@ -1980,8 +1979,7 @@ then nested `constructor-arg` elements. The following example uses the `c:` namespace to do the same thing as the from <>: -[source,xml,indent=0] -[subs="verbatim,quotes"] +[source,xml,indent=0,subs="verbatim,quotes"] ---- >. Consider the following example: -[source,xml,indent=0] -[subs="verbatim,quotes"] +[source,xml,indent=0,subs="verbatim,quotes"] ---- ---- @@ -3495,16 +3486,10 @@ Implementing the `org.springframework.beans.factory.DisposableBean` interface le bean get a callback when the container that contains it is destroyed. The `DisposableBean` interface specifies a single method: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- void destroy() throws Exception; ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - fun destroy() ----- We recommend that you do not use the `DisposableBean` callback interface, because it unnecessarily couples the code to Spring. Alternatively, we suggest using @@ -3715,8 +3700,7 @@ Destroy methods are called in the same order: The `Lifecycle` interface defines the essential methods for any object that has its own lifecycle requirements (such as starting and stopping some background process): -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- public interface Lifecycle { @@ -3727,18 +3711,6 @@ lifecycle requirements (such as starting and stopping some background process): boolean isRunning(); } ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface Lifecycle { - - fun start() - - fun stop() - - val isRunning: Boolean - } ----- Any Spring-managed object may implement the `Lifecycle` interface. Then, when the `ApplicationContext` itself receives start and stop signals (for example, for a stop/restart @@ -3746,8 +3718,7 @@ scenario at runtime), it cascades those calls to all `Lifecycle` implementations defined within that context. It does this by delegating to a `LifecycleProcessor`, shown in the following listing: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- public interface LifecycleProcessor extends Lifecycle { @@ -3756,16 +3727,6 @@ in the following listing: void onClose(); } ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface LifecycleProcessor : Lifecycle { - - fun onRefresh() - - fun onClose() - } ----- Notice that the `LifecycleProcessor` is itself an extension of the `Lifecycle` interface. It also adds two other methods for reacting to the context being refreshed @@ -3792,27 +3753,17 @@ prior to objects of another type. In those cases, the `SmartLifecycle` interface another option, namely the `getPhase()` method as defined on its super-interface, `Phased`. The following listing shows the definition of the `Phased` interface: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- public interface Phased { int getPhase(); } ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface Phased { - - val phase: Int - } ----- The following listing shows the definition of the `SmartLifecycle` interface: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- public interface SmartLifecycle extends Lifecycle, Phased { @@ -3821,16 +3772,6 @@ The following listing shows the definition of the `SmartLifecycle` interface: void stop(Runnable callback); } ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface SmartLifecycle : Lifecycle, Phased { - - val isAutoStartup: Boolean - - fun stop(callback: Runnable) - } ----- When starting, the objects with the lowest phase start first. When stopping, the reverse order is followed. Therefore, an object that implements `SmartLifecycle` and @@ -3942,23 +3883,13 @@ When an `ApplicationContext` creates an object instance that implements the with a reference to that `ApplicationContext`. The following listing shows the definition of the `ApplicationContextAware` interface: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- public interface ApplicationContextAware { void setApplicationContext(ApplicationContext applicationContext) throws BeansException; } ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface ApplicationContextAware { - - @Throws(BeansException::class) - fun setApplicationContext(applicationContext: ApplicationContext) - } ----- Thus, beans can programmatically manipulate the `ApplicationContext` that created them, through the `ApplicationContext` interface or by casting the reference to a known @@ -3987,23 +3918,13 @@ When an `ApplicationContext` creates a class that implements the a reference to the name defined in its associated object definition. The following listing shows the definition of the BeanNameAware interface: -[source,java,indent=0,subs="verbatim,quotes",role="primary"] -.Java +[source,java,indent=0,subs="verbatim,quotes"] ---- public interface BeanNameAware { void setBeanName(String name) throws BeansException; } ---- -[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] -.Kotlin ----- - interface BeanNameAware { - - @Throws(BeansException::class) - fun setBeanName(name: String) - } ----- The callback is invoked after population of normal bean properties but before an initialization callback such as `InitializingBean`, `afterPropertiesSet`, or a custom @@ -4401,15 +4322,14 @@ org.springframework.scripting.groovy.GroovyMessenger@272961 ---- -[[beans-factory-extension-bpp-examples-rabpp]] -==== Example: The `RequiredAnnotationBeanPostProcessor` +[[beans-factory-extension-bpp-examples-aabpp]] +==== Example: The `AutowiredAnnotationBeanPostProcessor` -Using callback interfaces or annotations in conjunction with a custom -`BeanPostProcessor` implementation is a common means of extending the Spring IoC -container. An example is Spring's `RequiredAnnotationBeanPostProcessor` -- a -`BeanPostProcessor` implementation that ships with the Spring distribution and that ensures -that JavaBean properties on beans that are marked with an (arbitrary) annotation are -actually (configured to be) dependency-injected with a value. +Using callback interfaces or annotations in conjunction with a custom `BeanPostProcessor` +implementation is a common means of extending the Spring IoC container. An example is +Spring's `AutowiredAnnotationBeanPostProcessor` -- a `BeanPostProcessor` implementation +that ships with the Spring distribution and autowires annotated fields, setter methods, +and arbitrary config methods. @@ -4673,7 +4593,7 @@ An alternative to XML setup is provided by annotation-based configuration, which 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 <>, using +field declaration. As mentioned in <>, using a `BeanPostProcessor` in conjunction with annotations is a common means of extending the Spring IoC container. For example, Spring 2.0 introduced the possibility of enforcing required properties with the <> annotation. Spring @@ -4692,8 +4612,8 @@ Annotation injection is performed before XML injection. Thus, the XML configurat overrides the annotations for properties wired through both approaches. ==== -As always, you can register them as individual bean definitions, but they can also be -implicitly registered by including the following tag in an XML-based Spring +As always, you can register the post-processors as individual bean definitions, but they +can also be implicitly registered by including the following tag in an XML-based Spring configuration (notice the inclusion of the `context` namespace): [source,xml,indent=0,subs="verbatim,quotes"] @@ -4712,12 +4632,13 @@ configuration (notice the inclusion of the `context` namespace): ---- -(The implicitly registered post-processors include -{api-spring-framework}/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.html[`AutowiredAnnotationBeanPostProcessor`], -{api-spring-framework}/context/annotation/CommonAnnotationBeanPostProcessor.html[`CommonAnnotationBeanPostProcessor`], -{api-spring-framework}/orm/jpa/support/PersistenceAnnotationBeanPostProcessor.html[`PersistenceAnnotationBeanPostProcessor`], -and the aforementioned -{api-spring-framework}/beans/factory/annotation/RequiredAnnotationBeanPostProcessor.html[`RequiredAnnotationBeanPostProcessor`].) +The `` element implicitly registers the following post-processors: + +* {api-spring-framework}/context/annotation/ConfigurationClassPostProcessor.html[`ConfigurationClassPostProcessor`] +* {api-spring-framework}/beans/factory/annotation/AutowiredAnnotationBeanPostProcessor.html[`AutowiredAnnotationBeanPostProcessor`] +* {api-spring-framework}/context/annotation/CommonAnnotationBeanPostProcessor.html[`CommonAnnotationBeanPostProcessor`] +* {api-spring-framework}/orm/jpa/support/PersistenceAnnotationBeanPostProcessor.html[`PersistenceAnnotationBeanPostProcessor`] +* {api-spring-framework}/context/event/EventListenerMethodProcessor.html[`EventListenerMethodProcessor`] [NOTE] ==== @@ -4763,7 +4684,6 @@ example: } ---- - This annotation indicates that the affected bean property must be populated at configuration time, through an explicit property value in a bean definition or through autowiring. The container throws an exception if the affected bean property has not been @@ -4772,11 +4692,18 @@ instances or the like later on. We still recommend that you put assertions into bean class itself (for example, into an init method). Doing so enforces those required references and values even when you use the class outside of a container. +[TIP] +==== +The {api-spring-framework}/beans/factory/annotation/RequiredAnnotationBeanPostProcessor.html[`RequiredAnnotationBeanPostProcessor`] +must be registered as a bean to enable support for the `@Required` annotation. +==== + [NOTE] ==== -The `@Required` annotation is formally deprecated as of Spring Framework 5.1, in favor -of using constructor injection for required settings (or a custom implementation of -`InitializingBean.afterPropertiesSet()` along with bean property setter methods). +The `@Required` annotation and `RequiredAnnotationBeanPostProcessor` are formally +deprecated as of Spring Framework 5.1, in favor of using constructor injection for +required settings (or a custom implementation of `InitializingBean.afterPropertiesSet()` +or a custom `@PostConstruct` method along with bean property setter methods). ==== @@ -5001,6 +4928,7 @@ The same applies for typed collections, as the following example shows: } ---- +[[beans-factory-ordered]] [TIP] ==== Your target beans can implement the `org.springframework.core.Ordered` interface or use @@ -7197,10 +7125,10 @@ metadata is provided per-instance rather than per-class. While classpath scanning is very fast, it is possible to improve the startup performance of large applications by creating a static list of candidates at compilation time. In this -mode, all modules that are target of component scan must use this mechanism. +mode, all modules that are targets of component scanning must use this mechanism. -NOTE: Your existing `@ComponentScan` or `` directives must remain +unchanged to request the context to scan candidates in certain packages. When the `ApplicationContext` detects such an index, it automatically uses it rather than scanning the classpath. @@ -7229,12 +7157,10 @@ configuration, as shown in the following example: compileOnly "org.springframework:spring-context-indexer:{spring-version}" } ---- -==== With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example: -==== [source,groovy,indent=0subs="verbatim,quotes,attributes"] ---- dependencies { @@ -7242,19 +7168,20 @@ configuration, as shown in the following example: } ---- -That process generates a `META-INF/spring.components` file that is -included in the jar file. +The `spring-context-indexer` artifact generates a `META-INF/spring.components` file that +is included in the jar file. NOTE: When working with this mode in your IDE, the `spring-context-indexer` must be registered as an annotation processor to make sure the index is up-to-date when candidate components are updated. -TIP: The index is enabled automatically when a `META-INF/spring.components` is found +TIP: The index is enabled automatically when a `META-INF/spring.components` file is found on the classpath. If an index is partially available for some libraries (or use cases) -but could not be built for the whole application, you can fallback to a regular classpath -arrangement (as though no index was present at all) by setting `spring.index.ignore` to -`true`, either as a system property or in a `spring.properties` file at the root of the -classpath. +but could not be built for the whole application, you can fall back to a regular classpath +arrangement (as though no index were present at all) by setting `spring.index.ignore` to +`true`, either as a JVM system property or in a `spring.properties` file at the root of +the classpath. + @@ -7857,8 +7784,7 @@ To enable component scanning, you can annotate your `@Configuration` class as fo Experienced Spring users may be familiar with the XML declaration equivalent from Spring's `context:` namespace, shown in the following example: -[source,xml,indent=0] -[subs="verbatim,quotes"] +[source,xml,indent=0,subs="verbatim,quotes"] ----