org.knime.core.node
Class BufferedDataTable

java.lang.Object
  org.knime.core.node.BufferedDataTable

All Implemented Interfaces:

Iterable<DataRow>, DataTable, PortObject

public final class BufferedDataTable
extends Object
implements DataTable, PortObject

DataTable implementation that is passed along the KNIME workflow. This implementation is provided in a NodeModel's NodeModel.execute( BufferedDataTable[], ExecutionContext) method as input data and must also be returned as output data.

BufferedDataTable are not created directly (via a constructor, for instance) but they are rather instantiated using the ExecutionContext that is provided in the execute method.

Implementation note: The iterator returned by this class is a CloseableRowIterator, meaning that if your implementation is likely to open many iterators without pushing them to the end of the table, you should consider to close them when done in order to free system resources.

Author:

Bernd Wiswedel, University of Konstanz

Nested Class Summary

static interface

BufferedDataTable.KnowsRowCountTable Internally used interface.

Nested classes/interfaces inherited from interface org.knime.core.node.port.PortObject

PortObject.PortObjectSerializer<T extends PortObject>

Field Summary

static PortType

TYPE Define port type of objects of this class when used as PortObjects.

Constructor Summary

BufferedDataTable(ConcatenateTable table)
Creates a new buffered data table based on a concatenation of BufferedDataTables.

BufferedDataTable(ContainerTable table, int bufferID)
Creates a new buffered data table based on a container table (caching everything).

BufferedDataTable(ExtensionTable table)
Creates a new BufferedDataTable for an extended table type.

BufferedDataTable(JoinedTable table)
Creates a new buffered data table based on a join of BufferedDataTables.

BufferedDataTable(RearrangeColumnsTable table)
Creates a new buffered data table based on a changed columns table (only memorize columns that changed).

BufferedDataTable(TableSpecReplacerTable table)
Creates a new buffered data table based on a changed spec table (only keep new spec).

BufferedDataTable(WrappedTable table)
Creates a new buffered data table based on a wrapped table.

Method Summary

(package private) void	clear(Node dataOwner) Clears any associated storage, for instance temp files.
(package private) void	clearSingle(Node dataOwner) Clears any associated storage, for instance temp files.
(package private) void	ensureOpen() Reads table from its saved location (usually the workspace).
(package private) static int	generateNewID() Returns a table identifier and increments the internal counter.
Integer	getBufferedTableId() Method being used internally, not interesting for the implementor of a new node model.
static BufferedDataTable	getDataTable(Map<Integer,BufferedDataTable> tblRep, Integer tableID) Method that is used internally while the workflow is being loaded.
DataTableSpec	getDataTableSpec() Returns the DataTableSpec object of this table which gives information about the structure of this data table.
(package private) BufferedDataTable.KnowsRowCountTable	getDelegate() Package scope getter for underlying table implementation.
(package private) Node	getOwner()
(package private) static PortObject.PortObjectSerializer<BufferedDataTable>	getPortObjectSerializer() Throws IllegalStateException as this method is not supposed to be called; refer to the API of PortObject for details on this method.
int	getRowCount() Get the row count of the this table.
DataTableSpec	getSpec() Get specification to this port object.
String	getSummary() Get a short summary of this PortObject.
JComponent[]	getViews() The returned views are displayed in the out port view of the referring node.
CloseableRowIterator	iterator() Returns a row iterator which returns each row one-by-one from the table.
CloseableRowIterator	iteratorFailProve() Get an iterator instance that will return missing values when the table is cleared as part of a node reset.
(package private) static BufferedDataTable	loadFromFile(ReferencedFile dirRef, NodeSettingsRO settings, ExecutionMonitor exec, Map<Integer,BufferedDataTable> tblRep, HashMap<Integer,ContainerTable> bufferRep) Factory method to restore a table that has been written using the save method.
(package private) static DataTableSpec	loadSpec(ReferencedFile dataPortDir) Utility method used in the node's load method.
static void	putDataTable(Map<Integer,BufferedDataTable> tblRep, BufferedDataTable t) Method that is used internally while the workflow is being loaded.
(package private) void	putIntoTableRepository(HashMap<Integer,ContainerTable> rep) Called after execution of node has finished to put the tables that are returned from the execute method into a global table repository.
(package private) int	removeFromTableRepository(HashMap<Integer,ContainerTable> rep, Node owner) Remove this table and all of its delegates from the table repository, if and only if its owner is the argument node.
(package private) void	save(File dir, ExecutionMonitor exec) Saves the table to a directory and writes some settings to the argument NodeSettingsWO object.
(package private) static void	saveSpec(DataTableSpec spec, File dataPortDir) Utility method that is used when the node saves its state.
(package private) void	setOwnerRecursively(Node owner)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TYPE

