RtjAocsFramework.ModeManagement
Class ModeManager

java.lang.Object
  |
  +--RtjAocsFramework.BasicObjects.RootObject
        |
        +--RtjAocsFramework.BasicObjects.AocsObject
              |
              +--RtjAocsFramework.ModeManagement.ModeManager

All Implemented Interfaces:

Configurable, Monitorable, Resettable, Telemeterable

Direct Known Subclasses:

AocsMissionModeManager, CyclingModeManager, FollowerModeManager

public class ModeManager

extends AocsObject

implements Monitorable

This class encapsulates a core mode manager and acts as base class for all mode managers.

Althugh it is not possible to give a generic implementation of a mode manager (because the mode switching logic is highly application specific and because the number and type of strategies vary across mode managers), there are some functionalities that are common to all mode managers and that are gathered in class ModeManager. This class models a core mode manager that has no mode switching logic (mode changes occur only in response to external commands) and that handles strategies as references to the basic type RootObject.

The core mode manager implements the following functionalities: 1) control of mode changes (overriding of autonomous mode changes, constraining of autonomous mode changes, etc); 2) generation of mode events in response to mode changes; 3) management of the implementers for the mode strategies.

Instances of ModeManager cannot be used as mode managers for framework components because they do not have any mode switching logic and should not be used for this purpose because they handle implementers as objects of generic type RootObject which would require users to perform potentially dangerous downcasts to the actual type of the implementers. Concrete mode managers are obtained by subclassing ModeManager and adding the following: 1) mode switching logic; 2) casting operations to allow the user of the mode managers to see the type of the implementers.

Mode switches can be either triggered by an external commands (through method setMode) or they can be initiated autonomously by the mode manager itself (for instance, in response to the reception of an event). In the latter case, the logic for autonomous mode switches should be placed in method updateMode(). Subclasses of ModeManager that choose this approach should therefore override updateMode().

Mode managers are monitorable objects which expose their mode as a monitorable property. Other objects interested in monitoring the mode property using the "monitoring through change notification change pattern" can register their interest in the property together with the change profile aginst which the monitoring should be performed.

Mode managers act as event sources. They fire a mode event whenever there is a mode change and they fire a change event whenever their mode property violates the change profile specified by a registered monitor.

Copyright: see the Copyright Notice.

Version:

1.0

Author:

Alessandro Pasetti (University of Konstanz)

See Also:

The Operational Mode Framelet Document., ModeEvent

Field Summary

protected int	currentMode
protected int	nModes
protected int	nStrategies

Fields inherited from interface RtjAocsFramework.TelemetryManagement.Telemeterable

DEBUG_TM, LONG_TM, NORMAL_TM, NTMFORMATS, SHORT_TM

Constructor Summary

protected	ModeManager() Default constructor: the object should not be used before being initialized.
protected	ModeManager(int nModes, int nStrategies, int defaultMode, int numberOfListeners) This class cannot be directly instantiated.

Method Summary

void	addChangeListener(ChangeListener l) Initialization method to register listeners to change events.
void	addModeListener(ModeListener l) Initialization method to register listeners to mode events.
protected void	changeMode(int targetMode) Change the current mode to the target mode (if mode transitions are enabled and if the target mode is enabled).
void	disableMode(int mode) Disable transitions to mode 'mode'
void	enableMode(int mode) Enable transitions to mode 'mode'
protected void	fireChangeEvent(short eventTypeId, ChangeObject changeObject, double lastValue) Fire a change event to all registered listeners.
protected void	fireModeEvent(short eventTypeId, int oldMode, int newMode) Fire a mode event to all registered listeners.
void	forceMode(int newMode) This method sets the current mode to newMode and inhibits further autonomous mode changes.
AocsObject	getAocsObject() Return the property owner as an instance of type AocsObject.
int	getDefaultMode() Return the default operational mode.
RootObject	getImplementer(int strategy) Return the implementer corresponding to the current mode for strategy 'strategy'.
int	getMode() Return the current mode.
ModeChangeAction	getModeChangeAction()
double	getMonitorablePropertyValue(int i) Return the mode indicator as a float.
int	getNumberOfModes() Return the number of operational modes.
int	getNumberOfMonitorableProperties() Return the total number of monitorable properties exposed by the object.
int	getTelemetryImageLength() Return the length (in bits) of the telemetry image of the object.
boolean	isConfigured() Return false if some configuration data are missing.
protected boolean	isModeLegal(int mode) Check if the argument mode is legal.
void	loadImplementer(int mode, int strategy, RootObject implementer) This method loads the implementer for the strategy 'strategy' in mode 'mode'.
protected void	notifyMonitors(int newMode) The operational mode is a monitorable property.
void	releaseMode() Release the inhibition on autonomous mode changes that is caused by a call to forceMode.
void	removeChangeListener(ChangeListener l) Initialization method to unregister change event listeners.
void	removeModeListener(ModeListener l) Initialization method to unregister mode event listeners.
void	reset() Set the mode to the default mode and enable all mode transitions.
void	resetConfiguration() Unload all implementers, all mode event listeners and the mode change action.
void	setDefaultMode(int n) Initialization method to set the default mode and to put the mode manager in default mode.
void	setMaxNumberOfChangeListeners(int n) Initialization method to set the maximum number of listeners to change events.
void	setMaxNumberOfModeListeners(int n) Initialization method to set the maximum number of listeners to mode events.
void	setMode(int newMode) This method sets the current mode to newMode without however inhibiting further autonomous mode changes.
void	setModeChangeAction(ModeChangeAction m)
void	setNumberOfModes(int n) Initialization mode to set the number of strategies.
void	setNumberOfStrategies(int n) Initialization method to set the number of strategies.
void	setPropertyMonitorListSize(int n) Initialization method to set the maximum number of monitors for the mode property.
protected void	updateMode() This method implements the logic for an autonomous mode switch.
void	writeToTelemetry(TelemetryStream tmStream) Direct the object to write its own state to the telemetry stream.

