alma.ACS.MasterComponentImpl

Class MasterComponentImplBase

java.lang.Object

alma.acs.component.ComponentImplBase

alma.ACS.impl.CharacteristicComponentImpl

alma.ACS.MasterComponentImpl.MasterComponentImplBase

All Implemented Interfaces:

ComponentLifecycle, AcsStateChangeListener, PrioritizedExecutor

public abstract class MasterComponentImplBase
extends CharacteristicComponentImpl
implements AcsStateChangeListener

Base class for subsystem master components.

Each ALMA subsystem ('subsystem' in its technical meaning) must provide such a master component for administrational purposes. It's strongly recommended to do this in Java and use MasterComponentImplBase as the base class for the component implementation.

This class provides the transition logic for the various states. Subclasses only need to implement the actions for the various transitions or, more accurately, for the activity states. (see method getActionHandler; as an example, please see TestMasterComponent.

Author:

hsommer created Mar 16, 2004 3:02:37 PM

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	MasterComponentImplBase.DefaultResourceErrorHandler<T> [ miscellaneous ]

Field Summary

Fields inherited from class alma.ACS.impl.CharacteristicComponentImpl

characteristicModelImpl, properties

Fields inherited from class alma.acs.component.ComponentImplBase

m_containerServices, m_instanceName, m_logger

Constructor Summary

Constructors

Constructor and Description
MasterComponentImplBase()

Method Summary

Modifier and Type	Method and Description
void	cleanUp() Master component subclasses must call super.cleanUp() if they override this method!
ROstringSeq	currentStateHierarchy()
void	doTransition(SubsystemStateEvent event) Dispatches the event to the corresponding state machine method.
protected abstract AlmaSubsystemActions	getActionHandler() Subsystem state machine actions, to be implemented by concrete subclasses.
void	initialize(ContainerServices containerServices) Master component subclasses must call super.initialize() if they override this method!
protected void	monitorComponent(ACSComponent component) Subclasses can request to have the "health" of a given subsystem component monitored, and that the mastercomponent state be set to "Error" in case problems are detected with this component.
protected <T extends ACSComponent> void	monitorComponent(T component, SubsysResourceMonitor.ResourceErrorHandler<T> err) Subclasses can request to have the "health" of a given subsystem component monitored, and that the provided ResourceErrorHandler be called in case problems are detected.
protected void	monitorPingableResource(PingableResourceOperations resource, java.lang.String name) Like monitorComponent(ACSComponent) but for objects implementing the PingableResource interface.
protected <T extends PingableResourceOperations> void	monitorPingableResource(T resource, java.lang.String name, SubsysResourceMonitor.ResourceErrorHandler<T> err) Like #monitorComponent() but for objects implementing the PingableResource interface.
protected <T> void	monitorResource(SubsysResourceMonitor.ResourceChecker<T> checker, SubsysResourceMonitor.ResourceErrorHandler<T> err, int monitorDelaySeconds) Subclasses can request to have the "health" of a given subsystem component monitored, and that the provided ResourceErrorHandler be called in case problems are detected.
void	stateChangedNotify(AcsState[] oldStateHierarchy, AcsState[] currentStateHierarchy) Will be called by the state machine implementation for every state change.
protected void	stopMonitoringAllResources() Stops monitoring all resources that have been previously submitted for monitoring.
protected void	stopMonitoringResource(java.lang.String resourceName) Stops monitoring a resource.
void	updateStateHierarchy() Sets the property value of currentStateHierarchy to match the current (sub-)states from the state machine.

Methods inherited from class alma.ACS.impl.CharacteristicComponentImpl

descriptor, execute, find_characteristic, get_all_characteristics, get_characteristic_by_name, getComponentContainerServices, registerProperty, unregisterProperty

Methods inherited from class alma.acs.component.ComponentImplBase

aboutToAbort, componentState, execute, name

Methods inherited from class java.lang.Object

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

Constructor Detail

MasterComponentImplBase

public MasterComponentImplBase()

Method Detail

initialize

public void initialize(ContainerServices containerServices)
                throws ComponentLifecycleException

Master component subclasses must call super.initialize() if they override this method!

Specified by:

initialize in interface ComponentLifecycle

Overrides:

initialize in class CharacteristicComponentImpl

Parameters:

containerServices - callback object for services provided by the container

Throws:

ComponentLifecycleException

See Also:

ComponentLifecycle.initialize(alma.acs.container.ContainerServices)

cleanUp

public void cleanUp()
             throws AcsJComponentCleanUpEx

Master component subclasses must call super.cleanUp() if they override this method!

Specified by:

cleanUp in interface ComponentLifecycle

Overrides:

cleanUp in class CharacteristicComponentImpl

Throws:

AcsJComponentCleanUpEx

See Also:

CharacteristicComponentImpl.cleanUp()

currentStateHierarchy

public final ROstringSeq currentStateHierarchy()

See Also:

alma.ACS.MasterComponentOperations#currentStateHierarchy(), updateStateHierarchy()

doTransition

public final void doTransition(SubsystemStateEvent event)
                        throws IllegalStateEventEx

Dispatches the event to the corresponding state machine method.

Relies on CORBA to queue concurrent calls, which this synchronized implementation forcefully serializes. Note that calls should always return quickly, since the real work is done asynchronously in activity states.

Throws:

IllegalStateEventEx

See Also:

alma.ACS.MasterComponentOperations#doTransition(alma.ACS.MasterComponentPackage.SubsystemStateEvent)

getActionHandler

protected abstract AlmaSubsystemActions getActionHandler()

Subsystem state machine actions, to be implemented by concrete subclasses.

monitorComponent

protected final void monitorComponent(ACSComponent component)

Subclasses can request to have the "health" of a given subsystem component monitored, and that the mastercomponent state be set to "Error" in case problems are detected with this component. It is then the responsibility of the operator or some other external actor to get the mastercomponent out of this error state again. In other words, this method helps to detect problems, but does not fix the problem itself.

Detected problems can be

1. the component can not be reached at all within 10 seconds, or
2. the method componentState returns a state other than OPERATIONAL.

Note that this is a simplified version of #monitorComponent(ACSComponent, ComponentErrorHandler) and does not require the subclass to provide an error handler.

Before a resource gets unloaded/released etc, its monitoring should be stopped to avoid false errors, using stopMonitoringResource(String) or stopMonitoringAllResources().

Since:

ACS 6.0

monitorComponent

protected final <T extends ACSComponent> void monitorComponent(T component,
                                                               SubsysResourceMonitor.ResourceErrorHandler<T> err)

Subclasses can request to have the "health" of a given subsystem component monitored, and that the provided ResourceErrorHandler be called in case problems are detected.

Unlike method monitorComponent(ACSComponent), this method gives full control over the reaction to a detected failure. The master component can thus ignore or try to fix the problem, or eventually also go to error state (by calling doTransition(SubsystemStateEvent.SUBSYSEVENT_ERROR)).

Before a resource gets unloaded/released etc, its monitoring should be stopped to avoid false errors, using stopMonitoringResource(String) or stopMonitoringAllResources().

Parameters:

component - the component that should be monitored

err - a custom error handler. If null, then a default error handler will be used, and the master component will go to error state automatically (same as using monitorComponent(ACSComponent)).

Since:

ACS 6.0

monitorPingableResource

protected final void monitorPingableResource(PingableResourceOperations resource,
                                             java.lang.String name)

Like monitorComponent(ACSComponent) but for objects implementing the PingableResource interface.

Parameters:

resource - the resource that should be monitored

Since:

ACS 7.0

monitorPingableResource

protected final <T extends PingableResourceOperations> void monitorPingableResource(T resource,
                                                                                    java.lang.String name,
                                                                                    SubsysResourceMonitor.ResourceErrorHandler<T> err)

Like #monitorComponent() but for objects implementing the PingableResource interface.

Parameters:

resource - the resource that should be monitored

err - a custom error handler. If null, then a default error handler will be used, and the master component will go to error state automatically (same as using #monitorPingableResource(PingableResourceOperations)).

Since:

ACS 7.0

monitorResource

protected final <T> void monitorResource(SubsysResourceMonitor.ResourceChecker<T> checker,
                                         SubsysResourceMonitor.ResourceErrorHandler<T> err,
                                         int monitorDelaySeconds)

Subclasses can request to have the "health" of a given subsystem component monitored, and that the provided ResourceErrorHandler be called in case problems are detected.

Compared with the methods that allow monitoring a component, this method offers more flexibility: any kind of resource can be monitored, for which a custom ResourceChecker must be provided. Examples of resources include an "offshoot" remote object, a database, or a standalone-process such as Tomcat.

This method also takes the delay between monitor calls as a parameter, to allow adjusting the frequency of monitor calls on a per resource basis. Invalid values will result in the default delay being used.

Before a resource gets unloaded/released etc, its monitoring should be stopped to avoid false errors, using stopMonitoringResource(String) or stopMonitoringAllResources().

Type Parameters:

T - The resource type. Used to enforce matching checker and error handler.

Parameters:

checker - The checker that encapsulates the specifics of the methods to be checked. Must not be null.

err - A custom error handler. If null, then a default error handler will be used, and the master component will go to error state automatically (see comment for method monitorComponent(ACSComponent).

monitorDelaySeconds - The delay between two check calls. If monitorDelaySeconds < 1 then the default delay of 10 seconds will be used.

Since:

ACS 6.0

stopMonitoringResource

protected final void stopMonitoringResource(java.lang.String resourceName)

Stops monitoring a resource. It is important to stop monitoring resources before they get released, for example when shutting down.

See Also:

monitorComponent(ACSComponent), monitorComponent(ACSComponent, alma.ACS.MasterComponentImpl.SubsysResourceMonitor.ResourceErrorHandler), monitorResource(alma.ACS.MasterComponentImpl.SubsysResourceMonitor.ResourceChecker, alma.ACS.MasterComponentImpl.SubsysResourceMonitor.ResourceErrorHandler, int), stopMonitoringAllResources()

stopMonitoringAllResources

protected final void stopMonitoringAllResources()

Stops monitoring all resources that have been previously submitted for monitoring.

See Also:

stopMonitoringResource(String)

stateChangedNotify

public void stateChangedNotify(AcsState[] oldStateHierarchy,
                               AcsState[] currentStateHierarchy)

Will be called by the state machine implementation for every state change.

Normally you should not overload this method; if you do, make sure to call updateStateHierarchy() so that the state change propagates to the field which is visible from the outside of this component.

Specified by:

stateChangedNotify in interface AcsStateChangeListener

See Also:

alma.ACS.MasterComponentImpl.statemachine.AcsStateChangeListener#stateChangedNotify(alma.ACS.MasterComponentImpl.statemachine.AcsState[], alma.ACS.MasterComponentImpl.statemachine.AcsState[])

updateStateHierarchy

public void updateStateHierarchy()
                          throws AcsJException

Sets the property value of currentStateHierarchy to match the current (sub-)states from the state machine.

This method should not be overloaded by subclasses! We just don't make it final to meet special testing needs.

Throws:

AcsJException