public static final PortType TYPE

Define port type of objects of this class when used as PortObjects.

Constructor Detail

BufferedDataTable

BufferedDataTable(ContainerTable table,
                  int bufferID)

Creates a new buffered data table based on a container table (caching everything).

Parameters:

table - The reference.

bufferID - The buffer ID.

BufferedDataTable

BufferedDataTable(RearrangeColumnsTable table)

Creates a new buffered data table based on a changed columns table (only memorize columns that changed).

Parameters:

table - The reference.

BufferedDataTable

BufferedDataTable(TableSpecReplacerTable table)

Creates a new buffered data table based on a changed spec table (only keep new spec).

Parameters:

table - The reference.

BufferedDataTable

BufferedDataTable(WrappedTable table)

Creates a new buffered data table based on a wrapped table.

Parameters:

table - The reference.

BufferedDataTable

BufferedDataTable(ConcatenateTable table)

Creates a new buffered data table based on a concatenation of BufferedDataTables.

Parameters:

table - The reference.

BufferedDataTable

BufferedDataTable(JoinedTable table)

Creates a new buffered data table based on a join of BufferedDataTables.

Parameters:

table - The reference.

BufferedDataTable

BufferedDataTable(ExtensionTable table)

Creates a new BufferedDataTable for an extended table type.

Parameters:

table - The extended table

Method Detail

getDataTable

public static BufferedDataTable getDataTable(Map<Integer,BufferedDataTable> tblRep,
                                             Integer tableID)
                                      throws InvalidSettingsException

Method that is used internally while the workflow is being loaded. Not intended to be used directly by node implementations.

Parameters:

tblRep - The table repository

tableID - The table ID

Returns:

The table from the repository.

Throws:

InvalidSettingsException - If no such table exists.

putDataTable

public static void putDataTable(Map<Integer,BufferedDataTable> tblRep,
                                BufferedDataTable t)

Method that is used internally while the workflow is being loaded. Not intended to be used directly by node implementations.

Parameters:

tblRep - The table repository

t - The table to put into the repository.

generateNewID

static int generateNewID()

Returns a table identifier and increments the internal counter.

Returns:

Table identifier.

getPortObjectSerializer

static PortObject.PortObjectSerializer<BufferedDataTable> getPortObjectSerializer()

Throws IllegalStateException as this method is not supposed to be called; refer to the API of PortObject for details on this method. The KNIME engine treats objects of this kind differently.

Returns:

Nothing as an exception is being thrown.

getDelegate

BufferedDataTable.KnowsRowCountTable getDelegate()

Package scope getter for underlying table implementation. Only needed if underlying table is of special kind and can be treated differently/ more efficiently by individual node implementations.

Returns:

underlying table.

putIntoTableRepository

void putIntoTableRepository(HashMap<Integer,ContainerTable> rep)

Called after execution of node has finished to put the tables that are returned from the execute method into a global table repository.

Parameters:

rep - The repository from the workflow

removeFromTableRepository

int removeFromTableRepository(HashMap<Integer,ContainerTable> rep,
                              Node owner)

Remove this table and all of its delegates from the table repository, if and only if its owner is the argument node.

Parameters:

rep - The repository to be removed from.

owner - The dedicated owner.

Returns:

The number of tables effectively removed, used for assertions.

getDataTableSpec

public DataTableSpec getDataTableSpec()

Returns the DataTableSpec object of this table which gives information about the structure of this data table.

Specified by:

getDataTableSpec in interface DataTable

Returns:

the DataTableSpec of this table

getSpec

public DataTableSpec getSpec()

Get specification to this port object. That is, the corresponding PortObjectSpec which is used to configure any successor node after execution, e.g. a BufferedDataTable can return a DataTableSpec.

Subclasses should narrow the return type if possible.

Specified by:

getSpec in interface PortObject

Returns:

underlying PortObjectSpec or any derived spec, never null.

See Also:

getDataTableSpec()

getSummary

public String getSummary()

Get a short summary of this PortObject. The return value will be shown in a node port's tooltip, for instance.

Specified by:

getSummary in interface PortObject

Returns:

Summary of the object's content, suitable for a tooltip. Empty strings and null result values are ok (though not encouraged).

iterator

public CloseableRowIterator iterator()

