LifecycleBase (Apache Tomcat 9.0.111 API Documentation)
Description: declaration: package: org.apache.catalina.util, class: LifecycleBase

# Class LifecycleBase

java.lang.Object
org.apache.catalina.util.LifecycleBase

All Implemented Interfaces:
  `Lifecycle`

Direct Known Subclasses:
  `AbstractResourceSet, EmptyResourceSet, LifecycleMBeanBase, SessionIdGeneratorBase, StandardPipeline, StoreBase`

public abstract class LifecycleBase extends Object implements Lifecycle
Base implementation of the `Lifecycle` interface that implements the state transition rules for `Lifecycle.start()` and `Lifecycle.stop()`

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  ### Fields inherited from interface Lifecycle

  `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LifecycleBase()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addLifecycleListener(LifecycleListener listener)`
  Add a LifecycleEvent listener to this component.
  `final void`
  `destroy()`
  Prepare to discard the object.
  `protected abstract void`
  `destroyInternal()`
  Subclasses implement this method to perform any instance destruction required.
  `LifecycleListener[]`
  `findLifecycleListeners()`
  Get the life cycle listeners associated with this life cycle.
  `protected void`
  `fireLifecycleEvent(String type, Object data)`
  Allow subclasses to fire `Lifecycle` events.
  `LifecycleState`
  `getState()`
  Obtain the current state of the source component.
  `String`
  `getStateName()`
  Obtain a textual representation of the current component state.
  `boolean`
  `getThrowOnFailure()`
  Will a `LifecycleException` thrown by a subclass during `initInternal()`, `startInternal()`, `stopInternal()` or `destroyInternal()` be re-thrown for the caller to handle or will it be logged instead?
  `final void`
  `init()`
  Prepare the component for starting.
  `protected abstract void`
  `initInternal()`
  Subclasses implement this method to perform any instance initialisation required.
  `void`
  `removeLifecycleListener(LifecycleListener listener)`
  Remove a LifecycleEvent listener from this component.
  `protected void`
  `setState(LifecycleState state)`
  Provides a mechanism for subclasses to update the component state.
  `protected void`
  `setState(LifecycleState state, Object data)`
  Provides a mechanism for subclasses to update the component state.
  `void`
  `setThrowOnFailure(boolean throwOnFailure)`
  Configure if a `LifecycleException` thrown by a subclass during `initInternal()`, `startInternal()`, `stopInternal()` or `destroyInternal()` will be re-thrown for the caller to handle or if it will be logged instead.
  `final 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.
  `protected abstract void`
  `startInternal()`
  Subclasses must ensure that the state is changed to `LifecycleState.STARTING` during the execution of this method.
  `final void`
  `stop()`
  Gracefully terminate the active use of the public methods other than property getters/setters and life cycle methods of this component.
  `protected abstract void`
  `stopInternal()`
  Subclasses must ensure that the state is changed to `LifecycleState.STOPPING` during the execution of this method.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### LifecycleBase

    public LifecycleBase()

- ## Method Details

  - ### getThrowOnFailure

    public boolean getThrowOnFailure()
    Will a `LifecycleException` thrown by a subclass during `initInternal()`, `startInternal()`, `stopInternal()` or `destroyInternal()` be re-thrown for the caller to handle or will it be logged instead?
    Returns:
      `true` if the exception will be re-thrown, otherwise `false`

  - ### setThrowOnFailure

    public void setThrowOnFailure(boolean throwOnFailure)
    Configure if a `LifecycleException` thrown by a subclass during `initInternal()`, `startInternal()`, `stopInternal()` or `destroyInternal()` will be re-thrown for the caller to handle or if it will be logged instead.
    Parameters:
      `throwOnFailure` - `true` if the exception should be re-thrown, otherwise `false`

  - ### addLifecycleListener

    public void addLifecycleListener(LifecycleListener listener)
    Description copied from interface: `Lifecycle`
    Add a LifecycleEvent listener to this component.
    Specified by:
      `addLifecycleListener` in interface `Lifecycle`
    Parameters:
      `listener` - The listener to add

  - ### findLifecycleListeners

    public LifecycleListener[] findLifecycleListeners()
    Description copied from interface: `Lifecycle`
    Get the life cycle listeners associated with this life cycle.
    Specified by:
      `findLifecycleListeners` in interface `Lifecycle`
    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

    public void removeLifecycleListener(LifecycleListener listener)
    Description copied from interface: `Lifecycle`
    Remove a LifecycleEvent listener from this component.
    Specified by:
      `removeLifecycleListener` in interface `Lifecycle`
    Parameters:
      `listener` - The listener to remove

  - ### fireLifecycleEvent

    protected void fireLifecycleEvent(String type, Object data)
    Allow subclasses to fire `Lifecycle` events.
    Parameters:
      `type` - Event type
      `data` - Data associated with event.

  - ### init

    public final void init() throws LifecycleException
    Description copied from interface: `Lifecycle`
    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.
    Specified by:
      `init` in interface `Lifecycle`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  - ### initInternal

    protected abstract void initInternal() throws LifecycleException
    Subclasses implement this method to perform any instance initialisation required.
    Throws:
      `LifecycleException` - If the initialisation fails

  - ### start

    public final void start() throws LifecycleException
    Description copied from interface: `Lifecycle`
    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`.
    Specified by:
      `start` in interface `Lifecycle`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  - ### startInternal

    protected abstract void startInternal() throws LifecycleException
    Subclasses must ensure that the state is changed to `LifecycleState.STARTING` during the execution of this method. Changing state will trigger the `Lifecycle.START_EVENT` event. If a component fails to start it may either throw a `LifecycleException` which will cause it's parent to fail to start, or it can place itself in the error state in which case `stop()` will be called on the failed component but the parent component will continue to start normally.
    Throws:
      `LifecycleException` - Start error occurred

  - ### stop

    public final void stop() throws LifecycleException
    Description copied from interface: `Lifecycle`
    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`
    Specified by:
      `stop` in interface `Lifecycle`
    Throws:
      `LifecycleException` - if this component detects a fatal error that needs to be reported

  - ### stopInternal

    protected abstract void stopInternal() throws LifecycleException
    Subclasses must ensure that the state is changed to `LifecycleState.STOPPING` during the execution of this method. Changing state will trigger the `Lifecycle.STOP_EVENT` event.
    Throws:
      `LifecycleException` - Stop error occurred

  - ### destroy

    public final void destroy() throws LifecycleException
    Description copied from interface: `Lifecycle`
    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.
    Specified by:
      `destroy` in interface `Lifecycle`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used

  - ### destroyInternal

    protected abstract void destroyInternal() throws LifecycleException
    Subclasses implement this method to perform any instance destruction required.
    Throws:
      `LifecycleException` - If the destruction fails

  - ### getState

    public LifecycleState getState()
    Description copied from interface: `Lifecycle`
    Obtain the current state of the source component.
    Specified by:
      `getState` in interface `Lifecycle`
    Returns:
      The current state of the source component.

  - ### getStateName

    public String getStateName()
    Description copied from interface: `Lifecycle`
    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 `Lifecycle.getState()`.
    Specified by:
      `getStateName` in interface `Lifecycle`
    Returns:
      The name of the current component state.

  - ### setState

    protected void setState(LifecycleState state) throws LifecycleException
    Provides a mechanism for subclasses to update the component state. Calling this method will automatically fire any associated `Lifecycle` event. It will also check that any attempted state transition is valid for a subclass.
    Parameters:
      `state` - The new state for this component
    Throws:
      `LifecycleException` - when attempting to set an invalid state

  - ### setState

    protected void setState(LifecycleState state, Object data) throws LifecycleException
    Provides a mechanism for subclasses to update the component state. Calling this method will automatically fire any associated `Lifecycle` event. It will also check that any attempted state transition is valid for a subclass.
    Parameters:
      `state` - The new state for this component
      `data` - The data to pass to the associated `Lifecycle` event
    Throws:
      `LifecycleException` - when attempting to set an invalid state