Lifecycle (Apache Tomcat 7.0.104 API Documentation)

org.apache.catalina

## Interface Lifecycle

- All Known Subinterfaces:
    Container, Context, Engine, Executor, Host, Server, Service, Wrapper
  All Known Implementing Classes:
    AccessLogValve, AuthenticatorBase, BackupManager, BasicAuthenticator, ClusterManagerBase, ClusterSingleSignOn, CombinedRealm, CometConnectionManagerValve, Connector, ContainerBase, CrawlerSessionManagerValve, DataSourceRealm, DeltaManager, DigestAuthenticator, Embedded, ErrorReportValve, ExtendedAccessLogValve, FailedContext, FileStore, FormAuthenticator, JAASMemoryLoginModule, JAASRealm, JDBCAccessLogValve, JDBCRealm, JDBCStore, JNDIRealm, JvmRouteBinderValve, LifecycleBase, LifecycleMBeanBase, LockOutRealm, ManagerBase, MapperListener, MemoryRealm, NamingResources, NonLoginAuthenticator, NullRealm, ParallelWebappClassLoader, PersistentManager, PersistentManagerBase, PersistentValve, RealmBase, RemoteAddrValve, RemoteCIDRValve, RemoteHostValve, RemoteIpValve, ReplicatedContext, ReplicationValve, RequestFilterValve, SemaphoreValve, SessionIdGeneratorBase, SimpleTcpCluster, SingleSignOn, SpnegoAuthenticator, SSLAuthenticator, SSLValve, StandardContext, StandardEngine, StandardHost, StandardManager, StandardPipeline, StandardServer, StandardService, StandardSessionIdGenerator, StandardThreadExecutor, StandardWrapper, StoreBase, StuckThreadDetectionValve, Tomcat.ExistingStandardWrapper, UserDatabaseRealm, ValveBase, VirtualWebappLoader, WebappClassLoader, WebappClassLoaderBase, WebappLoader

      public interface Lifecycle

  Common interface for component life cycle methods. Catalina components may implement this interface (as well as the appropriate interface(s) for the functionality they support) in order to provide a consistent mechanism to start and stop the component.
  The valid state transitions for components that support `Lifecycle` are:

                  start()
        -----------------------------
        |                           |
        | init()                    |
       NEW -»-- INITIALIZING        |
       | |           |              |     ------------------«-----------------------
       | |           |auto          |     |                                        |
       | |          \|/    start() \|/   \|/     auto          auto         stop() |
       | |      INITIALIZED --»-- STARTING_PREP --»- STARTING --»- STARTED --»---  |
       | |         |                                                            |  |
       | |destroy()|                                                            |  |
       | --»-----«--    ------------------------«--------------------------------  ^
       |     |          |                                                          |
       |     |         \|/          auto                 auto              start() |
       |     |     STOPPING_PREP ----»---- STOPPING ------»----- STOPPED -----»-----
       |    \|/                               ^                     |  ^
       |     |               stop()           |                     |  |
       |     |       --------------------------                     |  |
       |     |       |                                              |  |
       |     |       |    destroy()                       destroy() |  |
       |     |    FAILED ----»------ DESTROYING ---«-----------------  |
       |     |                        ^     |                          |
       |     |     destroy()          |     |auto                      |
       |     --------»-----------------    \|/                         |
       |                                 DESTROYED                     |
       |                                                               |
       |                            stop()                             |
       ----»-----------------------------»------------------------------

       Any state can transition to FAILED.

       Calling start() while a component is in states STARTING_PREP, STARTING or
       STARTED has no effect.

       Calling start() while a component is in state NEW will cause init() to be
       called immediately after the start() method is entered.

       Calling stop() while a component is in states STOPPING_PREP, STOPPING or
       STOPPED has no effect.

       Calling stop() while a component is in state NEW transitions the component
       to STOPPED. This is typically encountered when a component fails to start and
       does not start all its sub-components. When the component is stopped, it will
       try to stop all sub-components - even those it didn't start.

       Attempting any other transition will throw LifecycleException.

  The `LifecycleEvent`s fired during state changes are defined in the methods that trigger the changed. No `LifecycleEvent`s are fired if the attempted transition is not valid.
  Author:
    Craig R. McClanahan

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Lifecycle.SingleUse` Marker interface used to indicate that the instance should only be used once.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `AFTER_DESTROY_EVENT` The LifecycleEvent type for the "component after destroy" event.
    `static String` | `AFTER_INIT_EVENT` The LifecycleEvent type for the "component after init" event.
    `static String` | `AFTER_START_EVENT` The LifecycleEvent type for the "component after start" event.
    `static String` | `AFTER_STOP_EVENT` The LifecycleEvent type for the "component after stop" event.
    `static String` | `BEFORE_DESTROY_EVENT` The LifecycleEvent type for the "component before destroy" event.
    `static String` | `BEFORE_INIT_EVENT` The LifecycleEvent type for the "component before init" event.
    `static String` | `BEFORE_START_EVENT` The LifecycleEvent type for the "component before start" event.
    `static String` | `BEFORE_STOP_EVENT` The LifecycleEvent type for the "component before stop" event.
    `static String` | `CONFIGURE_START_EVENT` The LifecycleEvent type for the "configure_start" event.
    `static String` | `CONFIGURE_STOP_EVENT` The LifecycleEvent type for the "configure_stop" event.
    `static String` | `PERIODIC_EVENT` The LifecycleEvent type for the "periodic" event.
    `static String` | `START_EVENT` The LifecycleEvent type for the "component start" event.
    `static String` | `STOP_EVENT` The LifecycleEvent type for the "component stop" event.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addLifecycleListener(LifecycleListener listener)` Add a LifecycleEvent listener to this component.
    `void` | `destroy()` Prepare to discard the object.
    `LifecycleListener[]` | `findLifecycleListeners()` Get the life cycle listeners associated with this life cycle.
    `LifecycleState` | `getState()` Obtain the current state of the source component.
    `String` | `getStateName()` Obtain a textual representation of the current component state.
    `void` | `init()` Prepare the component for starting.
    `void` | `removeLifecycleListener(LifecycleListener listener)` Remove a LifecycleEvent listener from this component.
    `void` | `start()` Prepare for the beginning of active use of the public methods other than property getters/setters and life cycle methods of this component.
    `void` | `stop()` Gracefully terminate the active use of the public methods other than property getters/setters and life cycle methods of this component.

