org.knime.core.node
Class ExecutionContext

java.lang.Object
  extended by org.knime.core.node.ExecutionMonitor
      extended by org.knime.core.node.ExecutionContext

public class ExecutionContext
extends ExecutionMonitor

An ExecutionContext provides storage capacities during a NodeModel's execution. Furthermore it allows to report progress of the execution and to check for cancellation events. Any derived class of NodeModel that has at least one data output will need to create a BufferedDataTable as return value of the execute method. These BufferedDataTable can only be created by means of an ExecutionContext using one of the create... methods. There are basically three different ways to create the output table:

New data
Use the createDataContainer(DataTableSpec) method to create a container to which rows are sequentially added. The final result will be available through the container's BufferedDataContainer.getTable() method. Alternatively you can also use the createBufferedDataTable(DataTable, ExecutionMonitor) method which will traverse the argument table and cache everything. These method shall be used when the entire output must be cached (thus also resulting in using more disc space when the workflow is saved).
Some columns of the input have changed
This is the case, for instance when you just append a single column to the input table (or filter/replace existing columns from it). The method to use here is createColumnRearrangeTable(BufferedDataTable, ColumnRearranger, ExecutionMonitor). When the workflow is saved, only the columns that have changed are stored to disc.
The table spec of the input changes
This happens for nodes that rename a column or add some properties to the table spec. The input data itself is left untouched. Use the createSpecReplacerTable(BufferedDataTable, DataTableSpec) here.

Apart from creating BufferedDataTable, objects of this class are also responsible to report progress information. See the super class for more information.

Author:
Bernd Wiswedel, University of Konstanz

Constructor Summary
ExecutionContext(NodeProgressMonitor progMon, Node node)
          Deprecated. Use the constructor with a table repository argument instead. This constructor potentially does not support serialization of blobs.
ExecutionContext(NodeProgressMonitor progMon, Node node, SingleNodeContainer.MemoryPolicy policy, HashMap<Integer,ContainerTable> tableRepository)
          Creates new object based on a progress monitor and a node as parent of any created buffered data table.
 
Method Summary
 BufferedDataTable createBufferedDataTable(DataTable table, ExecutionMonitor subProgressMon)
          Caches the table argument and returns a reference to a BufferedDataTable wrapping the content.
 BufferedDataTable[] createBufferedDataTables(DataTable[] tables, ExecutionMonitor exec)
          Performs the creation of buffered datatables for an array of DataTables.
 BufferedDataTable createColumnRearrangeTable(BufferedDataTable in, ColumnRearranger rearranger, ExecutionMonitor subProgressMon)
          Creates a new BufferedDataTable based on a given input table (in) whereby only some of the columns of in have changed.
 BufferedDataTable createConcatenateTable(ExecutionMonitor exec, BufferedDataTable... tables)
          Creates a new BufferedDataTable, which is row-wise concatenation of the argument tables.
 BufferedDataContainer createDataContainer(DataTableSpec spec)
          Creates a container to which rows can be added.
 BufferedDataContainer createDataContainer(DataTableSpec spec, boolean initDomain)
          Creates a container to which rows can be added.
 BufferedDataContainer createDataContainer(DataTableSpec spec, boolean initDomain, int maxCellsInMemory)
          Creates a container to which rows can be added, overwriting the node's memory policy.
 BufferedDataTable createJoinedTable(BufferedDataTable left, BufferedDataTable right, ExecutionMonitor exec)
          Creates a new BufferedDataTable that is a column based join of the argument tables.
 ExecutionContext createSilentSubExecutionContext(double maxProg)
          Creates a new execution context with a different max progress value and swallowing any report messages.
 BufferedDataTable createSpecReplacerTable(BufferedDataTable in, DataTableSpec newSpec)
          Creates a new BufferedDataTable based on a given input table (in) whereby only the table spec of it has changed.
 ExecutionContext createSubExecutionContext(double maxProg)
          Creates a new execution context with a different max progress value.
 BufferedDataTable createWrappedTable(BufferedDataTable in)
          Creates a new BufferedDataTable that simply wraps the argument table.
(package private)  HashMap<Integer,ContainerTable> getLocalTableRepository()
          Get reference to the local table repository.
 Future<PortObject[]> submitJob(PortObject[] input, NodeSettingsRO settings, Class<? extends KNIMEJob> jobClass, ExecutionMonitor exec)
          Submits a job to an executor, which can be a threaded one, a cluster executor or anything else.
 
Methods inherited from class org.knime.core.node.ExecutionMonitor
checkCanceled, createSilentSubProgress, createSilentSubProgressMonitor, createSubProgress, createSubProgressMonitor, getProgressMonitor, isCanceled, setMessage, setProgress, setProgress, setProgress
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ExecutionContext

@Deprecated
public ExecutionContext(NodeProgressMonitor progMon,
                                   Node node)
Deprecated. Use the constructor with a table repository argument instead. This constructor potentially does not support serialization of blobs.

Creates new object based on a progress monitor and a node as parent of any created buffered data table.

Parameters:
progMon - To report progress to.
node - The parent of any BufferedDataTable being created. themselves; used internally to identify tables that serialize blob cells.

