Can be implemented by both components (typically a Spring bean defined in - * a Spring {@link org.springframework.beans.factory.BeanFactory}) and containers - * (typically a Spring {@link ApplicationContext}). Containers will propagate - * start/stop signals to all components that apply. + *
Can be implemented by both components (typically a Spring bean defined in a + * Spring context) and containers (typically a Spring {@link ApplicationContext} + * itself). Containers will propagate start/stop signals to all components that + * apply within each container, e.g. for a stop/restart scenario at runtime. * *
Can be used for direct invocations or for management operations via JMX. * In the latter case, the {@link org.springframework.jmx.export.MBeanExporter} @@ -32,10 +34,10 @@ package org.springframework.context; * restricting the visibility of activity-controlled components to the Lifecycle * interface. * - *
Note that the Lifecycle interface is only supported on top-level singleton beans. - * On any other component, the Lifecycle interface will remain undetected and hence ignored. - * Also, note that the extended {@link SmartLifecycle} interface provides more sophisticated - * integration with the container's startup and shutdown phases. + *
Note that the Lifecycle interface is only supported on top-level singleton + * beans. On any other component, the Lifecycle interface will remain undetected + * and hence ignored. Also, note that the extended {@link SmartLifecycle} interface + * provides integration with the application context's startup and shutdown phases. * * @author Juergen Hoeller * @since 2.0 @@ -51,6 +53,7 @@ public interface Lifecycle { * Should not throw an exception if the component is already running. *
In the case of a container, this will propagate the start signal * to all components that apply. + * @see SmartLifecycle#isAutoStartup() */ void start(); diff --git a/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java b/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java index ffd4c92cb93..1ae2c12e9de 100644 --- a/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java +++ b/spring-context/src/main/java/org/springframework/context/SmartLifecycle.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2015 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. @@ -17,8 +17,8 @@ package org.springframework.context; /** - * An extension of the {@link Lifecycle} interface for those objects that require to be - * started upon ApplicationContext refresh and/or shutdown in a particular order. + * An extension of the {@link Lifecycle} interface for those objects that require to + * be started upon ApplicationContext refresh and/or shutdown in a particular order. * The {@link #isAutoStartup()} return value indicates whether this object should * be started at the time of a context refresh. The callback-accepting * {@link #stop(Runnable)} method is useful for objects that have an asynchronous @@ -55,26 +55,37 @@ package org.springframework.context; * * @author Mark Fisher * @since 3.0 + * @see LifecycleProcessor + * @see ConfigurableApplicationContext */ public interface SmartLifecycle extends Lifecycle, Phased { /** - * Return whether this Lifecycle component should be started automatically - * by the container when the ApplicationContext is refreshed. A value of - * "false" indicates that the component is intended to be started manually. + * Returns {@code true} if this {@code Lifecycle} component should get + * started automatically by the container at the time that the containing + * {@link ApplicationContext} gets refreshed. + *
A value of {@code false} indicates that the component is intended to + * be started through an explicit {@link #start()} call instead, analogous + * to a plain {@link Lifecycle} implementation. + * @see #start() + * @see #getPhase() + * @see LifecycleProcessor#onRefresh() + * @see ConfigurableApplicationContext#refresh() */ boolean isAutoStartup(); /** * Indicates that a Lifecycle component must stop if it is currently running. - *
The provided callback is used by the {@link LifecycleProcessor} to support an - * ordered, and potentially concurrent, shutdown of all components having a + *
The provided callback is used by the {@link LifecycleProcessor} to support + * an ordered, and potentially concurrent, shutdown of all components having a * common shutdown order value. The callback must be executed after - * the SmartLifecycle component does indeed stop. - *
The {@code LifecycleProcessor} will call only this variant of the + * the {@code SmartLifecycle} component does indeed stop. + *
The {@link LifecycleProcessor} will call only this variant of the * {@code stop} method; i.e. {@link Lifecycle#stop()} will not be called for - * {@link SmartLifecycle} implementations unless explicitly delegated to within - * this method. + * {@code SmartLifecycle} implementations unless explicitly delegated to within + * the implementation of this method. + * @see #stop() + * @see #getPhase() */ void stop(Runnable callback); diff --git a/src/asciidoc/core-beans.adoc b/src/asciidoc/core-beans.adoc index 4b016f2ba54..3b209317ad9 100644 --- a/src/asciidoc/core-beans.adoc +++ b/src/asciidoc/core-beans.adoc @@ -3093,9 +3093,9 @@ lifecycle requirements (e.g. starts and stops some background process): ---- Any Spring-managed object may implement that interface. Then, when the -`ApplicationContext` itself starts and stops, it will cascade those calls to all `Lifecycle` -implementations defined within that context. It does this by delegating to a -`LifecycleProcessor`: +`ApplicationContext` itself receives start and stop signals, e.g. for a stop/restart +scenario at runtime, it will cascade those calls to all `Lifecycle` implementations +defined within that context. It does this by delegating to a `LifecycleProcessor`: [source,java,indent=0] [subs="verbatim,quotes"] @@ -3113,6 +3113,14 @@ 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 and closed. +[TIP] +==== +Note that the regular `org.springframework.context.Lifecycle` interface is just a plain +contract for explicit start/stop notifications and does NOT imply auto-startup at context +refresh time. Consider implementing `org.springframework.context.SmartLifecycle` instead +for fine-grained control over auto-startup of a specific bean (including startup phases). +==== + The order of startup and shutdown invocations can be important. If a "depends-on" relationship exists between any two objects, the dependent side will start __after__ its dependency, and it will stop __before__ its dependency. However, at times the direct