org.sape.carbon.core.component.lifecycle
Class DefaultLifecycleInterceptor

java.lang.Object
  |
  +--org.sape.carbon.core.component.proxy.AbstractInterceptor
        |
        +--org.sape.carbon.core.component.lifecycle.DefaultLifecycleInterceptor

All Implemented Interfaces:

Decorator, Interceptor, LifecycleInterceptor

public class DefaultLifecycleInterceptor

extends AbstractInterceptor

implements LifecycleInterceptor, Interceptor

This is the default implementation of the lifecycle interceptor interface. This class takes on the responsibility of delegating Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.9 $($Author: ghinkl $ / $Date: 2003/10/15 21:40:19 $)

Author:

Chris Herron, January 2002

Field Summary

private long	blockedCallTimeout timeout for blocking calls.
private Component	componentProxy reference to the complete component
private LifecycleStateEnum	currentState The current state associated with the Component.
private long	destroyerThreadTimeout timeout for the destroyer thread.
protected static Class[]	EXPOSED_INTERFACES Array of interfaces this proxy adds to a component.
private FunctionalInterface	functionalImplementation A reference to the Component instance that is being managed.
static String	LIFECYCLE_CHANGE_EVENT_NAME Name of lifecycle change event.
private org.apache.commons.logging.Log	log Provides handle to Apache-commons logger.
private ComponentProxyInvocationHandler	proxyInvocationHandler A reference to the component proxy invocation handler.
private Object	suspendedLock lock object synchronized upon to block calls while in a suspended state, used in waitForResume and internalResumeComponent methods
private static Set	VALID_ENTRY_STATES_CONFIGURE Defines the valid configure states
private static Set	VALID_ENTRY_STATES_INITIALIZE Defines the valid initialize states
private static Set	VALID_ENTRY_STATES_RESUME Defines the valid resume states
private static Set	VALID_ENTRY_STATES_START Defines the valid start states
private static Set	VALID_ENTRY_STATES_STOP Defines the valid stop states
private static Set	VALID_ENTRY_STATES_SUSPEND Defines the valid suspend states

Fields inherited from class org.sape.carbon.core.component.proxy.AbstractInterceptor

nextInterceptor, nextInterceptorIsProxy, nextInvocationHandler

Constructor Summary

DefaultLifecycleInterceptor(FunctionalInterface componentInstance, ComponentProxyInvocationHandler proxyInvocationHandler, DefaultLifecycleInterceptorConfiguration configuration)
Creates a new DefaultLifecycleInterceptor.

Method Summary

private void	callComponentConfigure(ComponentConfiguration configuration) Calls component's lifecycle method.
private void	callComponentResume() Calls component's lifecycle method.
private void	callComponentStart() Calls component's lifecycle method.
private void	callComponentStop() Calls component's lifecycle method.
private void	callComponentSuspend() Calls component's lifecycle method.
void	configureComponent(ComponentConfiguration configuration) Provides a Component with its Configuration.
void	destroyComponent() Tells the Component prepare to die.
protected String	getComponentName() Utility method used to get the component's name
Class[]	getExposedInterfaces() This should return the list of interfaces that a decorator wishes to expose through the component proxy.
LifecycleStateEnum	getLifecycleState() Gets the current lifecycle state of the component.
String	getLifecycleStateString() Returns a string representation of the Lifecycle State
void	initializeComponent(Component thisComponent) Run ONLY ONCE during the life of a Component, immediately after the Component is created.
protected void	internalResumeComponent() Helper method to do the work of resuming a component.
protected void	internalStopComponent() Helper method to do the work of suspending a component.
protected void	internalSuspendComponent() Helper method to do the work of suspending a component.
Object	invoke(Invocation invocation) This method must implement the invocation of any necessary actions and the chaining the next interceptor.
protected void	killInvalidComponent() This method is called when an exception other than NonFatalStateTransitionException is thrown from a component's lifecycle method which signals that the component is corrupt and should be destroyed.
protected void	logNotSupported(Class unImplementedInterface) Utility method to log trace details when a component does not support an attempted lifecycle operation.
void	resumeComponent() Tells the Component to resume its service.
void	setComponentReference(Component componentProxy) This implementation does not make use of the componentProxy reference
protected void	setLifecycleState(LifecycleStateEnum state) Sets the current lifecycle state
void	startComponent() Tells the Component to begin providing its service.
protected void	startLifecycleMethod() Acquires the component's monitor for writing.
void	stopComponent() Tells the Component to cease providing its service.
protected void	stopLifecycleMethod() Releases the component's monitor
void	suspendComponent() Tells the Component to suspend its service.
protected void	validateEntryState(LifecycleStateEnum entryState, Set validStates) Checks if a given state exists in a set of valid states.
protected void	waitForResume() Waits for the component to return from the LifecycleStateEnum.SUSPENDED state to the LifecycleStateEnum.RUNNING state.

Methods inherited from class org.sape.carbon.core.component.proxy.AbstractInterceptor

