de.cau.cs.kieler.sim.kiem.internal
Class AbstractDataComponent

java.lang.Object
  extended by de.cau.cs.kieler.sim.kiem.internal.AbstractDataComponent
All Implemented Interfaces:
IDataComponent, IExecutableExtension
Direct Known Subclasses:
JSONObjectDataComponent, JSONStringDataComponent

public abstract class AbstractDataComponent
extends Object
implements IDataComponent, IExecutableExtension

The DataComponent class implements the basic behavior of a data observer and/or data producer component. Implemented components may want to override some of the here provided methods.

Rating yellow
(2009-01-15)

Field Summary
static int MASTER_CMD_MACROSTEP
          The Constant to imitate a user macro step command.
static int MASTER_CMD_PAUSE
          The Constant to imitate a user pause command.
static int MASTER_CMD_RUN
          The Constant to imitate a user run command.
static int MASTER_CMD_STEP
          The Constant to imitate a user step command.
static int MASTER_CMD_STEPBACK
          The Constant to imitate a user step command.
static int MASTER_CMD_STOP
          The Constant to imitate a user stop command.
 
Constructor Summary
AbstractDataComponent()
          Constructor initializes the properties with the provideProperties() provideProperties method that may be overridden by the component.
 
Method Summary
 void checkProperties(KiemProperty[] propertiesParam)
          This method is intended to check if the properties are set correctly.
 void finalize()
          finalize() is a destructor of the DataComponent that is called by the execution manager before the DataComponent instance is removed from the list.
 IConfigurationElement getConfigurationElement()
          Gets the configuration element.
 String getCurrentComponentID()
           
 String getDataComponentId()
          Gets the String representation id of a DataComponent.
 String getName()
          Gets the name of the component which is defined in the extension point.
 String getPluginId()
          Gets the component's plug-in ID.
 KiemProperty[] getProperties()
          Returns the properties associated with this component.
 Shell getShell()
          Getter for the main shell of the active workbench.
 boolean isDeltaObserver()
          Checks if component is a delta observer.
 boolean isHistoryObserver()
          Flags that this component can handle past, already computed history values.
 boolean isHistoryStep()
          Checks if the current step is a history step.
 boolean isInvisible()
          If the component doesn't want to appear in the scheduling list, it may set this flag to true.
 boolean isMacroStepDone()
          Checks if is a macro step is done.
 boolean isMaster()
          Override this, if this DataComponent is a master.
If it returns true then
1.
 boolean isMasterImplementingGUI()
          Override this if the DataComponents implements the GUI buttons by itself.
 boolean isMultiInstantiable()
          Flag that this component can be run multible times in different threads.
 void masterCommand(int command)
          If this is component is a master it can control the execution using this method.
 int masterGetAimedStepDuration()
          If this component is a master it can get the aimed step duration.
 void masterGUI(int command)
          If this is component is a master and implements the GUI it must react to user button hits.

The command can be either:
MASTER_CMD_STEP for the step button
MASTER_CMD_MACROSTEP for the macro step button
MASTER_CMD_RUN for the run button
MASTER_CMD_PAUSE for the pause button
MASTER_CMD_STOP for the stop button
MASTER_CMD_STEPBACK for the back step button

 boolean masterGUIisEnabled(int command)
          If this is component is a master and implements the GUI it must tell KIEM when user buttons are enabled/disabled.
 boolean masterIsPaused()
          If this component is a master it can detect whether the execution is currently paused.
 boolean masterIsRunning()
          If this component is a master it can detect whether the execution is currently running.
 void masterSetAimedStepDuration(int aimedStepDuration)
          If this component is a master it can set the aimed step duration.
 void masterSetKIEMInstance(KiemPlugin kIEMInstanceParam)
          This method is called from the ExecutionManager only iff isMaster() returns true!

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!
 void notifyEvent(KiemEvent event)
          This is the basic notify method that is called by KIEM whenever an event occurs for which this DataComponent is registered (see provideEventOfInterest()).
 KiemEvent provideEventOfInterest()
          Return a KiemEvent type (integer value) that represents a number of events this component wants to listen to.

A KiemEvent can be a combination of several events.
 String[] provideFilterKeys()
          If this DataComponent implements an observer, provide some key's of interest.
 KiemProperty[] provideProperties()
          Provide properties for this component.
 void setConfigurationElemenet(IConfigurationElement configEleParam)
          Sets the configuration element.
 void setCurrentComponentID(String currentComponentIDParam)
           
 void setHistoryStep(boolean historyStepParam)
          Sets the history step flag.
 void setInitializationData(IConfigurationElement config, String propertyName, Object data)
          
 void setProperties(KiemProperty[] propertiesParam)
          Sets the properties.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface de.cau.cs.kieler.sim.kiem.IDataComponent
