org.sape.carbon.core.component.lifecycle
Interface LifecycleInterceptor

All Known Implementing Classes:

DefaultLifecycleInterceptor

public interface LifecycleInterceptor

Defines the operations exposed by a lifecycle managing decorating filter. Copyright 2003 Sapient

Since:

carbon 2.0

Version:

$Revision: 1.8 $($Author: dvoet $ / $Date: 2003/05/05 21:21:13 $)

Author:

Chris Herron, January 2002

Method Summary

void	configureComponent(ComponentConfiguration configuration) Provides a Component with its Configuration.
void	destroyComponent() Tells the Component prepare to die.
LifecycleStateEnum	getLifecycleState() getLifecycleState implies a property "LifecycleState".
String	getLifecycleStateString() Returns the string version of the state of the assisted component
void	initializeComponent(Component thisComponent) Run only once during the life of a Component, immediately after the Component is created.
void	resumeComponent() Tells the Component to resume its service.
void	startComponent() Tells the Component to begin providing its service.
void	stopComponent() Tells the Component to cease providing its service.
void	suspendComponent() Tells the Component to suspend its service.

Method Detail

getLifecycleState

public LifecycleStateEnum getLifecycleState()

getLifecycleState implies a property "LifecycleState". Note the lack of a corresponding mutator method - this property is read-only to external entities.

Returns:

the enum state of the assisted component

getLifecycleStateString

public String getLifecycleStateString()

Returns the string version of the state of the assisted component

Returns:

the string state of the assisted component

initializeComponent

public void initializeComponent(Component thisComponent)
                         throws InvalidStateException,
                                OperationNotSupportedException,
                                StateTransitionException

Run only once during the life of a Component, immediately after the Component is created.

Valid Entry States: CREATING

Interim State: INITIALIZING

Exit State: STOPPED

Parameters:

thisComponent - component being initialized

Throws:

InvalidStateException - When the entry state is not allowed

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation

startComponent

public void startComponent()
                    throws InvalidStateException,
                           OperationNotSupportedException,
                           StateTransitionException

Tells the Component to begin providing its service.

Valid Entry States: STOPPED

Interim State: STARTING

Exit State: RUNNING

Throws:

InvalidStateException - When the entry state is not allowed

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation

stopComponent

public void stopComponent()
                   throws InvalidStateException,
                          OperationNotSupportedException,
                          StateTransitionException

Tells the Component to cease providing its service. This is an opportunity for the Component to complete outstanding work.

Valid Entry States: RUNNING or SUSPENDED

Interim State: STOPPING

Exit State: STOPPED

Throws:

InvalidStateException - When the entry state is not allowed

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation

suspendComponent

public void suspendComponent()
                      throws InvalidStateException,
                             OperationNotSupportedException,
                             StateTransitionException

Tells the Component to suspend its service. This is an opportunity for the Component to sensibly pause its outstanding work.

Valid Entry States: RUNNING

Interim State: SUSPENDING

Exit State: SUSPENDED

Throws:

InvalidStateException - When the entry state is not allowed

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation

resumeComponent

public void resumeComponent()
                     throws InvalidStateException,
                            OperationNotSupportedException,
                            StateTransitionException

Tells the Component to resume its service. The Component can now continue its outstanding work.

Valid Entry States: SUSPENDED

Interim State: RESUMING

Exit State: RUNNING

Throws:

InvalidStateException - When the entry state is not allowed

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation

configureComponent

public void configureComponent(ComponentConfiguration configuration)
                        throws InvalidStateException,
                               OperationNotSupportedException,
                               StateTransitionException

Provides a Component with its Configuration. A component can be configured if it is STOPPED or SUSPENDED. As a convenience, if the component is RUNNING, it will automatically be suspended prior to being configured, then resumend once configuring is complete.

Valid Entry States: STOPPED, SUSPENDED, RUNNING

Interim State: CONFIGURING

Exit States: STOPPED, SUSPENDED, RUNNING (should match entry state)

Parameters:

configuration - configuration for the component

Throws:

InvalidStateException - When the entry state is not allowed

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation

destroyComponent

public void destroyComponent()
                      throws OperationNotSupportedException,
                             StateTransitionException

Tells the Component prepare to die. This is an opportunity for the developer to do some sensible housekeeping to aid Garbage Collection, relinquish resources etc. Once in the DESTROYED state, a Component cannot be revived.

Valid Entry States: any

Interim State: DESTROYING

Exit State: DESTROYED

Throws:

OperationNotSupportedException - When component does not support the requested operation

StateTransitionException - When an error occured while trying to complete the lifecycle operation