callNextInterceptor, setNextInterceptor

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.sape.carbon.core.component.proxy.Interceptor

setNextInterceptor

Field Detail

EXPOSED_INTERFACES

protected static final Class[] EXPOSED_INTERFACES

Array of interfaces this proxy adds to a component.

log

private org.apache.commons.logging.Log log

Provides handle to Apache-commons logger.

LIFECYCLE_CHANGE_EVENT_NAME

public static final String LIFECYCLE_CHANGE_EVENT_NAME

Name of lifecycle change event.

See Also:

Constant Field Values

functionalImplementation

private final FunctionalInterface functionalImplementation

A reference to the Component instance that is being managed. final because once the interceptor in constructed, this should not change.

currentState

private LifecycleStateEnum currentState

The current state associated with the Component. Access to this property must be synchronized. Access only via get and set methods.

proxyInvocationHandler

private final ComponentProxyInvocationHandler proxyInvocationHandler

A reference to the component proxy invocation handler. Used to get a reference to the components monitor. final because once the interceptor in constructed, this should not change.

componentProxy

private Component componentProxy

reference to the complete component

suspendedLock

private final Object suspendedLock

lock object synchronized upon to block calls while in a suspended state, used in waitForResume and internalResumeComponent methods

blockedCallTimeout

private long blockedCallTimeout

timeout for blocking calls.

destroyerThreadTimeout

private long destroyerThreadTimeout

timeout for the destroyer thread.

VALID_ENTRY_STATES_INITIALIZE

private static final Set VALID_ENTRY_STATES_INITIALIZE

Defines the valid initialize states

VALID_ENTRY_STATES_START

private static final Set VALID_ENTRY_STATES_START

Defines the valid start states

VALID_ENTRY_STATES_STOP

private static final Set VALID_ENTRY_STATES_STOP

Defines the valid stop states

VALID_ENTRY_STATES_SUSPEND

private static final Set VALID_ENTRY_STATES_SUSPEND

Defines the valid suspend states

VALID_ENTRY_STATES_RESUME

private static final Set VALID_ENTRY_STATES_RESUME

Defines the valid resume states

VALID_ENTRY_STATES_CONFIGURE

private static final Set VALID_ENTRY_STATES_CONFIGURE

Defines the valid configure states

Constructor Detail

DefaultLifecycleInterceptor

public DefaultLifecycleInterceptor(FunctionalInterface componentInstance,
                                   ComponentProxyInvocationHandler proxyInvocationHandler,
                                   DefaultLifecycleInterceptorConfiguration configuration)

Creates a new DefaultLifecycleInterceptor. Sets the initial state to CREATING. It is intended that the constructor does not accept as a parameter the Component to be managed, since this would circumvent the mutator method on the LifecycleInterceptor Interface.

Parameters:

componentInstance - instance of the component

proxyInvocationHandler - invocation handler for the component

configuration - configuration for the interceptor

Method Detail

invoke

public Object invoke(Invocation invocation)
              throws Throwable

This method must implement the invocation of any necessary actions and the chaining the next interceptor.

Specified by:

invoke in interface Interceptor

Parameters:

invocation - the invocation to execute

Returns:

the results of the invocation's execution

Throws:

Throwable - indicates an error in the invocation chain

getExposedInterfaces

public Class[] getExposedInterfaces()

This should return the list of interfaces that a decorator wishes to expose through the component proxy. This is used by the component factory to determine what interfaces the component proxy will implement.

Specified by:

getExposedInterfaces in interface Decorator

Returns:

Class[] an array of interfaces

getLifecycleState

public LifecycleStateEnum getLifecycleState()

Gets the current lifecycle state of the component. Note the protected corresponding mutator method - this property is read-only to external entities.

Specified by:

getLifecycleState in interface LifecycleInterceptor

Returns:

the lifecycle state of this component

getLifecycleStateString

public String getLifecycleStateString()

Returns a string representation of the Lifecycle State

Specified by:

getLifecycleStateString in interface LifecycleInterceptor

Returns:

a string representation of the Lifecycle State

setLifecycleState

protected void setLifecycleState(LifecycleStateEnum state)

Sets the current lifecycle state

Parameters:

state - the new state

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. Enforced by having CREATING as the only allowed entry state.

Valid Entry States: CREATING

Interim State: INITIALIZING

Exit State: STOPPED

Specified by:

initializeComponent in interface LifecycleInterceptor

Parameters:

thisComponent - component to be 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

Specified by:

startComponent in interface LifecycleInterceptor

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, SUSPENDED

Interim State: STOPPING

Exit State: STOPPED

Specified by:

stopComponent in interface LifecycleInterceptor

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

Specified by:

suspendComponent in interface LifecycleInterceptor

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

Specified by:

resumeComponent in interface LifecycleInterceptor

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. The Component should be SUSPENDED or STOPPED, if not already. The Component should also be returned to its entry state (RUNNING or SUSPENDED) after the main Configure operation has completed.

Valid Entry States: RUNNING, SUSPENDED, STOPPED

Interim State: CONFIGURING

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

Specified by:

configureComponent in interface LifecycleInterceptor

Parameters:

configuration - Configuration object to be applied to 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. This implementation will wait for DESTROY_TIMEOUT_MILLIS for the component to be destroyed. If, after that time the component has not been destroyed, it will be logged as a warning.

Valid Entry States: All states are valid for entry. If the component is in the RUNNING state, it will be stopped first.

Interim State: DESTROYING

Exit State: DESTROYED

Specified by:

destroyComponent in interface LifecycleInterceptor

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

setComponentReference

public void setComponentReference(Component componentProxy)

This implementation does not make use of the componentProxy reference

Specified by:

setComponentReference in interface Decorator

Parameters:

componentProxy - a reference to the component that this interceptor is assisting

startLifecycleMethod

protected void startLifecycleMethod()

Acquires the component's monitor for writing. If this method is called, it is imperitive that stopLifecycleMethod() is called.

Example invocation:

 startLifecycleMethod();
 try {
     ...
 } finally {
     stopLifecycleMethod();
 }
 

Throws:

StateTransitionException - if the Thread is interrupted

See Also:

ComponentProxyInvocationHandler.getMonitor()

stopLifecycleMethod

protected void stopLifecycleMethod()

Releases the component's monitor

internalSuspendComponent

protected void internalSuspendComponent()
                                 throws OperationNotSupportedException,
                                        StateTransitionException

Helper method to do the work of suspending a component. Called by suspendComponent and configureComponent. A helper method is used so that calling methods can handle threading issues as they require while not duplicating code

Throws:

StateTransitionException - if an exception is caught in the functional implementations suspend method

OperationNotSupportedException - not thrown by this imlementation, but provided for overriding methods

internalResumeComponent

protected void internalResumeComponent()
                                throws OperationNotSupportedException,
                                       StateTransitionException

Helper method to do the work of resuming a component. Called by resumeComponent and configureComponent. A helper method is used so that calling methods can handle threading issues as they require while not duplicating code

Throws:

StateTransitionException - if an exception is caught in the functional implementations resume method

OperationNotSupportedException - not thrown by this imlementation, but provided for overriding methods

internalStopComponent

protected void internalStopComponent()
                              throws OperationNotSupportedException,
                                     StateTransitionException

Helper method to do the work of suspending a component. Called by suspendComponent and configureComponent. A helper method is used so that calling methods can handle threading issues as they require while not duplicating code

Throws:

StateTransitionException - if an exception is caught in the functional implementations suspend method

OperationNotSupportedException - not thrown by this imlementation, but provided for overriding methods

waitForResume

protected void waitForResume()
                      throws InvalidStateException,
                             ComponentUnavailableException

Waits for the component to return from the LifecycleStateEnum.SUSPENDED state to the LifecycleStateEnum.RUNNING state.

Override this method to disable or change this functionality.

Throws:

ComponentUnavailableException - if it does not change states in a timely manner or if

InvalidStateException - if the entry state is not within the Set of validStates

validateEntryState

protected final void validateEntryState(LifecycleStateEnum entryState,
                                        Set validStates)

Checks if a given state exists in a set of valid states.

Parameters:

entryState - the entry state to be validated

validStates - a set of validStates

Throws:

InvalidStateException - if the entry state is not within the Set of validStates

logNotSupported

protected final void logNotSupported(Class unImplementedInterface)

Utility method to log trace details when a component does not support an attempted lifecycle operation.

Parameters:

unImplementedInterface - the interface which held the lifecycle method that was not implemented by the component

getComponentName

protected final String getComponentName()

Utility method used to get the component's name

Returns:

String the name of the component

killInvalidComponent

protected void killInvalidComponent()

This method is called when an exception other than NonFatalStateTransitionException is thrown from a component's lifecycle method which signals that the component is corrupt and should be destroyed.

Override this method to change what happens to a component if it fails to transition state.

callComponentStart

private void callComponentStart()

Calls component's lifecycle method. Manages state transitions from entry state to interim state. It will also return the component to its entry state if a NonFatalStateTransitionException is caught.

callComponentStop

private void callComponentStop()

Calls component's lifecycle method. Manages state transitions from entry state to interim state. It will also return the component to its entry state if a NonFatalStateTransitionException is caught.

callComponentConfigure

private void callComponentConfigure(ComponentConfiguration configuration)

Calls component's lifecycle method. Manages state transitions from entry state to interim state, suspending or resuming as necessary. It will also return the component to its last good state (RUNNING or SUSPENDED depending on where the exception was thrown) if a NonFatalStateTransitionException is caught.

Parameters:

configuration - configuration for this component that will be passed to its lifecycle method

callComponentSuspend

private void callComponentSuspend()

Calls component's lifecycle method. Manages state transitions from entry state to interim state. It will also return the component to its entry state if a NonFatalStateTransitionException is caught.

callComponentResume

private void callComponentResume()

Calls component's lifecycle method. Manages state transitions from entry state to interim state. It will also return the component to its entry state if a NonFatalStateTransitionException is caught.