initialize, isObserver, isProducer, wrapup
 

Field Detail

MASTER_CMD_RUN

public static final int MASTER_CMD_RUN
The Constant to imitate a user run command.

See Also:
Constant Field Values

MASTER_CMD_PAUSE

public static final int MASTER_CMD_PAUSE
The Constant to imitate a user pause command.

See Also:
Constant Field Values

MASTER_CMD_STOP

public static final int MASTER_CMD_STOP
The Constant to imitate a user stop command.

See Also:
Constant Field Values

MASTER_CMD_STEP

public static final int MASTER_CMD_STEP
The Constant to imitate a user step command.

See Also:
Constant Field Values

MASTER_CMD_MACROSTEP

public static final int MASTER_CMD_MACROSTEP
The Constant to imitate a user macro step command.

See Also:
Constant Field Values

MASTER_CMD_STEPBACK

public static final int MASTER_CMD_STEPBACK
The Constant to imitate a user step command.

See Also:
Constant Field Values
Constructor Detail

AbstractDataComponent

public AbstractDataComponent()
Constructor initializes the properties with the provideProperties() provideProperties method that may be overridden by the component. It sets the properties to null in the default case to indicate that the DataComponent has no properties.

Method Detail

getShell

public Shell getShell()
Getter for the main shell of the active workbench.

Returns:
the active shell

getDataComponentId

public String getDataComponentId()
Gets the String representation id of a DataComponent. The id will be constituted by getting the pluginID and adding information about the implemented extension point, i.e., the property types and names and the type of DataProducer. Note that this class can be overridden if the implementation wants to provide its own identification.

Returns:
the id as a String

setProperties

public final void setProperties(KiemProperty[] propertiesParam)
Sets the properties. This method is needed to modify properties after deserialization.

Parameters:
propertiesParam - the new KiemProperty[] array

setConfigurationElemenet

public final void setConfigurationElemenet(IConfigurationElement configEleParam)
Sets the configuration element. This method is needed to instantiate several component instances only.

Parameters:
configEleParam - the new configuration element

getConfigurationElement

public final IConfigurationElement getConfigurationElement()
Gets the configuration element. This method is needed to instantiate several component instances only.

Returns:
the configuration element

getPluginId

public final String getPluginId()
Gets the component's plug-in ID.

Returns:
the plug-in ID

setInitializationData

public final void setInitializationData(IConfigurationElement config,
                                        String propertyName,
                                        Object data)
                                 throws CoreException

Specified by:
setInitializationData in interface IExecutableExtension
Throws:
CoreException

getName

public final String getName()
Gets the name of the component which is defined in the extension point.

Returns:
the name of the DataComponent

isMultiInstantiable

public boolean isMultiInstantiable()
Flag that this component can be run multible times in different threads. Overwrite this if this component is explicitly multi instantiable ONLY! note that you have to consider thread safety here because all instances will be run in a different (and hence concurrent) thread be aware of this for example if you share a common view etc.

Returns:
a boolean indicating that the component is multi threadable

isInvisible

public boolean isInvisible()
If the component doesn't want to appear in the scheduling list, it may set this flag to true. This implies that the specific component then cannot be added or removed.

Returns:
true, if is invisible

provideFilterKeys

public String[] provideFilterKeys()
If this DataComponent implements an observer, provide some key's of interest. If you use null then no filter is being used and the component will get all values.

As an example one could use the following code if the component is only interested in values with the (top-)key "state" and "emergency":

public String[] provideFilterKeys() {
String[] myFilter = {"state","emergency"};
return myFilter;
}

Returns:
a String array with the keys of interest or null for "no filter"

getProperties

public final KiemProperty[] getProperties()
Returns the properties associated with this component. These are set in the constructor and may be overridden by provideProperties().

Returns:
KiemProperty[] array of properties

provideProperties

public KiemProperty[] provideProperties()
Provide properties for this component. The component may create and publicize its properties with this method. They will be set/modified by the execution manager during the user edits them. Whenever the user decides to run/start the execution the properties are tested (see below) and the component may use there settings.

