Clarification: Lifecycle does not imply auto-startup semantics

Issue: SPR-12855

spring-context/src/main/java/org/springframework/context/Lifecycle.java

 /*
- * Copyright 2002-2012 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,13 +17,15 @@
 package org.springframework.context;
 
 /**
- * Interface defining methods for start/stop lifecycle control.
+ * A common interface defining methods for start/stop lifecycle control.
  * The typical use case for this is to control asynchronous processing.
+ * <b>NOTE: This interface does not imply specific auto-startup semantics.
+ * Consider implementing {@link SmartLifecycle} for that purpose.</b>
  *
- * <p>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.
+ * <p>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.
  *
  * <p>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.
  *
- * <p>Note that the Lifecycle interface is only supported on <b>top-level singleton beans</b>.
- * 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.
+ * <p>Note that the Lifecycle interface is only supported on <b>top-level singleton
+ * beans</b>. 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.
 	 * <p>In the case of a container, this will propagate the start signal
 	 * to all components that apply.
+	 * @see SmartLifecycle#isAutoStartup()
 	 */
 	void start();
 

spring-context/src/main/java/org/springframework/context/SmartLifecycle.java

 /*
- * 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.
+	 * <p>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.
-	 * <p>The provided callback is used by the {@link LifecycleProcessor} to support an
-	 * ordered, and potentially concurrent, shutdown of all components having a
+	 * <p>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 <b>must</b> be executed after
-	 * the SmartLifecycle component does indeed stop.
-	 * <p>The {@code LifecycleProcessor} will call <i>only</i> this variant of the
+	 * the {@code SmartLifecycle} component does indeed stop.
+	 * <p>The {@link LifecycleProcessor} will call <i>only</i> 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);
 

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