org.knime.core.node.interrupt
Class InterruptibleNodeModel

java.lang.Object
  extended by org.knime.core.node.NodeModel
      extended by org.knime.core.node.interrupt.InterruptibleNodeModel

public abstract class InterruptibleNodeModel
extends NodeModel

This class provides a generic implementation of a node that can be stopped and resumed during execution. Therefore a derived class has to provide a method which realizes one iteration of the algorithm that should be processed interruptible.

Author:
Fabian Dill, University of Konstanz

Field Summary
static int INITIAL_DELAY
          A constant to define the initial delay, so the algorithm and the slider have the same initial values.
static int SLEEPING_MILLIS
          A constant defining how long the execute thread should sleep, while waiting to resume again.
 
Constructor Summary
InterruptibleNodeModel(int nrInPorts, int nrOutPorts)
          Constructs a NodeModel with the desired in- and out-ports, setting the state to paused, that is waiting for an initial event to start executing.
 
Method Summary
 BufferedDataTable[] execute(BufferedDataTable[] inData, ExecutionContext exec)
          Initialises the NodeModel, starts the execution, pauses it, resumes it and finishes it.
abstract  void executeOneIteration(ExecutionContext exec)
          This method is assumed to implement one iteration of an interruptible algorithm.
 void finish()
          Forces the algorithm to finish its execution.
 int getDelay()
          Returns the current delay, that is the number of iterations until the view is refreshed.
 BufferedDataTable[] getInputData()
          Returns the input data that was connected to the node at the beginning of the execute method as a whole.
 DataTable getInputData(int portNr)
          Provides access to the input data the node is passed to at the beginning of the execute method.
 int getNumberOfIterations()
          Returns the number of processed iterations so far.
abstract  BufferedDataTable[] getOutput(ExecutionContext exec)
          Is called at the end of the execute method when it is finished and the data should be available.
abstract  void init(BufferedDataTable[] inData, ExecutionContext exec)
          Do here the initialisation of the model.
 boolean isFinished()
          Indicates whether the state of the algorithm is finished or not.
 boolean isPaused()
          Indicates whether the execution of the algorithm is paused or not.
protected  void loadInternals(File nodeInternDir, ExecutionMonitor exec)
          Load internals into the derived NodeModel.
 void next(int numberOfIterations)
          Causes the execution of the next (n) iteration(s).
 void pause()
          Causes the execution to pause until either next(int) or run() is called.
protected  void reset()
          Resets the status of the Node to paused and not finished so it can be triggered to start again.
 void run()
          Causes the node to run for an unlimited number of iterations.
protected  void saveInternals(File nodeInternDir, ExecutionMonitor exec)
          Save internals of the derived NodeModel.
 void setDelay(int delay)
          Sets the delay, that is the number of iterations until the view is refreshed.
 
Methods inherited from class org.knime.core.node.NodeModel
addWarningListener, configure, configure, continueLoop, execute, executeModel, getInHiLiteHandler, getLoopEndNode, getLoopStartNode, getNrInPorts, getNrOutPorts, getOutHiLiteHandler, getWarningMessage, loadValidatedSettingsFrom, notifyViews, notifyWarningListeners, peekFlowVariableDouble, peekFlowVariableInt, peekFlowVariableString, peekScopeVariableDouble, peekScopeVariableInt, peekScopeVariableString, pushFlowVariableDouble, pushFlowVariableInt, pushFlowVariableString, pushScopeVariableDouble, pushScopeVariableInt, pushScopeVariableString, removeWarningListener, saveSettingsTo, setInHiLiteHandler, setWarningMessage, stateChanged, validateSettings
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INITIAL_DELAY

public static final int INITIAL_DELAY
A constant to define the initial delay, so the algorithm and the slider have the same initial values.

See Also:
Constant Field Values

SLEEPING_MILLIS

public static final int SLEEPING_MILLIS
A constant defining how long the execute thread should sleep, while waiting to resume again.

See Also:
Constant Field Values
Constructor Detail

InterruptibleNodeModel

public InterruptibleNodeModel(int nrInPorts,
                              int nrOutPorts)
Constructs a NodeModel with the desired in- and out-ports, setting the state to paused, that is waiting for an initial event to start executing.

Parameters:
nrInPorts - - the desired number of in-ports.
nrOutPorts - - the desired number of out-ports.
Method Detail

getNumberOfIterations

public int getNumberOfIterations()
Returns the number of processed iterations so far.

Returns:
- the number of processed iterations so far.

setDelay

public void setDelay(int delay)
Sets the delay, that is the number of iterations until the view is refreshed. Setting the delay to n, every n-th iteration the view is refreshed.

Parameters:
delay - - the number of iterations until the view is refreshed.

getDelay

public int getDelay()
Returns the current delay, that is the number of iterations until the view is refreshed.

Returns:
- the current delay.

isPaused

public boolean isPaused()
Indicates whether the execution of the algorithm is paused or not.

Returns:
- true, if the execution pauses, false otherwise.

pause

public void pause()
Causes the execution to pause until either next(int) or run() is called.


isFinished

public boolean isFinished()
Indicates whether the state of the algorithm is finished or not.

Returns:
- true, if the algorithm is finished, false otherwise.

finish

public void finish()
Forces the algorithm to finish its execution. If the algorithm is currently running, the current iteration will be finished gracefully.


next

public void next(int numberOfIterations)
Causes the execution of the next (n) iteration(s).

Parameters:
numberOfIterations - number of iterations to perform

run

public void run()
Causes the node to run for an unlimited number of iterations.