The following lists a simple example for such properties:
\ATOverride
public KiemProperty[] provideProperties() {
KiemProperty[] properties = new KiemProperty[7];
properties[0] = new KiemProperty(
"state name",
"state");
properties[1] = new KiemProperty(
"some bool",
true);
properties[2] = new KiemProperty(
"an integer",
2);
properties[3] = new KiemProperty(
"a file",
new KiemPropertyTypeFile(),
"c:/nothing.txt");
String[] items = {"trace 1","trace 2", "trace 3", "trace 4"};
properties[4] = new KiemProperty(
"a choice",
new KiemPropertyTypeChoice(items),
items[2]);
properties[5] = new KiemProperty(
"workspace file",
new KiemPropertyTypeWorkspaceFile(),
"/nothing.txt");
properties[6] = new KiemProperty(
"editor",
new KiemPropertyTypeEditor(),
"");
return properties;
}

These are built-in types that can always be extended using the KiemProperty class.

Returns:
the KiemProperty[] or null if no properties are provided

checkProperties

public void checkProperties(KiemProperty[] propertiesParam)
                     throws KiemPropertyException
This method is intended to check if the properties are set correctly. Here a component may check for required and optional properties and their settings. Also an KiemPropertyError can be raised if some property prevents the execution of this component.

Parameters:
propertiesParam - the properties with the current user settings
Throws:
KiemPropertyException - if a property prevents the execution of this DataComponent this error should be thrown

isHistoryObserver

public boolean isHistoryObserver()
Flags that this component can handle past, already computed history values. Overwrite this if this component can explicitly handle past recorded history values.
In case the user makes steps back into the history, only observers that return true in this method will get any (recorded) history data. Components that return false (default) will not get any data, while the the user navigates within the recorded tick area.

Returns:
a boolean indicating that the component is recorded observer

setHistoryStep

public final void setHistoryStep(boolean historyStepParam)
Sets the history step flag. This is called by the execution manager to flag that the current step lies in history.

Parameters:
historyStepParam - the flag to set

isHistoryStep

public final boolean isHistoryStep()
Checks if the current step is a history step. This can be called by the component itself to check if the current step lies in history. If this is the case, any produced output data will not be considered. The DataComponent may implement special behavior in its step() method depending on the return value of this method.

Returns:
true, if is history step

isDeltaObserver

public boolean isDeltaObserver()
Checks if component is a delta observer. Delta values are all changed values that exist in the present tick (and in the past ticks when this component may have been skipped).
If a component wants all (accumulated & updated) values of the present tick, it should return false.

Example:

Step...........|..1..|..2..|..3..|..4..|..5..|
-----------------------------------------------------
Producer.......|..A..|../..|..B..|..C..|..D..|
-----------------------------------------------------
Observer.......|.A...|.skip|.skip|.ABC.|.ABCD|
-----------------------------------------------------
DeltaObserver..|.A...|.skip|.skip|.BC..|.D...|
-----------------------------------------------------

The above figure shows an execution of 5 steps with three participating DataComponents. One producer generates (different) data at steps 1, 3, 4, and 5. It does not produce any data in step 2. Both observers get skipped in steps 2 and 3 (e. g., because they might be a little slow). In step 1 both observers get the A data. Because there is no data in the pool, both inputs (their parameter values) are the same. In steps 2 and 3 both get skipped. Their step() method is not called in these steps. In step 4 the DeltaObserver gets only the B and the D data, produced in steps 3 and 4 (these are the delta values to the last time it was not skipped, i. e., step 1). The other observer gets the whole data of the pool, namely the A, B, and the C data. In step 5 the recently produced D data are the only ones that arrive at the DeltaObserver while the other observer gets all ever produced data A, B, C and D.

Returns:
true, if is delta observer

isMacroStepDone

public boolean isMacroStepDone()
Checks if is a macro step is done. Override this method to flag that a "macro tick" is not yet done during e.g., a fixed point semantics of a DataComponent.

In case ANY DataComponent raises this flag (by returning false) the KIEM GUI will display another icon "Macro Step Execution" that will perform as many steps until each DataComponent returns true (possibly an infinite number of steps) any following step should be interpreted as the beginning of a new macro step ALL DataComponents that already have flagged isStepDone == true will not be scheduled again during this MacroStep if you need them to update again they should also return a false value.

Also note that this method is ignored for pure Data Observers because there is blocking impact on the schedule from them.

NOTE: This method has not been implemented yet!

Returns:
true, if is macro step is done

isMaster

public boolean isMaster()
Override this, if this DataComponent is a master.
If it returns true then
1. ExecutionManager ensures that no other master is present
2. Calling stepExecution initializes a tick

ATTENTION: At most ONE DataComponent can be a Master!

Returns:
true, if is master

isMasterImplementingGUI

public boolean isMasterImplementingGUI()
Override this if the DataComponents implements the GUI buttons by itself. When this option returns false, then the component must implement the following methods:
masterGUIstep
masterGUImacrostep
masterGUIrun
masterGUIpause
masterGUIstop
masterGUIisEnabledStep
masterGUIisEnabledMacroStep
masterGUIisEnabledRun
masterGUIisEnabledPause
masterGUIisEnabledStop

