Tomcat 10.1.19 · org.apache.catalina.Lifecycle · APIdia, the JavaDoc alternative

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 LifecycleEvents fired during state changes are defined in the methods that trigger the changed. No LifecycleEvents are fired if the attempted transition is not valid.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	Lifecycle.SingleUse Marker interface used to indicate that the instance should only be used once.

Field Summary

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

Method Summary

Modifier and Type	Method and Description
public void	addLifecycleListener(LifecycleListener The listener to add listener) Add a LifecycleEvent listener to this component.
public void	destroy() Prepare to discard the object.
public LifecycleListener[]	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. findLifecycleListeners() Get the life cycle listeners associated with this life cycle.
public LifecycleState	Returns: The current state of the source component. getState() Obtain the current state of the source component.
public String	Returns: The name of the current component state. getStateName() Obtain a textual representation of the current component state.
public void	init() Prepare the component for starting.
public void	removeLifecycleListener(LifecycleListener The listener to remove listener) Remove a LifecycleEvent listener from this component.
public 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.
public 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

AFTER_DESTROY_EVENT	back to summary
public static final String AFTER_DESTROY_EVENT The LifecycleEvent type for the "component after destroy" event.

AFTER_INIT_EVENT	back to summary
public static final String AFTER_INIT_EVENT The LifecycleEvent type for the "component after init" event.

AFTER_START_EVENT	back to summary
public static final String AFTER_START_EVENT The LifecycleEvent type for the "component after start" event.

AFTER_STOP_EVENT	back to summary
public static final String AFTER_STOP_EVENT The LifecycleEvent type for the "component after stop" event.

BEFORE_DESTROY_EVENT	back to summary
public static final String BEFORE_DESTROY_EVENT The LifecycleEvent type for the "component before destroy" event.

BEFORE_INIT_EVENT	back to summary
public static final String BEFORE_INIT_EVENT The LifecycleEvent type for the "component before init" event.

BEFORE_START_EVENT	back to summary
public static final String BEFORE_START_EVENT The LifecycleEvent type for the "component before start" event.

BEFORE_STOP_EVENT	back to summary
public static final String BEFORE_STOP_EVENT The LifecycleEvent type for the "component before stop" event.

CONFIGURE_START_EVENT	back to summary
public 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`.

CONFIGURE_STOP_EVENT	back to summary
public 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`.

PERIODIC_EVENT	back to summary
public static final String PERIODIC_EVENT The LifecycleEvent type for the "periodic" event.

START_EVENT	back to summary
public static final String START_EVENT The LifecycleEvent type for the "component start" event.

STOP_EVENT	back to summary
public static final String STOP_EVENT The LifecycleEvent type for the "component stop" event.

Method Detail

addLifecycleListener	back to summary
public void addLifecycleListener(LifecycleListener listener) Add a LifecycleEvent listener to this component. Parameters listener:LifecycleListener The listener to add

addLifecycleListener

back to summary

public void addLifecycleListener(LifecycleListener listener)

Add a LifecycleEvent listener to this component.

Parameters

listener:LifecycleListener: The listener to add

destroy back to summary

destroy	back to summary
public void destroy() throws LifecycleException Prepare to discard the object. The following `LifecycleEvent`s will be fired in the following order: DESTROY_EVENT: On the successful completion of component destruction. Exceptions LifecycleException: if this component detects a fatal error that prevents this component from being used

public void destroy() throws LifecycleException

Prepare to discard the object. The following LifecycleEvents will be fired in the following order:

DESTROY_EVENT: On the successful completion of component destruction.

Exceptions

LifecycleException:: if this component detects a fatal error that prevents this component from being used

findLifecycleListeners	back to summary
public LifecycleListener[] findLifecycleListeners() Get the life cycle listeners associated with this life cycle. Returns:LifecycleListener[] 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.

findLifecycleListeners

back to summary

public LifecycleListener[] findLifecycleListeners()

Get the life cycle listeners associated with this life cycle.

Returns:LifecycleListener[]: 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.

getState	back to summary
public LifecycleState getState() Obtain the current state of the source component. Returns:LifecycleState The current state of the source component.

getState

back to summary

public LifecycleState getState()

Obtain the current state of the source component.

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

getStateName back to summary

getStateName	back to summary
public 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:String The name of the current component state.

public 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:String: The name of the current component state.

init back to summary

init	back to summary
public 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: INIT_EVENT: On the successful completion of component initialization. Exceptions LifecycleException: if this component detects a fatal error that prevents this component from being used

public void init() throws LifecycleException

Prepare the component for starting. This method should perform any initialization required post object creation. The following LifecycleEvents will be fired in the following order:

INIT_EVENT: On the successful completion of component initialization.

Exceptions

LifecycleException:: if this component detects a fatal error that prevents this component from being used

removeLifecycleListener	back to summary
public void removeLifecycleListener(LifecycleListener listener) Remove a LifecycleEvent listener from this component. Parameters listener:LifecycleListener The listener to remove

removeLifecycleListener

back to summary

public void removeLifecycleListener(LifecycleListener listener)

Remove a LifecycleEvent listener from this component.

Parameters

listener:LifecycleListener: The listener to remove

start back to summary

start	back to summary
public 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: BEFORE_START_EVENT: At the beginning of the method. It is as this point the state transitions to `LifecycleState#STARTING_PREP`. 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. 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`. Exceptions LifecycleException: if this component detects a fatal error that prevents this component from being used

public 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 LifecycleEvents will be fired in the following order:

BEFORE_START_EVENT: At the beginning of the method. It is as this point the state transitions to LifecycleState#STARTING_PREP.
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.
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.

Exceptions

LifecycleException:: if this component detects a fatal error that prevents this component from being used

stop back to summary

stop	back to summary
public 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: BEFORE_STOP_EVENT: At the beginning of the method. It is at this point that the state transitions to `LifecycleState#STOPPING_PREP`. 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. 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` Exceptions LifecycleException: if this component detects a fatal error that needs to be reported

public 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 LifecycleEvents will be fired in the following order:

BEFORE_STOP_EVENT: At the beginning of the method. It is at this point that the state transitions to LifecycleState#STOPPING_PREP.
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.
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

Exceptions

LifecycleException:: if this component detects a fatal error that needs to be reported

public Interface Lifecycle

Nested and Inner Type Summary

Field Summary

Method Summary

Field Detail

Method Detail

public Interface Lifecycle.SingleUse