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, PersistentManager, PersistentManagerBase, PersistentValve, RealmBase, RemoteAddrValve, RemoteHostValve, RemoteIpValve, ReplicatedContext, ReplicationValve, RequestFilterValve, SemaphoreValve, SimpleTcpCluster, SingleSignOn, SpnegoAuthenticator, SSLAuthenticator, SSLValve, StandardContext, StandardEngine, StandardHost, StandardManager, StandardPipeline, StandardServer, StandardService, StandardThreadExecutor, StandardWrapper, StoreBase, StuckThreadDetectionValve, Tomcat.ExistingStandardWrapper, UserDatabaseRealm, ValveBase, VirtualWebappLoader, WebappClassLoader, 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               |         |  |
 |     |       ---------<----- MUST_STOP ---------------------<--         |  |
 |     |       |                                                          |  |
 |    \|/      ---------------------------<--------------------------------  ^
 |     |       |                                                             |
 |     |      \|/            auto                 auto              start()  |
 |     |  STOPPING_PREP ------>----- STOPPING ------>----- STOPPED ---->------
 |     |                                ^                  |  |  ^
 |     |               stop()           |                  |  |  |
 |     |       --------------------------                  |  |  |
 |     |       |                                  auto     |  |  |
 |     |       |                  MUST_DESTROY------<-------  |  |
 |     |       |                    |                         |  |
 |     |       |                    |auto                     |  |
 |     |       |    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.

 MUST_STOP is used to indicate that the stop() should be called on
 the component as soon as start() exits. It is typically used when a
 component has failed to start.

 MUST_DESTROY is used to indicate that the stop() should be called on
 the component as soon as stop() exits. It is typically used when a
 component is not designed to be restarted.

 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. TODO: Not all components may transition from STOPPED to STARTING_PREP. These components should use MUST_DESTROY to signal this.

Version:

$Id: Lifecycle.java 1200159 2011-11-10 05:33:31Z kkolinko $

Author:

Craig R. McClanahan

Field Summary

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 after 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

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 after 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. 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 LifecycleEvents 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 LifecycleEvents 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 LifecycleEvents 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 LifecycleEvents 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.