diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 4df6bbf5210..5ba8c60b945 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -3495,6 +3495,29 @@ The preceding example has almost exactly the same effect as the following exampl However, the first of the two preceding examples does not couple the code to Spring. +[NOTE] +==== +Be aware that `@PostConstruct` and initialization methods in general are executed +within the container's singleton creation lock. The bean instance is only considered +as fully initialized and ready to be published to others after returning from the +`@PostConstruct` method. Such individual initialization methods are only meant +for validating the configuration state and possibly preparing some data structures +based on the given configuration but no further activity with external bean access. +Otherwise there is a risk for an initialization deadlock. + +For a scenario where expensive post-initialization activity is to be triggered, +e.g. asynchronous database preparation steps, your bean should either implement +`SmartInitializingSingleton.afterSingletonsInstantiated()` or rely on the context +refresh event: implementing `ApplicationListener` or +declaring its annotation equivalent `@EventListener(ContextRefreshedEvent.class)`. +Those variants come after all regular singleton initialization and therefore +outside of any singleton creation lock. + +Alternatively, you may implement the `(Smart)Lifecycle` interface and integrate with +the container's overall lifecycle management, including an auto-startup mechanism, +a pre-destroy stop step, and potential stop/restart callbacks (see below). +==== + [[beans-factory-lifecycle-disposablebean]] ==== Destruction Callbacks @@ -3574,28 +3597,37 @@ The preceding definition has almost exactly the same effect as the following def However, the first of the two preceding definitions does not couple the code to Spring. TIP: You can assign the `destroy-method` attribute of a `` element a special -`(inferred)` value, which instructs Spring to automatically detect a public `close` or -`shutdown` method on the specific bean class. (Any class that implements -`java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also set -this special `(inferred)` value on the `default-destroy-method` attribute of a +`(inferred)` value, which instructs Spring to automatically detect a public `close` +or `shutdown` method on the specific bean class. (Any class that implements +`java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also +set this special `(inferred)` value on the `default-destroy-method` attribute of a `` element to apply this behavior to an entire set of beans (see <>). Note that this is the -default behavior with Java configuration. +default behavior for `@Bean` methods in Java configuration classes. + +[NOTE] +==== +For extended shutdown phases, you may implement the `Lifecycle` interface and receive +an early stop signal before the destroy methods of any singleton beans are called. +You may also implement `SmartLifecycle` for a time-bound stop step where the container +will wait for all such stop processing to complete before moving on to destroy methods. +==== + [[beans-factory-lifecycle-default-init-destroy-methods]] ==== Default Initialization and Destroy Methods When you write initialization and destroy method callbacks that do not use the Spring-specific `InitializingBean` and `DisposableBean` callback interfaces, you -typically write methods with names such as `init()`, `initialize()`, `dispose()`, and so -on. Ideally, the names of such lifecycle callback methods are standardized across a -project so that all developers use the same method names and ensure consistency. +typically write methods with names such as `init()`, `initialize()`, `dispose()`, +and so on. Ideally, the names of such lifecycle callback methods are standardized across +a project so that all developers use the same method names and ensure consistency. You can configure the Spring container to "`look`" for named initialization and destroy -callback method names on every bean. This means that you, as an application -developer, can write your application classes and use an initialization callback called -`init()`, without having to configure an `init-method="init"` attribute with each bean -definition. The Spring IoC container calls that method when the bean is created (and in +callback method names on every bean. This means that you, as an application developer, +can write your application classes and use an initialization callback called `init()`, +without having to configure an `init-method="init"` attribute with each bean definition. +The Spring IoC container calls that method when the bean is created (and in accordance with the standard lifecycle callback contract <>). This feature also enforces a consistent naming convention for initialization and destroy method callbacks. @@ -3677,7 +3709,6 @@ target bean to its proxy or interceptors and leave strange semantics when your c interacts directly with the raw target bean. - [[beans-factory-lifecycle-combined-effects]] ==== Combining Lifecycle Mechanisms @@ -3710,7 +3741,6 @@ Destroy methods are called in the same order: . A custom configured `destroy()` method - [[beans-factory-lifecycle-processor]] ==== Startup and Shutdown Callbacks @@ -3752,14 +3782,15 @@ and closed. [TIP] ==== Note that the regular `org.springframework.context.Lifecycle` interface is a plain -contract for explicit start and stop notifications and does not imply auto-startup at context -refresh time. For fine-grained control over auto-startup of a specific bean (including startup phases), -consider implementing `org.springframework.context.SmartLifecycle` instead. +contract for explicit start and stop notifications and does not imply auto-startup +at context refresh time. For fine-grained control over auto-startup and for graceful +stopping of a specific bean (including startup and stop phases), consider implementing +the extended `org.springframework.context.SmartLifecycle` interface instead. Also, please note that stop notifications are not guaranteed to come before destruction. On regular shutdown, all `Lifecycle` beans first receive a stop notification before -the general destruction callbacks are being propagated. However, on hot refresh during a -context's lifetime or on stopped refresh attempts, only destroy methods are called. +the general destruction callbacks are being propagated. However, on hot refresh during +a context's lifetime or on stopped refresh attempts, only destroy methods are called. ==== The order of startup and shutdown invocations can be important. If a "`depends-on`" @@ -3833,7 +3864,6 @@ automatically for a standard context implementation). The `phase` value and any "`depends-on`" relationships determine the startup order as described earlier. - [[beans-factory-shutdown]] ==== Shutting Down the Spring IoC Container Gracefully in Non-Web Applications