ExecutionContext

public ExecutionContext(NodeProgressMonitor progMon,
                        Node node,
                        SingleNodeContainer.MemoryPolicy policy,
                        HashMap<Integer,ContainerTable> tableRepository)
Creates new object based on a progress monitor and a node as parent of any created buffered data table.

Parameters:
progMon - To report progress to.
node - The parent of any BufferedDataTable being created.
policy - the policy according to which created BufferedDataTables behave
tableRepository - A map to which BufferedDataTables register themselves; used internally to identify tables that serialize blob cells.
Method Detail

createBufferedDataTable

public BufferedDataTable createBufferedDataTable(DataTable table,
                                                 ExecutionMonitor subProgressMon)
                                          throws CanceledExecutionException
Caches the table argument and returns a reference to a BufferedDataTable wrapping the content. When saving the workflow, the entire data is written to disc. This method is provided for convenience. (All it does is to create a BufferedDataContainer, adding the rows to it and returning a handle to it.)

This method refers to the first way of storing data, see here.

Parameters:
table - The table to cache.
subProgressMon - The execution monitor to report progress to. In most cases this is the object on which this method is invoked. It may however be an sub progress monitor.
Returns:
A table ready to be returned in the execute method.
Throws:
CanceledExecutionException - If canceled.

createBufferedDataTables

public BufferedDataTable[] createBufferedDataTables(DataTable[] tables,
                                                    ExecutionMonitor exec)
                                             throws CanceledExecutionException
Performs the creation of buffered datatables for an array of DataTables.

Parameters:
tables - The tables to cache.
exec - The execution monitor for progress, cancel
Returns:
The cached array of tables.
Throws:
CanceledExecutionException - If canceled.
See Also:
createBufferedDataTable(DataTable, ExecutionMonitor)

createDataContainer

public BufferedDataContainer createDataContainer(DataTableSpec spec)
Creates a container to which rows can be added. Use this method if you sequentially generate new rows. Add those by using the addRow(DataRow) method and finally close the container and get the result by invoking getTable(). All rows will be cached.

This method refers to the first way of storing data, see here.

Parameters:
spec - The spec to open the container.
Returns:
A container to which rows can be added and which provides the BufferedDataTable.
Throws:
NullPointerException - If the argument is null.

createDataContainer

public BufferedDataContainer createDataContainer(DataTableSpec spec,
                                                 boolean initDomain)
Creates a container to which rows can be added. Use this method if you sequentially generate new rows. Add those by using the addRow(DataRow) method and finally close the container and get the result by invoking getTable(). All rows will be cached.

This method refers to the first way of storing data, see here.

Parameters:
spec - The spec to open the container.
initDomain - If the domain information from the argument shall be used to initialize the domain (min, max, possible values). If false, the domain will be determined on the fly.
Returns:
A container to which rows can be added and which provides the BufferedDataTable.
Throws:
NullPointerException - If the spec argument is null.

createDataContainer

public BufferedDataContainer createDataContainer(DataTableSpec spec,
                                                 boolean initDomain,
                                                 int maxCellsInMemory)
Creates a container to which rows can be added, overwriting the node's memory policy. This method has the same behavior as createDataContainer(DataTableSpec, boolean) except for the last argument maxCellsInMemory. It controls the memory policy of the data container (which is otherwise controlled by a user setting in the dialog).

Note: It's strongly advised to use createDataContainer(DataTableSpec, boolean) instead of this method as the above method realizes the memory policy specified by the user. Use this method only if you have good reasons to do so (for instance if you create many containers, whose default memory options would yield a high accumulated memory consumption).

Parameters:
spec - The spec to open the container.
initDomain - If the domain information from the argument shall be used to initialize the domain (min, max, possible values). If false, the domain will be determined on the fly.
maxCellsInMemory - Number of cells to be kept in memory, especially 0 forces the table to write to disk immediately. A value smaller than 0 will respect the user setting (as defined by the accompanying node).
Returns:
A container to which rows can be added and which provides the BufferedDataTable.
Throws:
NullPointerException - If the spec argument is null.

createColumnRearrangeTable

public BufferedDataTable createColumnRearrangeTable(BufferedDataTable in,
                                                    ColumnRearranger rearranger,
                                                    ExecutionMonitor subProgressMon)
                                             throws CanceledExecutionException
Creates a new BufferedDataTable based on a given input table (in) whereby only some of the columns of in have changed.

When the workflow is saved, only the columns that changed will be stored to disc, see also the class description for details.

Parameters:
in - The input table, i.e. reference table.
rearranger - The object which performs the reassembling of columns.
subProgressMon - Typically the object on which this method is performed unless the processing is only a part of the total work.
Returns:
A new table which can be returned in the execute method.
Throws:
CanceledExecutionException - If canceled.

createSpecReplacerTable

public BufferedDataTable createSpecReplacerTable(BufferedDataTable in,
                                                 DataTableSpec newSpec)
Creates a new BufferedDataTable based on a given input table (in) whereby only the table spec of it has changed.

When the workflow is saved, only the spec needs to be saved, see also the class description for details.

