    001    /*
    002     * Copyright (C) 2009 The Guava 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     * http://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
    017    package com.google.common.util.concurrent;
    018
    019    import com.google.common.annotations.Beta;
    020
    021    import java.util.concurrent.ExecutionException;
    022    import java.util.concurrent.Executor;
    023
    024    /**
    025     * An object with an operational state, plus asynchronous {@link #start()} and {@link #stop()}
    026     * lifecycle methods to transition between states. Example services include webservers, RPC servers
    027     * and timers.
    028     *
    029     * <p>The normal lifecycle of a service is:
    030     * <ul>
    031     *   <li>{@linkplain State#NEW NEW} -&gt;
    032     *   <li>{@linkplain State#STARTING STARTING} -&gt;
    033     *   <li>{@linkplain State#RUNNING RUNNING} -&gt;
    034     *   <li>{@linkplain State#STOPPING STOPPING} -&gt;
    035     *   <li>{@linkplain State#TERMINATED TERMINATED}
    036     * </ul>
    037     *
    038     * <p>There are deviations from this if there are failures or if {@link Service#stop} is called
    039     * before the {@link Service} reaches the {@linkplain State#RUNNING RUNNING} state. The set of legal
    040     * transitions form a <a href="http://en.wikipedia.org/wiki/Directed_acyclic_graph">DAG</a>,
    041     * therefore every method of the listener will be called at most once. N.B. The {@link State#FAILED}
    042     * and {@link State#TERMINATED} states are terminal states, once a service enters either of these
    043     * states it cannot ever leave them.
    044     *
    045     * <p>Implementors of this interface are strongly encouraged to extend one of the abstract classes
    046     * in this package which implement this interface and make the threading and state management
    047     * easier.
    048     *
    049     * @author Jesse Wilson
    050     * @author Luke Sandberg
    051     * @since 9.0 (in 1.0 as {@code com.google.common.base.Service})
    052     */
    053    @Beta
    054    public interface Service {
    055      /**
    056       * If the service state is {@link State#NEW}, this initiates service startup and returns
    057       * immediately. If the service has already been started, this method returns immediately without
    058       * taking action. A stopped service may not be restarted.
    059       *
    060       * @return a future for the startup result, regardless of whether this call initiated startup.
    061       *         Calling {@link ListenableFuture#get} will block until the service has finished
    062       *         starting, and returns one of {@link State#RUNNING}, {@link State#STOPPING} or
    063       *         {@link State#TERMINATED}. If the service fails to start, {@link ListenableFuture#get}
    064       *         will throw an {@link ExecutionException}, and the service's state will be
    065       *         {@link State#FAILED}. If it has already finished starting, {@link ListenableFuture#get}
    066       *         returns immediately. Cancelling this future has no effect on the service.
    067       */
    068      ListenableFuture<State> start();
    069
    070      /**
    071       * Initiates service startup (if necessary), returning once the service has finished starting.
    072       * Unlike calling {@code start().get()}, this method throws no checked exceptions, and it cannot
    073       * be {@linkplain Thread#interrupt interrupted}.
    074       *
    075       * @throws UncheckedExecutionException if startup failed
    076       * @return the state of the service when startup finished.
    077       */
    078      State startAndWait();
    079
    080      /**
    081       * Returns {@code true} if this service is {@linkplain State#RUNNING running}.
    082       */
    083      boolean isRunning();
    084
    085      /**
    086       * Returns the lifecycle state of the service.
    087       */
    088      State state();
    089
    090      /**
    091       * If the service is {@linkplain State#STARTING starting} or {@linkplain State#RUNNING running},
    092       * this initiates service shutdown and returns immediately. If the service is
    093       * {@linkplain State#NEW new}, it is {@linkplain State#TERMINATED terminated} without having been
    094       * started nor stopped. If the service has already been stopped, this method returns immediately
    095       * without taking action.
    096       *
    097       * @return a future for the shutdown result, regardless of whether this call initiated shutdown.
    098       *         Calling {@link ListenableFuture#get} will block until the service has finished shutting
    099       *         down, and either returns {@link State#TERMINATED} or throws an
    100       *         {@link ExecutionException}. If it has already finished stopping,
    101       *         {@link ListenableFuture#get} returns immediately. Cancelling this future has no effect
    102       *         on the service.
    103       */
    104      ListenableFuture<State> stop();
    105
    106      /**
    107       * Initiates service shutdown (if necessary), returning once the service has finished stopping. If
    108       * this is {@link State#STARTING}, startup will be cancelled. If this is {@link State#NEW}, it is
    109       * {@link State#TERMINATED terminated} without having been started nor stopped. Unlike calling
    110       * {@code stop().get()}, this method throws no checked exceptions.
    111       *
    112       * @throws UncheckedExecutionException if the service has failed or fails during shutdown
    113       * @return the state of the service when shutdown finished.
    114       */
    115      State stopAndWait();
    116
    117      /**
    118       * Registers a {@link Listener} to be {@linkplain Executor#execute executed} on the given
    119       * executor.  The listener will have the corresponding transition method called whenever the
    120       * service changes state. The listener will not have previous state changes replayed, so it is
    121       * suggested that listeners are added before the service starts.
    122       *
    123       * <p>There is no guaranteed ordering of execution of listeners, but any listener added through
    124       * this method is guaranteed to be called whenever there is a state change.
    125       *
    126       * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown
    127       * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception
    128       * thrown by {@linkplain MoreExecutors#sameThreadExecutor inline execution}) will be caught and
    129       * logged.
    130       *
    131       * @param listener the listener to run when the service changes state is complete
    132       * @param executor the executor in which the the listeners callback methods will be run. For fast,
    133       *     lightweight listeners that would be safe to execute in any thread, consider
    134       *     {@link MoreExecutors#sameThreadExecutor}.
    135       * @since 13.0
    136       */
    137      void addListener(Listener listener, Executor executor);
    138
    139      /**
    140       * The lifecycle states of a service.
    141       *
    142       * @since 9.0 (in 1.0 as {@code com.google.common.base.Service.State})
    143       */
    144      @Beta // should come out of Beta when Service does
    145      enum State {
    146        /**
    147         * A service in this state is inactive. It does minimal work and consumes
    148         * minimal resources.
    149         */
    150        NEW,
    151
    152        /**
    153         * A service in this state is transitioning to {@link #RUNNING}.
    154         */
    155        STARTING,
    156
    157        /**
    158         * A service in this state is operational.
    159         */
    160        RUNNING,
    161
    162        /**
    163         * A service in this state is transitioning to {@link #TERMINATED}.
    164         */
    165        STOPPING,
    166
    167        /**
    168         * A service in this state has completed execution normally. It does minimal work and consumes
    169         * minimal resources.
    170         */
    171        TERMINATED,
    172
    173        /**
    174         * A service in this state has encountered a problem and may not be operational. It cannot be
    175         * started nor stopped.
    176         */
    177        FAILED
    178      }
    179
    180      /**
    181       * A listener for the various state changes that a {@link Service} goes through in its lifecycle.
    182       *
    183       * @author Luke Sandberg
    184       * @since 13.0
    185       */
    186      @Beta // should come out of Beta when Service does
    187      interface Listener {
    188        /**
    189         * Called when the service transitions from {@linkplain State#NEW NEW} to
    190         * {@linkplain State#STARTING STARTING}. This occurs when {@link Service#start} or
    191         * {@link Service#startAndWait} is called the first time.
    192         */
    193        void starting();
    194
    195        /**
    196         * Called when the service transitions from {@linkplain State#STARTING STARTING} to
    197         * {@linkplain State#RUNNING RUNNING}. This occurs when a service has successfully started.
    198         */
    199        void running();
    200
    201        /**
    202         * Called when the service transitions to the {@linkplain State#STOPPING STOPPING} state. The
    203         * only valid values for {@code from} are {@linkplain State#STARTING STARTING} or
    204         * {@linkplain State#RUNNING RUNNING}.  This occurs when {@link Service#stop} is called.
    205         *
    206         * @param from The previous state that is being transitioned from.
    207         */
    208        void stopping(State from);
    209
    210        /**
    211         * Called when the service transitions to the {@linkplain State#TERMINATED TERMINATED} state.
    212         * The {@linkplain State#TERMINATED TERMINATED} state is a terminal state in the transition
    213         * diagram.  Therefore, if this method is called, no other methods will be called on the
    214         * {@link Listener}.
    215         *
    216         * @param from The previous state that is being transitioned from.  The only valid values for
    217         *     this are {@linkplain State#NEW NEW}, {@linkplain State#RUNNING RUNNING} or
    218         *     {@linkplain State#STOPPING STOPPING}.
    219         */
    220        void terminated(State from);
    221
    222        /**
    223         * Called when the service transitions to the {@linkplain State#FAILED FAILED} state. The
    224         * {@linkplain State#FAILED FAILED} state is a terminal state in the transition diagram.
    225         * Therefore, if this method is called, no other methods will be called on the {@link Listener}.
    226         *
    227         * @param from The previous state that is being transitioned from.  Failure can occur in any
    228         *     state with the exception of {@linkplain State#NEW NEW} or
    229         *     {@linkplain State#TERMINATED TERMINATED}.
    230         * @param failure The exception that caused the failure.
    231         */
    232        void failed(State from, Throwable failure);
    233      }
    234    }