getInputData

public DataTable getInputData(int portNr)
Provides access to the input data the node is passed to at the beginning of the execute method.

Parameters:
portNr - - the referring inport number
Returns:
- the DataTable that was connected to port portNr at the beginning of the execute method, null if no input data is available.

getInputData

public BufferedDataTable[] getInputData()
Returns the input data that was connected to the node at the beginning of the execute method as a whole.

Returns:
- the input data as a whole.

execute

public final BufferedDataTable[] execute(BufferedDataTable[] inData,
                                         ExecutionContext exec)
                                  throws Exception
Initialises the NodeModel, starts the execution, pauses it, resumes it and finishes it. At the end the from the derived NodeModel provided output data is set to the output. This function is invoked by the Node#executeNode() method of the node (through the #executeModel(BufferedDataTable[],ExecutionMonitor) method)only after all predecessor nodes have been successfully executed and all data is therefore available at the input ports. Implement this function with your task in the derived model.

The input data is available in the given array argument inData and is ensured to be neither null nor contain null elements.

In order to create output data, you need to create objects of class BufferedDataTable. Use the execution context argument to create BufferedDataTable.

Overrides:
execute in class NodeModel
Parameters:
inData - An array holding DataTable elements, one for each input.
exec - The execution monitor for this execute method. It provides us with means to create new BufferedDataTable. Additionally, it should be asked frequently if the execution should be interrupted and throws an exception then. This exception might me caught, and then after closing all data streams, been thrown again. Also, if you can tell the progress of your task, just set it in this monitor.
Returns:
An array of non- null DataTable elements with the size of the number of outputs. The result of this execution.
Throws:
Exception - If you must fail the execution. Try to provide a meaningful error message in the exception as it will be displayed to the user.Please be advised to check frequently the canceled status by invoking ExecutionMonitor#checkCanceled which will throw an CanceledExcecutionException and abort the execution.

reset

protected void reset()
Resets the status of the Node to paused and not finished so it can be triggered to start again.

Specified by:
reset in class NodeModel
See Also:
NodeModel.reset()

loadInternals

protected void loadInternals(File nodeInternDir,
                             ExecutionMonitor exec)
                      throws IOException,
                             CanceledExecutionException
Load internals into the derived NodeModel. This method is only called if the Node was executed. Read all your internal structures from the given file directory to create your internal data structure which is necessary to provide all node functionalities after the workflow is loaded, e.g. view content and/or hilite mapping.

Specified by:
loadInternals in class NodeModel
Parameters:
nodeInternDir - The directory to read from.
exec - Used to report progress and to cancel the load process.
Throws:
IOException - If an error occurs during reading from this dir.
CanceledExecutionException - If the loading has been canceled.
See Also:
NodeModel.saveInternals(File,ExecutionMonitor)

saveInternals

protected void saveInternals(File nodeInternDir,
                             ExecutionMonitor exec)
                      throws IOException,
                             CanceledExecutionException
Save internals of the derived NodeModel. This method is only called if the Node is executed. Write all your internal structures into the given file directory which are necessary to recreate this model when the workflow is loaded, e.g. view content and/or hilite mapping.

Specified by:
saveInternals in class NodeModel
Parameters:
nodeInternDir - The directory to write into.
exec - Used to report progress and to cancel the save process.
Throws:
IOException - If an error occurs during writing to this dir.
CanceledExecutionException - If the saving has been canceled.
See Also:
NodeModel.loadInternals(File,ExecutionMonitor)

executeOneIteration

public abstract void executeOneIteration(ExecutionContext exec)
                                  throws CanceledExecutionException
This method is assumed to implement one iteration of an interruptible algorithm. Most of the data mining algorithm typically run in several for- or while-clauses until they meet any stopping criteria. Here the control is different, since here the user is able to start, resume and stop the algorithm. (If there is any natural stopping criteria for even the interruptible algorithm call the finish()-method when it is met). In any case implement in this method the content of the for- or while-clause.

Parameters:
exec - the ExecutionContext to cancel the operation or show the progress.
Throws:
CanceledExecutionException - if the operation is canceled by the user.

init

public abstract void init(BufferedDataTable[] inData,
                          ExecutionContext exec)
                   throws CanceledExecutionException,
                          InvalidSettingsException
Do here the initialisation of the model. This method is called before starting the execute method.

Parameters:
inData - - the incoming DataTables at the moment the execute method starts.
exec - to show the progress of the initialization or to cancel it.
Throws:
CanceledExecutionException - if the operation is canceled by the user.
InvalidSettingsException - - if the inData doesn't fit the expected configuration.

getOutput

public abstract BufferedDataTable[] getOutput(ExecutionContext exec)
                                       throws CanceledExecutionException
Is called at the end of the execute method when it is finished and the data should be available. Note that the returned DataTable[] is directly returned from the execute method, so mind the restrictions on the DataTable[] as for the execute method.

Parameters:
exec - The execution monitor to show the progress.
Returns:
- an BufferedDataTable[] as should be returned from the NodeModel's execute method.
Throws:
CanceledExecutionException - If writing output tables has been canceled.


Copyright, 2003 - 2010. All rights reserved.
University of Konstanz, Germany.
Chair for Bioinformatics and Information Mining, Prof. Dr. Michael R. Berthold.
You may not modify, publish, transmit, transfer or sell, reproduce, create derivative works from, distribute, perform, display, or in any way exploit any of the content, in whole or in part, except as otherwise expressly permitted in writing by the copyright owner or as specified in the license file distributed with this product.