Parameters:
in - The input table, i.e. reference table.
newSpec - The new table spec of in.
Returns:
A new table which can be returned in the execute method.

createWrappedTable

public BufferedDataTable createWrappedTable(BufferedDataTable in)
Creates a new BufferedDataTable that simply wraps the argument table. This is useful when a node just passes on the input table, for example. If the implementation of NodeModel does not use this method (but simply returns the input table directy), the framework will perform the wrapping operation.

Parameters:
in - The input table to wrap.
Returns:
A new table which can be returned in the execute method.
Throws:
NullPointerException - If the argument is null.

createConcatenateTable

public BufferedDataTable createConcatenateTable(ExecutionMonitor exec,
                                                BufferedDataTable... tables)
                                         throws CanceledExecutionException
Creates a new BufferedDataTable, which is row-wise concatenation of the argument tables. The order of the rows in the returned table is defined through the order of the argument array tables (the BufferedDataTable at index 0 provides the first set of rows.

The table specs of the argument tables must structurally match (i.e. order of columns, column count, column names, and types). The column domains (min, max and possible values) and properties will be merged. (The merge of properties is based on a maximum intersection of all properties.)

Property handlers (such as Color, Shape, and SizeHandler) attached to any of the input columns need to be the same for all respective columns in the remaining tables.

The RowKeys must be unique, other wise this method throws an exception.

Parameters:
exec - For cancel checks (this method iterates all rows to ensure uniqueness) and progress.
tables - An array of tables to concatenate, must not be null or empty.
Returns:
The concatenated table.
Throws:
CanceledExecutionException - If canceled.
IllegalArgumentException - If the table specs violate any constraint mentioned above, the row keys are not unique, or the array is empty.
NullPointerException - If any argument is null.

createJoinedTable

public BufferedDataTable createJoinedTable(BufferedDataTable left,
                                           BufferedDataTable right,
                                           ExecutionMonitor exec)
                                    throws CanceledExecutionException
Creates a new BufferedDataTable that is a column based join of the argument tables. The left table argument contributes the first set of columns and the right table argument the second set of columns. The tables must not contain duplicate columns (i.e. columns with the same name). They do need to contain the same set of rows though, i.e. the same row count and equal row keys in identical order. If any of these constraints is not met, this method throws and IllegalArgumentException.

This method will traverse both tables ones to ensure that the row keys are identical and are returned in the same order. It reports progress for this sanity check to the exec argument.

The returned table is only a view on both argument tables, i.e. any subsequent iteration is carried out on the argument tables. This also means that the returned table does only acquire little main memory and no disc memory at all.

Parameters:
left - The table contributing the first set of columns.
right - The table contributing the second set of columns.
exec - For progress information and cancel checks, consider to use a sub execution monitor when joining two tables is only part of the whole work.
Returns:
A buffered data table as join of the two argument tables.
Throws:
CanceledExecutionException - If progress has been canceled.
NullPointerException - If any argument is null.
IllegalArgumentException - If the tables contain duplicate columns or non-matching rows.
See Also:
DataTableSpec.DataTableSpec(DataTableSpec, DataTableSpec)

createSubExecutionContext

public ExecutionContext createSubExecutionContext(double maxProg)
Creates a new execution context with a different max progress value. This method is the counterpart to ExecutionMonitor.createSubProgress(double) ExecutionMonitor. A sub execution contexts has the same properties as this object but it only reports progress to a limited value of maxProg. It can therefore be used in, e.g. utility classes which report progress in [0, 1], but whose progress is only a small contribution to the overall progress.

Parameters:
maxProg - The maximum progress, must be in [0,1]
Returns:
A new execution context.

createSilentSubExecutionContext

public ExecutionContext createSilentSubExecutionContext(double maxProg)
Creates a new execution context with a different max progress value and swallowing any report messages. This method is the counterpart to ExecutionMonitor.createSilentSubProgress(double) in ExecutionMonitor. A sub execution contexts has the same properties as this object but it only reports progress to a limited value of maxProg. It will also ignore any message, which is set using the ExecutionMonitor.setMessage(String) method. It can therefore be used in, e.g. utility classes which report progress in [0, 1], but whose progress is only a small contribution to the overall progress.

Parameters:
maxProg - The maximum progress, must be in [0,1]
Returns:
A new execution context.

getLocalTableRepository

HashMap<Integer,ContainerTable> getLocalTableRepository()
Get reference to the local table repository. It contains ContainerTable objects that have been created during the execution of a node. Some of which will be put into the global repository after execution.

Returns:
The local table repository.

submitJob

public Future<PortObject[]> submitJob(PortObject[] input,
                                      NodeSettingsRO settings,
                                      Class<? extends KNIMEJob> jobClass,
                                      ExecutionMonitor exec)
                               throws NoSuchMethodException
Submits a job to an executor, which can be a threaded one, a cluster executor or anything else.

Parameters:
input - the input data for the job
settings - the settings for the job
jobClass - the job's class that is
exec - the execution monitor
Returns:
a future holding the job's results
Throws:
NoSuchMethodException - of the job class does not have a default constructor


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.