Methods inherited from class RtjAocsFramework.BasicObjects.AocsObject

addConfigurationListener, addFailureListener, finalize, getAocsClock, getConfigurationListenerList, getCycle, getDestructionRecoveryAction, getFailureListenerList, getSystemManager, getTelemetryFormat, getTime, removeConfigurationListener, removeFailureListener, reportConfigurationEvent, reportFailure, resetStaticConfiguration, setAocsClock, setDestructionRecoveryAction, setMaxNumberOfConfigurationListeners, setMaxNumberOfFailureListeners, setSystemManager, setTelemetryFormat

Methods inherited from class RtjAocsFramework.BasicObjects.RootObject

getClassId, getInstanceId, setClassId

Methods inherited from class java.lang.Object

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

Field Detail

nStrategies

protected int nStrategies

nModes

protected int nModes

currentMode

protected int currentMode

Constructor Detail

ModeManager

protected ModeManager(int nModes,
                      int nStrategies,
                      int defaultMode,
                      int numberOfListeners)

This class cannot be directly instantiated.

Parameters:

nModes - number of modes managed by the mode manager

nStrategies - number of strategies associated to each mode

defaultMode - default mode upon creation and after reset

numberOfListeners - maximum number of listeners to mode events

ModeManager

protected ModeManager()

Default constructor: the object should not be used before being initialized. Initialization is performed by setting the number of modes, the number of strategies, the default mode, the maximum number of mode event and change event listeners, the maximum number of property monitors and the mode change action.

Method Detail

setNumberOfModes

public void setNumberOfModes(int n)

Initialization mode to set the number of strategies. Attempts to call it more than once will result in a configuration error being generated.

setNumberOfStrategies

public void setNumberOfStrategies(int n)

Initialization method to set the number of strategies. Attempts to call it more than once will result in a configuration error being generated.

setDefaultMode

public void setDefaultMode(int n)

Initialization method to set the default mode and to put the mode manager in default mode. This method should only be called after the initialization modes to set the number of modes and number of strategies have been called.

setMaxNumberOfModeListeners

public void setMaxNumberOfModeListeners(int n)

Initialization method to set the maximum number of listeners to mode events. Attempts to call it more than once will result in a configuration error being generated.

setMaxNumberOfChangeListeners

public void setMaxNumberOfChangeListeners(int n)

Initialization method to set the maximum number of listeners to change events. Attempts to call it more than once will result in a configuration error being generated.

setPropertyMonitorListSize

public void setPropertyMonitorListSize(int n)

Initialization method to set the maximum number of monitors for the mode property. This method should only be called once. Attempts to call it more than once will result in a configuration error event being generated.

Parameters:

n - is a size of the property monitor list

changeMode

protected void changeMode(int targetMode)

Change the current mode to the target mode (if mode transitions are enabled and if the target mode is enabled). The change mode actions are executed just prior to and after performing the mode change. If the target mode is different from the current mode, then a mode event is fired. After the mode has been changed, it is verified if any monitors who have registered their interest in the mode property need to be verified.

fireModeEvent

protected void fireModeEvent(short eventTypeId,
                             int oldMode,
                             int newMode)

Fire a mode event to all registered listeners. The mode event records a change of mode from oldMode to newMode.

fireChangeEvent

protected void fireChangeEvent(short eventTypeId,
                               ChangeObject changeObject,
                               double lastValue)

Fire a change event to all registered listeners. The event records a change in the mode property exposed by the manoeuvre object.

Parameters:

eventTypeId - the event type identifier

changeObject - the change object through which the propoerty value was passed and that triggered the property change

lastValue - the most recent value of the property that underwent the change

notifyMonitors

protected void notifyMonitors(int newMode)

The operational mode is a monitorable property. After a mode change, the mode manager is responsible for notifying any registered property monitors of the change. This notification is carried out by firing a change event and by invoking the monitor's propertyChange method.

Parameters:

newMode - is the new operational mode

updateMode

protected void updateMode()

This method implements the logic for an autonomous mode switch. In class ModeManager it has a trivial implementation that returns withour taking any actions. Concrete mode managers that are obtained by subclassing ModeManager must provide their own implementation.

Class ModeManager does not define when updateMode() is called. In general, three possibilities can be recognized:

1) On-Call Mode Update : the method is called whenever getImplementer() is called and mode switches only take place when the client of the mode manager requires a new implementation for one of its strategies. In this case, updateMode is called from within getImplementer().

2) Reactive Mode Update : the mode manager changes its mode in response to the arrival of an event. In this case updateMode is called by the event processing method.

3) Periodic Mode Update : the mode switching logic is triggered at regular intervals. This is best realized by making the mode manager an active object. Method updateMode is then called from within method runOnceCyle().

The framework provides two components encapsulating default mode switching logic: the cycling mode manager, and the follower mode manager.

Implementers of updateMode should use method changeMode to perform the mode change.

See Also:

CyclingModeManager, FollowerModeManager

isModeLegal

protected boolean isModeLegal(int mode)

Check if the argument mode is legal. The mode is legal if it lies in the range [0..n-1] where n is the number of modes.

loadImplementer

public void loadImplementer(int mode,
                            int strategy,
                            RootObject implementer)

This method loads the implementer for the strategy 'strategy' in mode 'mode'. The implementer is treated as a reference to an object of generic type RootObject.

setMode

public void setMode(int newMode)

This method sets the current mode to newMode without however inhibiting further autonomous mode changes. The mode change is performed using method changeMode.

See Also:

changeMode(int)

forceMode

public void forceMode(int newMode)

This method sets the current mode to newMode and inhibits further autonomous mode changes. The mode change is performed using method changeMode.

See Also:

changeMode(int)

releaseMode

public void releaseMode()

Release the inhibition on autonomous mode changes that is caused by a call to forceMode.

See Also:

forceMode(int)

disableMode

public void disableMode(int mode)

Disable transitions to mode 'mode'

enableMode

public void enableMode(int mode)

Enable transitions to mode 'mode'

getImplementer

public RootObject getImplementer(int strategy)

Return the implementer corresponding to the current mode for strategy 'strategy'.

resetConfiguration

public void resetConfiguration()

Unload all implementers, all mode event listeners and the mode change action.

Specified by:

resetConfiguration in interface Configurable

Overrides:

resetConfiguration in class AocsObject

isConfigured

public boolean isConfigured()

Description copied from interface: Configurable

Return false if some configuration data are missing.

Typically, a false value indicates that a plug-in component is missing or that the object has not been initialized. This is a negative check only: a return value of true cannot guarantee that the object is correctly configured.

Calls to resetConfiguration on an object A are normally not propagated objects of type AocsObject that are contained or otherwise aggregated to A. The rationale for this policy is that all objects of type AocsObject implement interface configurable and therefore their configuration status should be checked externally (probably through the configuration check service of the system manager).

Specified by:

isConfigured in interface Configurable

Overrides:

isConfigured in class AocsObject

reset

public void reset()

Set the mode to the default mode and enable all mode transitions.

Specified by:

reset in interface Resettable

Overrides:

reset in class AocsObject

writeToTelemetry

public void writeToTelemetry(TelemetryStream tmStream)

Description copied from interface: Telemeterable

Direct the object to write its own state to the telemetry stream.

Specified by:

writeToTelemetry in interface Telemeterable

Overrides:

writeToTelemetry in class AocsObject

getTelemetryImageLength

public int getTelemetryImageLength()

Description copied from interface: Telemeterable

Return the length (in bits) of the telemetry image of the object. This method is useful to verify that the quantity of data generated by a given object is compatible with the capacity of the telemetry channel.

Specified by:

getTelemetryImageLength in interface Telemeterable

Overrides:

getTelemetryImageLength in class AocsObject

getMode

public int getMode()

Return the current mode.

getNumberOfModes

public int getNumberOfModes()

Return the number of operational modes.

getDefaultMode

public int getDefaultMode()

Return the default operational mode.

setModeChangeAction

public void setModeChangeAction(ModeChangeAction m)

getModeChangeAction

public ModeChangeAction getModeChangeAction()

addModeListener

public void addModeListener(ModeListener l)

Initialization method to register listeners to mode events.

removeModeListener

public void removeModeListener(ModeListener l)

Initialization method to unregister mode event listeners.

addChangeListener

public void addChangeListener(ChangeListener l)

Initialization method to register listeners to change events.

removeChangeListener

public void removeChangeListener(ChangeListener l)

Initialization method to unregister change event listeners.

getAocsObject

public AocsObject getAocsObject()

Description copied from interface: Monitorable

Return the property owner as an instance of type AocsObject.

Specified by:

getAocsObject in interface Monitorable

getMonitorablePropertyValue

public double getMonitorablePropertyValue(int i)

Return the mode indicator as a float. Mode managers only expose a single monitorable property and this method always return the mode indicator regardless of the value of argument i. Attempts to access the property values with i greater than 0 will result in the generation of a failure event.

Specified by:

getMonitorablePropertyValue in interface Monitorable

See Also:

Monitorable

getNumberOfMonitorableProperties

public int getNumberOfMonitorableProperties()

Description copied from interface: Monitorable

Return the total number of monitorable properties exposed by the object.

Specified by:

getNumberOfMonitorableProperties in interface Monitorable