public abstract class AlgorithmRTE extends HostSecurity
executeStep(int, AlgorithmStateAttachment)
,
createInitialState(AlgorithmState)
, storeState(AlgorithmState)
, restoreState(AlgorithmState)
,
rollBackStep(int, int)
and adoptState(int, AlgorithmState)
.executeStep(int, AlgorithmStateAttachment)
.
setExecSpeedFactor(float)
) to a greater/smaller
value than 1.0f
. Skip/ignore all breakpoints by using setSkipBreakpoints(boolean)
.
setMinStepDwellTime(long)
to specify the execution time that a step should have at least. This prevents from overrunning
steps especially if the user steps back in the algorithm.
addListener(RTEListener)
to add a RTEListener
to listen to runtime events like:
RTEListener.beforeStart(RTEvent)
)RTEListener.beforeResume(RTEvent)
)RTEListener.beforePause(RTEvent)
)RTEListener.onStop()
)HostSecurity.registerHost(lavesdk.algorithm.plugin.PluginHost)
. This must only be done by the host application!
setExerciseModeEnabled(boolean)
to change the mode of the runtime environment.
GuiJob
or a GuiRequest
.TextView
component that has a thread-unsafe setText(...)
method and a ListView
component
that has a thread-unsafe getEntry(...)
method
... protected void executeStep(int stepID, AlgorithmStateAttachment asa) throws Exception { ... switch(stepID) { case 3: // a step that changes a specific set // visualize the changed set but the setText()-method of the TextView is not thread-safe // so shift the call to the EDT EDT.execute(new GuiJob() { protected void execute() throws Throwable { textView.setText(set); } }); nextStepID = 4; break; case 7: // a step that has to modify an entry of a ListView component its getEntry() method is not thread-safe final Entry e = EDT.execute(new GuiRequest<Entry>() { protected Entry execute() throws Throwable { return listView.getEntry(index); } }); // modify the entry ... break; } return nextStepID; } ...
Constructor and Description |
---|
AlgorithmRTE(AlgorithmPlugin plugin,
AlgorithmText text)
Creates a new algorithm runtime environment.
|
AlgorithmRTE(AlgorithmPlugin plugin,
AlgorithmText text,
AlgorithmExerciseProvider provider)
Creates a new algorithm runtime environment.
|
Modifier and Type | Method and Description |
---|---|
void |
addListener(RTEListener listener)
Adds a new listener to listen to runtime events of the algorithm.
|
protected abstract void |
adoptState(int stepID,
AlgorithmState state)
Lets the algorithm adopt the given state.
|
protected abstract void |
createInitialState(AlgorithmState state)
Creates the initial state of the algorithm meaning the initial values of the variables
which are used in your algorithm.
|
protected abstract int |
executeStep(int stepID,
AlgorithmStateAttachment asa)
Executes a step of the algorithm.
|
float |
getExecSpeedFactor()
Gets the execution speed factor of the rte.
|
long |
getMinStepDwellTime()
Gets the minimal dwell time that a step must have.
|
boolean |
getPauseBeforeStop()
Indicates whether the runtime environment should be paused before it transitions into stop.
|
boolean |
getSkipBreakpoints()
Indicates if the breakpoints will currently be skipped/ignored.
|
protected abstract View[] |
getViews()
Gets the views that are used in the runtime environment to visualize the algorithm.
|
protected void |
hostAccepted()
Is invoked when the secured host is set meaning that
HostSecurity.getHost() returns a valid host. |
boolean |
isExerciseModeEnabled()
Indicates whether the exercise mode of the runtime environment is enabled.
|
boolean |
isRunning()
Indicates if the algorithm runtime environment is currently in running mode.
|
boolean |
isStarted()
Indicates if the runtime environment is started.
|
void |
nextStep()
Goes to the next step of the algorithm.
|
void |
pause()
Pauses the runtime environment of the algorithm until it is resumed by calling
start() . |
void |
prevStep()
Goes to the previous step of the algorithm.
|
void |
removeListener(RTEListener listener)
Removes the listener from the algorithm runtime environment.
|
protected abstract void |
restoreState(AlgorithmState state)
Restores a state of the algorithm.
|
protected abstract void |
rollBackStep(int stepID,
int nextStepID)
Rolls back the specified step.
|
void |
setExecSpeedFactor(float factor)
Sets the execution speed factor of the rte.
|
void |
setExerciseModeEnabled(boolean enabled)
Sets whether the exercise mode of the runtime environment should be enabled.
|
void |
setMinStepDwellTime(long millis)
Sets the minimal dwell time that a step must have.
|
void |
setPauseBeforeTerminate(boolean pause)
Sets whether the runtime environment should be paused before it transitions into stop.
|
void |
setSkipBreakpoints(boolean skip)
Sets if the breakpoints should currently be skipped/ignored.
|
protected void |
sleep(long millis)
Allows the runtime environment to sleep for a specific amount of time.
|
void |
start()
Starts or resumes the execution of the algorithm.
|
void |
start(AlgorithmStartOption option)
Starts or resumes the execution of the algorithm.
|
void |
stop()
Stops the runtime environment of the algorithm.
|
protected abstract void |
storeState(AlgorithmState state)
Stores the current state of the algorithm.
|
getDefaultExerciseProvider, getHost, isActivePlugin, registerHost, showMessage, writeLogMessage, writeLogMessage
public AlgorithmRTE(AlgorithmPlugin plugin, AlgorithmText text) throws java.lang.IllegalArgumentException
plugin
- the algorithm plugin that uses the runtime environmenttext
- the algorithm text that is executed in the runtime environmentjava.lang.IllegalArgumentException
- public AlgorithmRTE(AlgorithmPlugin plugin, AlgorithmText text, AlgorithmExerciseProvider provider) throws java.lang.IllegalArgumentException
plugin
- the algorithm plugin that uses the runtime environmenttext
- the algorithm text that is executed in the runtime environmentprovider
- a custom provider that handles and displays exercises of the algorithm or null
if the default provider of the host should be usedjava.lang.IllegalArgumentException
- public final void addListener(RTEListener listener)
listener
- the listenerRTEAdapter
public final void removeListener(RTEListener listener)
listener
- the listenerpublic final void start()
RTEListener.beforeStart(RTEvent)
or RTEListener.beforeResume(RTEvent)
and the
RTEListener.onRunning()
event.public final void start(AlgorithmStartOption option) throws java.lang.IllegalArgumentException
RTEListener.beforeStart(RTEvent)
or RTEListener.beforeResume(RTEvent)
and the
RTEListener.onRunning()
event.
setMinStepDwellTime(long)
).
This dwell time can be ignored using the AlgorithmStartOption.START_TO_FINISH
option. This means that only breakpoints are regarded.
public final void pause()
start()
.RTEListener.beforePause(RTEvent)
and the RTEListener.onPause()
event.
public final void stop()
start()
.RTEListener.onStop()
event.pause()
public final void nextStep()
isExerciseModeEnabled()
) then it is not possible to go to the next step.public final void prevStep()
isExerciseModeEnabled()
) then it is not possible to go to the previous step.public final boolean isStarted()
true
if the rte is started otherwise false
public final boolean isRunning()
true
if the rte is running otherwise false
public final float getExecSpeedFactor()
1.0f
means a slower and a value greater 1.0f
a
faster execution. For example a factor of 2.0f
means that the execution of the
algorithm is two times faster as normal and a factor of 0.5f
means that the execution is only
half as fast as normal (0.1f
means ten times slower as normal).> 0.0f
)public final void setExecSpeedFactor(float factor)
1.0f
means a slower and a value greater 1.0f
a
faster execution. For example a factor of 2.0f
means that the execution of the
algorithm is two times faster as normal and a factor of 0.5f
means that the execution is only
half as fast as normal (0.1f
means ten times slower as normal).factor
- the execution speed factor (a value > 0.0f
)public final long getMinStepDwellTime()
500
milliseconds.public final void setMinStepDwellTime(long millis) throws java.lang.IllegalArgumentException
500
milliseconds.millis
- the minimal dwell time in millisecondsjava.lang.IllegalArgumentException
- < 0
public final boolean getSkipBreakpoints()
true
if breakpoints are ignored otherwise false
public final void setSkipBreakpoints(boolean skip)
skip
- true
if breakpoints are ignored otherwise false
public final boolean getPauseBeforeStop()
true
if the runtime environment pauses the execution before it transitions into stop otherwise false
public final void setPauseBeforeTerminate(boolean pause)
pause
- true
if the environment should pause the execution before it transitions into stop otherwise false
public final boolean isExerciseModeEnabled()
true
if the exercise mode is enabled otherwise false
public final void setExerciseModeEnabled(boolean enabled)
AlgorithmPlugin.hasExerciseMode()
and the rte is not started yet (meaning
the exercise mode can only be activated if the rte is stopped).
The PluginHost
is notified about the changed mode by PluginHost.rteModeChanged()
.enabled
- true
if the exercise mode should be enabled otherwise false
protected final void sleep(long millis)
millis
- the sleeping time in millisecondsprotected abstract int executeStep(int stepID, AlgorithmStateAttachment asa) throws java.lang.Exception
sleep(long)
to let the algorithm sleep for a specific amount of time to visualize the current step.GraphView
) you should invoke the repaint method after
you make the modification.... // get the visual component of the vertex GraphViewImportant (please note):.VisualVertex vv = graphView.getVisualVertexByCaption("v"); // change the background and afterwards repaint the graph view vv.setBackground(Color.yellow); graphView.repaint();
setText(...)
of a component TextView
is not tagged as thread-safe:
final Set<Integer> set; ... // visualize the current set EDT.execute(new GuiJob() { protected void execute() { textView.setText(set.toString()); } }); ...If a method is tagged as thread-safe (like "This method is thread-safe!") then you can invoke the method directly in the runtime environment without shift it to the EDT.
stepID
- the id of the step that should be executedasa
- the attachment of the current algorithm state that can be used to attach data that is available only during the execution of the current step< 0
if the algorithm is terminatedjava.lang.Exception
- protected abstract void storeState(AlgorithmState state)
Serializer.addInt(String, int)
/AlgorithmState.addSet(String, lavesdk.math.Set)
/...) to
store the current content of the variables you use in your algorithm implementation.
public class MyAlgorithm extends AlgorithmRTE { ... private int k; private float B; private List<Integer> indices; ... protected void storeState(AlgorithmState state) { state.addInt("k", k); state.addFloat("B", B); state.addList("indices", indices); } protected void restoreState(AlgorithmState state) { k = state.getInt("k"); B = state.getFloat("B"); indices = state.getList("indices"); } ... protected int executeStep(int stepID, AlgorithmStateAttachment asa) { ... // implement each step of the algorithm switch(stepID) { case ...: k = indices.get(i); indices.remove(i); ... case ...: B = 0.5*k*i; ... } return nextStep; } ... }Attention:
Serializable
and are public
and independent classes.public
or not independent (like nested classes).state
- the state where the algorithm variables/data should be storedprotected abstract void restoreState(AlgorithmState state)
Serializer.addInt(String, int)
/AlgorithmState.addSet(String, lavesdk.math.Set)
/...) to
assign the data of the state to the variables you use in your algorithm implementation.
public class MyAlgorithm extends AlgorithmRTE { ... private int k; private float B; private List<Integer> indices; ... protected void storeState(AlgorithmState state) { state.addInt("k", k); state.addFloat("B", B); state.addList("indices", indices); } protected void restoreState(AlgorithmState state) { k = state.getInt("k"); B = state.getFloat("B"); indices = state.getList("indices"); } ... protected int executeStep(int stepID, AlgorithmStateAttachment asa) { ... // implement each step of the algorithm switch(stepID) { case ...: k = indices.get(i); indices.remove(i); ... case ...: B = 0.5*k*i; ... } return nextStep; } ... }Attention:
public
or not independent (like nested classes).state
- the state where the algorithm variables/data should be storedprotected abstract void createInitialState(AlgorithmState state)
stop()
)
and the algorithm should start from scratch.
public class MyAlgorithm extends AlgorithmRTE { ... private int k; private float B; private List<Integer> indices; ... public MyAlgorithm(AlgorithmPlugin plugin) { super(plugin); ... // the variables of the algorithm are initialized through createInitialState(...) } protected void createInitialState(AlgorithmState state) { k = state.addInt("k", 0); B = state.addFloat("B", 0.0f); indices = state.addList("indices", new ArrayList<>()); } ... }
state
- the state where the algorithm variables/data should be storedstoreState(AlgorithmState)
,
restoreState(AlgorithmState)
protected abstract void rollBackStep(int stepID, int nextStepID)
restoreState(AlgorithmState)
before a step is rolled back meaning it is possible to access the
state the algorithm had before the given step was executed.
protected void rollBackStep(int stepID) { switch(stepID) { ... case StepIDs.INITIALIZE_SETS: // the step to initialize the sets of the algorithm (like "Let A:={v1}, B:={v | v in V and (v, v1) in E} ...") // should be rolled back meaning we delete the text in the specific view that shows the sets textAreaView.setText(""); break; ... } }Important (please note):
setText(...)
of a component TextView
is not tagged as thread-safe:
final Set<Integer> set; ... // visualize the current set EDT.execute(new GuiJob() { protected void execute() { textView.setText(set.toString()); } }); ...If a method is tagged as thread-safe (like "This method is thread-safe!") then you can invoke the method directly in the runtime environment without shift it to the EDT.
stepID
- the id of the step to roll backnextStepID
- the id of the next step that would have been executed if the current step were not rolled back (this information is useful when a step has several execution branches with each doing different visualization work); might be < 0
if no further step follows and the algorithm terminatesprotected abstract void adoptState(int stepID, AlgorithmState state)
AlgorithmStep
overrides AlgorithmExercise.getApplySolutionToAlgorithm()
meaning
that it returns true
.AlgorithmExercise.applySolutionToAlgorithm(AlgorithmState, Object[])
.
stepID
- the id of the step for whom this adoption is donestate
- the state the algorithm should adopt (in general this state is not equal a state stored or restored with storeState(AlgorithmState)
/restoreState(AlgorithmState)
)protected abstract View[] getViews()
GraphView
graphView
and a TextAreaView
textAreaView
to visualize the algorithm,
so the method should return them as follows:
protected View[] getViews() { return new View[] { graphView, textAreaView }; }These view information are used to disable the repaint mechanism of the views when an algorithm step is skipped by use of
nextStep()
or prevStep()
. Disabling the repaint mechanism might enhance the performance during a step is skipped.null
protected final void hostAccepted()
HostSecurity
HostSecurity.getHost()
returns a valid host.hostAccepted
in class HostSecurity