de.cau.cs.kieler.sim.kiem.internal
Class AbstractDataComponent
java.lang.Object
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

- (2009-01-15)
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 |
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. |
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 |
setHistoryStep(boolean historyStepParam)
Sets the history step flag. |
void |
setInitializationData(IConfigurationElement config,
String propertyName,
Object data)
|
void |
setProperties(KiemProperty[] propertiesParam)
Sets the properties. |
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
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.
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