001/*
002 * Copyright 2002-2018 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.context;
018
019/**
020 * An extension of the {@link Lifecycle} interface for those objects that require to
021 * be started upon ApplicationContext refresh and/or shutdown in a particular order.
022 * The {@link #isAutoStartup()} return value indicates whether this object should
023 * be started at the time of a context refresh. The callback-accepting
024 * {@link #stop(Runnable)} method is useful for objects that have an asynchronous
025 * shutdown process. Any implementation of this interface <i>must</i> invoke the
026 * callback's {@code run()} method upon shutdown completion to avoid unnecessary
027 * delays in the overall ApplicationContext shutdown.
028 *
029 * <p>This interface extends {@link Phased}, and the {@link #getPhase()} method's
030 * return value indicates the phase within which this Lifecycle component should
031 * be started and stopped. The startup process begins with the <i>lowest</i> phase
032 * value and ends with the <i>highest</i> phase value ({@code Integer.MIN_VALUE}
033 * is the lowest possible, and {@code Integer.MAX_VALUE} is the highest possible).
034 * The shutdown process will apply the reverse order. Any components with the
035 * same value will be arbitrarily ordered within the same phase.
036 *
037 * <p>Example: if component B depends on component A having already started,
038 * then component A should have a lower phase value than component B. During
039 * the shutdown process, component B would be stopped before component A.
040 *
041 * <p>Any explicit "depends-on" relationship will take precedence over the phase
042 * order such that the dependent bean always starts after its dependency and
043 * always stops before its dependency.
044 *
045 * <p>Any {@code Lifecycle} components within the context that do not also
046 * implement {@code SmartLifecycle} will be treated as if they have a phase
047 * value of 0. That way a {@code SmartLifecycle} implementation may start
048 * before those {@code Lifecycle} components if it has a negative phase value,
049 * or it may start after those components if it has a positive phase value.
050 *
051 * <p>Note that, due to the auto-startup support in {@code SmartLifecycle}, a
052 * {@code SmartLifecycle} bean instance will usually get initialized on startup
053 * of the application context in any case. As a consequence, the bean definition
054 * lazy-init flag has very limited actual effect on {@code SmartLifecycle} beans.
055 *
056 * @author Mark Fisher
057 * @since 3.0
058 * @see LifecycleProcessor
059 * @see ConfigurableApplicationContext
060 */
061public interface SmartLifecycle extends Lifecycle, Phased {
062
063        /**
064         * Returns {@code true} if this {@code Lifecycle} component should get
065         * started automatically by the container at the time that the containing
066         * {@link ApplicationContext} gets refreshed.
067         * <p>A value of {@code false} indicates that the component is intended to
068         * be started through an explicit {@link #start()} call instead, analogous
069         * to a plain {@link Lifecycle} implementation.
070         * @see #start()
071         * @see #getPhase()
072         * @see LifecycleProcessor#onRefresh()
073         * @see ConfigurableApplicationContext#refresh()
074         */
075        boolean isAutoStartup();
076
077        /**
078         * Indicates that a Lifecycle component must stop if it is currently running.
079         * <p>The provided callback is used by the {@link LifecycleProcessor} to support
080         * an ordered, and potentially concurrent, shutdown of all components having a
081         * common shutdown order value. The callback <b>must</b> be executed after
082         * the {@code SmartLifecycle} component does indeed stop.
083         * <p>The {@link LifecycleProcessor} will call <i>only</i> this variant of the
084         * {@code stop} method; i.e. {@link Lifecycle#stop()} will not be called for
085         * {@code SmartLifecycle} implementations unless explicitly delegated to within
086         * the implementation of this method.
087         * @see #stop()
088         * @see #getPhase()
089         */
090        void stop(Runnable callback);
091
092}