Returns:
true, if component implements the GUI buttons

masterSetAimedStepDuration

public final void masterSetAimedStepDuration(int aimedStepDuration)
                                      throws KiemMasterException
If this component is a master it can set the aimed step duration.

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!

Parameters:
aimedStepDuration - the aimed step duration
Throws:
KiemMasterException - a KiemMasterException

masterGetAimedStepDuration

public final int masterGetAimedStepDuration()
                                     throws KiemMasterException
If this component is a master it can get the aimed step duration.

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!

Returns:
the aimed step duration set priorly
Throws:
KiemMasterException - a KiemMasterException

masterCommand

public final void masterCommand(int command)
                         throws KiemMasterException
If this is component is a master it can control the execution using this method.

The command can be either:
MASTER_CMD_STEP to make an execution step
MASTER_CMD_MACROSTEP to make a macro step
MASTER_CMD_RUN to run the execution
MASTER_CMD_PAUSE to pause the execution
MASTER_CMD_STOP to stop the execution
MASTER_CMD_STEPBACK to make back step

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!

Parameters:
command - the master command to process
Throws:
KiemMasterException - a KiemMasterException

masterIsPaused

public final boolean masterIsPaused()
                             throws KiemMasterException
If this component is a master it can detect whether the execution is currently paused.

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!

Returns:
true, if paused
Throws:
KiemMasterException - a KiemMasterException

masterIsRunning

public final boolean masterIsRunning()
                              throws KiemMasterException
If this component is a master it can detect whether the execution is currently running.

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!

Returns:
true, if running
Throws:
KiemMasterException - a KiemMasterException

masterSetKIEMInstance

public final void masterSetKIEMInstance(KiemPlugin kIEMInstanceParam)
This method is called from the ExecutionManager only iff isMaster() returns true!

ATTENTION: At most ONE DataComponent can be a Master! This method SHOULD NOT be overridden!

Parameters:
kIEMInstanceParam - the KIEM instance

masterGUI

public void masterGUI(int command)
If this is component is a master and implements the GUI it must react to user button hits.

The command can be either:
MASTER_CMD_STEP for the step button
MASTER_CMD_MACROSTEP for the macro step button
MASTER_CMD_RUN for the run button
MASTER_CMD_PAUSE for the pause button
MASTER_CMD_STOP for the stop button
MASTER_CMD_STEPBACK for the back step button

Parameters:
command - the command

masterGUIisEnabled

public boolean masterGUIisEnabled(int command)
If this is component is a master and implements the GUI it must tell KIEM when user buttons are enabled/disabled.

The command can be either:
MASTER_CMD_STEP for the step button
MASTER_CMD_MACROSTEP for the macro step button
MASTER_CMD_RUN for the run button
MASTER_CMD_PAUSE for the pause button
MASTER_CMD_STOP for the stop button
MASTER_CMD_STEPBACK for the back step button

Parameters:
command - the command
Returns:
true, if the specific button is enabled

finalize

public void finalize()
finalize() is a destructor of the DataComponent that is called by the execution manager before the DataComponent instance is removed from the list. If the DataComponent needs to free any resources immediately (e.g., closing socket streams) this can be done here.

Overrides:
finalize in class Object

provideEventOfInterest

public KiemEvent provideEventOfInterest()
Return a KiemEvent type (integer value) that represents a number of events this component wants to listen to.

A KiemEvent can be a combination of several events. The simplest way to register for two events that e.g., indicate a step-command and the save event is to have the following code:

public KiemEvent provideEventOfInterest() {
int[] events = {KiemEvent.CMD_STEP, KiemEvent.SAVE};
KiemEvent event = new KiemEvent(events);
System.out.println(event.getEventCodesAsList());
return (event);
} * }

NOTE: The provision of event types is only read by KIEM once before the execution starts. Hence, changes during the execution are not having any effect. In doubt, this method should return more events than needed. These could dynamically be ignored when temporarily not of interest.

Returns:
the KiemEvent type indicating the events of interest

notifyEvent

public void notifyEvent(KiemEvent event)
This is the basic notify method that is called by KIEM whenever an event occurs for which this DataComponent is registered (see provideEventOfInterest()).

Parameters:
event - the KiemEvent with additional attached information, depending on the specific event

setCurrentComponentID

public void setCurrentComponentID(String currentComponentIDParam)
Parameters:
currentComponentIDParam - the currentComponentID to set

getCurrentComponentID

public String getCurrentComponentID()
Returns:
the currentID