Returns a row iterator which returns each row one-by-one from the table.

Specified by:

iterator in interface Iterable<DataRow>

Specified by:

iterator in interface DataTable

Returns:

row iterator

See Also:

DataRow

iteratorFailProve

public CloseableRowIterator iteratorFailProve()

Get an iterator instance that will return missing values when the table is cleared as part of a node reset.

In general, node implementations are guaranteed not to be active (executing none of the abstract methods) when a node is reset. However, if the data is displayed in a view using an iterator (e.g. a table view), there is no guarantee when the data is accessed. Reading the data and clearing the table may occur concurrently, specifically if used in fast executing loops. An iterator returned by this method will ensure that (invalid = missing) data is returned and that there are as many rows as suggested by the getRowCount() method.

Client implementations should generally use the iterator() method to read the data unless the data is potentially accessed in a node or port view outside the NodeModel.execute(BufferedDataTable[], ExecutionContext) method.

Returns:

A new iterator instance that will return missing values and fake row ids in case the table is cleared (either before this method is called or while the iteration is in progress).

getRowCount

public int getRowCount()

Get the row count of the this table.

Returns:

Number of rows in the table.

getBufferedTableId

public Integer getBufferedTableId()

Method being used internally, not interesting for the implementor of a new node model. It will return a unique ID to identify the table while loading.

Returns:

The unique ID.

save

void save(File dir,
          ExecutionMonitor exec)
    throws IOException,
           CanceledExecutionException

Saves the table to a directory and writes some settings to the argument NodeSettingsWO object. It will also write the reference table in case this node is responsible for it (i.e. this node created the reference table).

Parameters:

dir - The directory to write to.

exec - The progress monitor for cancellation.

Throws:

IOException - If writing fails.

CanceledExecutionException - If canceled.

saveSpec

static void saveSpec(DataTableSpec spec,
                     File dataPortDir)
              throws IOException

Utility method that is used when the node saves its state. It saves it to a file spec.xml.

Parameters:

spec - To save

dataPortDir - destination directory

Throws:

IOException - if that fails for any reason

loadSpec

static DataTableSpec loadSpec(ReferencedFile dataPortDir)
                       throws IOException,
                              InvalidSettingsException

Utility method used in the node's load method. It reads the spec from a file spec.xml in dataPortDir.

Parameters:

dataPortDir - To load from.

Returns:

The spec contained in this directory.

Throws:

IOException - If that fails.

InvalidSettingsException - If the settings in the spec.xml can't be parsed.

loadFromFile

static BufferedDataTable loadFromFile(ReferencedFile dirRef,
                                      NodeSettingsRO settings,
                                      ExecutionMonitor exec,
                                      Map<Integer,BufferedDataTable> tblRep,
                                      HashMap<Integer,ContainerTable> bufferRep)
                               throws IOException,
                                      CanceledExecutionException,
                                      InvalidSettingsException

Factory method to restore a table that has been written using the save method.

Parameters:

dirRef - The directory to load from.

settings - The settings to load from.

exec - The exec mon for progress/cancel

tblRep - The table repository

bufferRep - The buffer repository (needed for blobs).

Returns:

The table as written by save.

Throws:

IOException - If reading fails.

CanceledExecutionException - If canceled.

InvalidSettingsException - If settings are invalid.

getOwner

Node getOwner()

Returns:

Returns the owner.

setOwnerRecursively

void setOwnerRecursively(Node owner)

Parameters:

owner - The owner to set.

clear

void clear(Node dataOwner)

Clears any associated storage, for instance temp files. This call also clears all referenced tables (if they are owned by the same node).

Parameters:

dataOwner - The owner of the tables. If getOwner() != dataOwner, we return immediately.

clearSingle

void clearSingle(Node dataOwner)

Clears any associated storage, for instance temp files. This call does not clear referenced tables owned by the same node. Only used if client code programmatically clears a temporary table created during the execution.

Parameters:

dataOwner - The owner of the tables. If getOwner() != dataOwner, we return immediately.

ensureOpen

void ensureOpen()

Reads table from its saved location (usually the workspace). Used to allow for later re-saving in a cleared workspace (used for version hop)

getViews

public JComponent[] getViews()

The returned views are displayed in the out port view of the referring node. Each component is displayed in an extra tab. The name of the component is used as the title for the tab. It is important that no external members are kept in the component so it can be deleted, when the port object is deleted. If the port object has no view return an empty array.

Specified by:

getViews in interface PortObject

Returns:

an array of views for the port object, each displayed as a tab in the out port view