- - ### Field Detail

    - #### BEFORE_INIT_EVENT

          static final String BEFORE_INIT_EVENT

      The LifecycleEvent type for the "component before init" event.
      See Also:
        Constant Field Values

    - #### AFTER_INIT_EVENT

          static final String AFTER_INIT_EVENT

      The LifecycleEvent type for the "component after init" event.
      See Also:
        Constant Field Values

    - #### START_EVENT

          static final String START_EVENT

      The LifecycleEvent type for the "component start" event.
      See Also:
        Constant Field Values

    - #### BEFORE_START_EVENT

          static final String BEFORE_START_EVENT

      The LifecycleEvent type for the "component before start" event.
      See Also:
        Constant Field Values

    - #### AFTER_START_EVENT

          static final String AFTER_START_EVENT

      The LifecycleEvent type for the "component after start" event.
      See Also:
        Constant Field Values

    - #### STOP_EVENT

          static final String STOP_EVENT

      The LifecycleEvent type for the "component stop" event.
      See Also:
        Constant Field Values

    - #### BEFORE_STOP_EVENT

          static final String BEFORE_STOP_EVENT

      The LifecycleEvent type for the "component before stop" event.
      See Also:
        Constant Field Values

    - #### AFTER_STOP_EVENT

          static final String AFTER_STOP_EVENT

      The LifecycleEvent type for the "component after stop" event.
      See Also:
        Constant Field Values

    - #### AFTER_DESTROY_EVENT

          static final String AFTER_DESTROY_EVENT

      The LifecycleEvent type for the "component after destroy" event.
      See Also:
        Constant Field Values

    - #### BEFORE_DESTROY_EVENT

          static final String BEFORE_DESTROY_EVENT

      The LifecycleEvent type for the "component before destroy" event.
      See Also:
        Constant Field Values

    - #### PERIODIC_EVENT

          static final String PERIODIC_EVENT

      The LifecycleEvent type for the "periodic" event.
      See Also:
        Constant Field Values

    - #### CONFIGURE_START_EVENT

          static final String CONFIGURE_START_EVENT

      The LifecycleEvent type for the "configure_start" event. Used by those components that use a separate component to perform configuration and need to signal when configuration should be performed - usually after `BEFORE_START_EVENT` and before `START_EVENT`.
      See Also:
        Constant Field Values

    - #### CONFIGURE_STOP_EVENT

          static final String CONFIGURE_STOP_EVENT

      The LifecycleEvent type for the "configure_stop" event. Used by those components that use a separate component to perform configuration and need to signal when de-configuration should be performed - usually after `STOP_EVENT` and before `AFTER_STOP_EVENT`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### addLifecycleListener

          void addLifecycleListener(LifecycleListener listener)

      Add a LifecycleEvent listener to this component.
      Parameters:
        `listener` - The listener to add

    - #### findLifecycleListeners

          LifecycleListener[] findLifecycleListeners()

      Get the life cycle listeners associated with this life cycle.
      Returns:
        An array containing the life cycle listeners associated with this life cycle. If this component has no listeners registered, a zero-length array is returned.

    - #### removeLifecycleListener

          void removeLifecycleListener(LifecycleListener listener)

      Remove a LifecycleEvent listener from this component.
      Parameters:
        `listener` - The listener to remove

    - #### init

          void init()
                    throws LifecycleException

      Prepare the component for starting. This method should perform any initialization required post object creation. The following `LifecycleEvent`s will be fired in the following order:
      1. INIT_EVENT: On the successful completion of component initialization.
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### start

          void start()
                     throws LifecycleException

      Prepare for the beginning of active use of the public methods other than property getters/setters and life cycle methods of this component. This method should be called before any of the public methods other than property getters/setters and life cycle methods of this component are utilized. The following `LifecycleEvent`s will be fired in the following order:
      1. BEFORE_START_EVENT: At the beginning of the method. It is as this point the state transitions to `LifecycleState.STARTING_PREP`.
      2. START_EVENT: During the method once it is safe to call start() for any child components. It is at this point that the state transitions to `LifecycleState.STARTING` and that the public methods other than property getters/setters and life cycle methods may be used.
      3. AFTER_START_EVENT: At the end of the method, immediately before it returns. It is at this point that the state transitions to `LifecycleState.STARTED`.
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### stop

          void stop()
                    throws LifecycleException

      Gracefully terminate the active use of the public methods other than property getters/setters and life cycle methods of this component. Once the STOP_EVENT is fired, the public methods other than property getters/setters and life cycle methods should not be used. The following `LifecycleEvent`s will be fired in the following order:
      1. BEFORE_STOP_EVENT: At the beginning of the method. It is at this point that the state transitions to `LifecycleState.STOPPING_PREP`.
      2. STOP_EVENT: During the method once it is safe to call stop() for any child components. It is at this point that the state transitions to `LifecycleState.STOPPING` and that the public methods other than property getters/setters and life cycle methods may no longer be used.
      3. AFTER_STOP_EVENT: At the end of the method, immediately before it returns. It is at this point that the state transitions to `LifecycleState.STOPPED`.
      Note that if transitioning from `LifecycleState.FAILED` then the three events above will be fired but the component will transition directly from `LifecycleState.FAILED` to `LifecycleState.STOPPING`, bypassing `LifecycleState.STOPPING_PREP`
      Throws:
        `LifecycleException` - if this component detects a fatal error that needs to be reported

    - #### destroy

          void destroy()
                       throws LifecycleException

      Prepare to discard the object. The following `LifecycleEvent`s will be fired in the following order:
      1. DESTROY_EVENT: On the successful completion of component destruction.
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### getState

          LifecycleState getState()

      Obtain the current state of the source component.
      Returns:
        The current state of the source component.

    - #### getStateName

          String getStateName()

      Obtain a textual representation of the current component state. Useful for JMX. The format of this string may vary between point releases and should not be relied upon to determine component state. To determine component state, use `getState()`.
      Returns:
        The name of the current component state.

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.