org.knime.core.data
Class DataTableSpec

java.lang.Object
  extended by org.knime.core.data.DataTableSpec
All Implemented Interfaces:
Iterable<DataColumnSpec>, PortObjectSpec

public final class DataTableSpec
extends Object
implements PortObjectSpec, Iterable<DataColumnSpec>

DataTableSpecs specify the structure of a DataTable.

The spec specifies the characteristics i.e. column numbers, as well as column types, names, and other column oriented information through a collection of DataColumnSpec objects. The names of the DataColumnSpecs must be unique identifiers within a DataTableSpec.

Once a DataTableSpec is initialized, it is immutable. That is, if you want to add further information to a column (for instance, the possible values in a column), you have to create a new instance of a DataTableSpec carrying the new information. A spec can be propagated from node to node via the ports so that succeeding nodes know about the table structure even if no data table is currently available.

In addition, the table spec provides a single SizeHandler, ColorHandler and/or ShapeHandler if available. The handlers are associated with a column. These property handlers can be used to assign size, color, and shape to a row based on the DataCells value in the corresponding column. If there is more than one column that provides a handler of a certain type (color, shape, size) the first handler is used.
A DataTableSpec can also have a name which does not need to be unique.

Author:
Peter Ohl, University of Konstanz
See Also:
DataTable, DataColumnSpec

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.knime.core.node.port.PortObjectSpec
PortObjectSpec.PortObjectSpecSerializer<T extends PortObjectSpec>
 
Field Summary
static String[] CLASS_COLUMN_NAMES
          Columns used to guess class column in the order they are specified.
 
Constructor Summary
DataTableSpec()
          Creates an empty DataTableSpec with no columns defined and default as name.
DataTableSpec(DataColumnSpec... colSpecs)
          Creates a new DataTableSpec, which is built from an array of DataColumnSpec elements.
DataTableSpec(DataTableSpec spec1, DataTableSpec spec2)
          Constructor for a new DataTableSpec based on two existing specifications that are to be concatenated.
DataTableSpec(String name)
          Creates an empty DataTableSpec with no columns defined.
DataTableSpec(String[] names, DataType[] types)
          Creates a new DataTableSpec based on a list of names and types.
DataTableSpec(String name, DataColumnSpec... colSpecs)
          Creates a new DataTableSpec, which is built from an array of DataColumnSpec elements.
DataTableSpec(String name, DataTableSpec spec1, DataTableSpec spec2)
          Constructor for a new DataTableSpec based on two existing specifications that are to be concatenated.
DataTableSpec(String name, String[] names, DataType[] types)
          Creates a new DataTableSpec based on a list of names and types.
 
Method Summary
 boolean containsCompatibleType(Class<? extends DataValue> valueClass)
          Checks if this spec contains a column with a type compatible to the given DataValue class.
 boolean containsName(String columnName)
          Checks if the given column name occurs in this spec.
static DataColumnSpec[] createColumnSpecs(String[] names, DataType[] types)
          Static helper method to create a DataColumnSpec array from the given names and types.
 boolean equals(Object obj)
          Checks if both DataTableSpecs are equal.
 boolean equalStructure(DataTableSpec spec)
          Returns true if spec has the same column names and types.
 int findColumnIndex(String columnName)
          Finds the column with the specified name in the TableSpec and returns its index, or -1 if the name doesn't exist in the table.
 DataColumnSpec getColumnSpec(int index)
          Returns column information of the column with the provided index.
 DataColumnSpec getColumnSpec(String column)
          Returns the DataColumnSpec of the column with the provided name.
 String getName()
          Returns the name of this DataTableSpec.
 int getNumColumns()
          Returns the number of columns.
static PortObjectSpec.PortObjectSpecSerializer<DataTableSpec> getPortObjectSpecSerializer()
          Method required by the interface PortObjectSpec.
 ColorAttr getRowColor(DataRow row)
          Returns the color that an object should have when displaying information concerning this row (for instance in a scatterplot).
 ShapeFactory.Shape getRowShape(DataRow row)
          Return the shape that an object should have when displaying information concerning this row (for instance in a scatterplot).
 double getRowSize(DataRow row)
          Deprecated. use row size factor instead
 double getRowSizeFactor(DataRow row)
          Return the size (as a scaling factor) that an object should have when displaying information concerning this row (for instance in a scatterplot).
static String getUniqueColumnName(DataTableSpec spec, String columnName)
          Returns a column name, which is not contained in specified DataTableSpec.
 JComponent[] getViews()
          The returned views are displayed in the out port view of the referring node.
static String guessNominalClassColumn(DataTableSpec spec, boolean withValues)
          Guesses the column in the argument spec that likely contains the class attribute.
 int hashCode()
          
 Iterator<DataColumnSpec> iterator()
          Returns an iterator for the contained DataColumnSpec elements.
static DataTableSpec load(ConfigRO config)
          Reads all DataColumnSpec objects from the given ConfigRO and returns a new DataTableSpec object containing them.
static DataTableSpec mergeDataTableSpecs(DataTableSpec... specs)
          This method merges two or more DataTableSpecs.
 void save(ConfigWO config)
          Saves the table spec name and all DataColumnSpecs to the given ConfigWO object.
 String toString()
          The string summary of all column specs of this table spec.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

CLASS_COLUMN_NAMES

public static final String[] CLASS_COLUMN_NAMES
Columns used to guess class column in the order they are specified.

Constructor Detail

DataTableSpec

public DataTableSpec()
Creates an empty DataTableSpec with no columns defined and default as name.


DataTableSpec

public DataTableSpec(DataColumnSpec... colSpecs)
Creates a new DataTableSpec, which is built from an array of DataColumnSpec elements.

Parameters:
colSpecs - an array containing information about all columns
Throws:
NullPointerException - if the given column spec or one of its elements is null
IllegalArgumentException - if the parameter array contains duplicates according to the DataColumnSpec.getName() method

DataTableSpec

public DataTableSpec(DataTableSpec spec1,
                     DataTableSpec spec2)
Constructor for a new DataTableSpec based on two existing specifications that are to be concatenated. The new spec name is combined by both specs' names, though a concatenation of "default+default+...+default" is avoided.

Parameters:
spec1 - The first spec.
spec2 - The second spec.
Throws:
NullPointerException - If one of the given specs is null.
IllegalArgumentException - If the parameter specs contain duplicate names.

DataTableSpec

public DataTableSpec(String name)
Creates an empty DataTableSpec with no columns defined.

Parameters:
name - this spec's name

DataTableSpec

public DataTableSpec(String name,
                     DataColumnSpec... colSpecs)
Creates a new DataTableSpec, which is built from an array of DataColumnSpec elements.

Parameters:
colSpecs - an array containing information about all columns
name - this spec's name, if null a default name is assigned
Throws:
NullPointerException - if the given column spec or one of its elements is null
IllegalArgumentException - if the parameter array contains duplicates according to the DataColumnSpec.getName() method

DataTableSpec

public DataTableSpec(String name,
                     DataTableSpec spec1,
                     DataTableSpec spec2)
Constructor for a new DataTableSpec based on two existing specifications that are to be concatenated.

Parameters:
name - This spec's name.
spec1 - The first spec.
spec2 - The second spec.
Throws:
NullPointerException - If one of the given specs is null.
IllegalArgumentException - If the parameter specs contain duplicate names.

DataTableSpec

public DataTableSpec(String name,
                     String[] names,
                     DataType[] types)
Creates a new DataTableSpec based on a list of names and types. The constructor uses the DataColumnSpec but does not create additional information (values, ...).

Parameters:
name - this spec's identifier, if null a default name will be used
names - an array of names
types - an array of types
Throws:
NullPointerException - if names or types, or one of its elements is null
IllegalArgumentException - if the names and types arrays don't have the same length or if the parameter array names contains duplicates

DataTableSpec

public DataTableSpec(String[] names,
                     DataType[] types)
Creates a new DataTableSpec based on a list of names and types. The constructor uses the DataColumnSpec but does not create additional information (values, ...).

Parameters:
names - an array of names
types - an array of types
Throws:
NullPointerException - if names or types, or one of its elements is null
IllegalArgumentException - if the names and types arrays don't have the same length or if the parameter array names contains duplicates
Method Detail

getPortObjectSpecSerializer

public static PortObjectSpec.PortObjectSpecSerializer<DataTableSpec> getPortObjectSpecSerializer()
Method required by the interface PortObjectSpec. Not meant for public use.

Returns:
A new serializer responsible for loading/saving.

createColumnSpecs

public static final DataColumnSpec[] createColumnSpecs(String[] names,
                                                       DataType[] types)
Static helper method to create a DataColumnSpec array from the given names and types.

Parameters:
names - an array of column names
types - an array of column types
Returns:
an array of DataColumnSpec elements
Throws:
NullPointerException - if one of the arrays is null
IllegalArgumentException - if the arrays do not have the same length

load

public static DataTableSpec load(ConfigRO config)
                          throws InvalidSettingsException
Reads all DataColumnSpec objects from the given ConfigRO and returns a new DataTableSpec object containing them.

Parameters:
config - object to read column specs from
Returns:
a new table spec object containing the just read columns
Throws:
InvalidSettingsException - if the name, number of columns, or a column spec could not be read

containsCompatibleType

public boolean containsCompatibleType(Class<? extends DataValue> valueClass)
Checks if this spec contains a column with a type compatible to the given DataValue class. This method returns false if the argument is null.

Parameters:
valueClass - the class of the data value interface to check for
Returns:
true if at least one column type in the spec is compatible to the provided value

containsName

public boolean containsName(String columnName)
Checks if the given column name occurs in this spec. This method returns false if the argument is null.

Parameters:
columnName - the column name to check
Returns:
true if this spec contains the column name

equalStructure

public boolean equalStructure(DataTableSpec spec)
Returns true if spec has the same column names and types. Two specs are equal if they have the same number of columns and the column specs of the same columns are equal (that implies that the order of the columns has to be the same). The domains, properties, and handlers of the column specs are not included into the comparison.

Parameters:
spec - the DataTableSpec to compare this with
Returns:
true if the two specs have the same column names, and types, otherwise false

equals

public boolean equals(Object obj)
Checks if both DataTableSpecs are equal. In particular it checks the name, indices of property handlers, and the equality of the contained column specs according to the DataColumnSpec.equals(Object) method. This implies that both specs have to have the same number of columns and the order of the columns has to be the same.

Overrides:
equals in class Object
Parameters:
obj - the DataTableSpec to compare this with
Returns:
true if the two specs are equal
See Also:
equalStructure(DataTableSpec), DataColumnSpec.equals(Object)

findColumnIndex

public int findColumnIndex(String columnName)
Finds the column with the specified name in the TableSpec and returns its index, or -1 if the name doesn't exist in the table. This method returns -1 if the argument is null.

Parameters:
columnName - the name to search for
Returns:
the index of the column with the specified name, or -1 if not found.

getColumnSpec

public DataColumnSpec getColumnSpec(int index)
Returns column information of the column with the provided index.

Parameters:
index - the column index within the table
Returns:
the column specification
Throws:
ArrayIndexOutOfBoundsException - if the index is out of range

getColumnSpec

public DataColumnSpec getColumnSpec(String column)
Returns the DataColumnSpec of the column with the provided name. This method returns null if the argument is null.

Parameters:
column - the column name to find the spec for
Returns:
the column specification or null if not available

getName

public String getName()
Returns the name of this DataTableSpec.

Returns:
the name of this table spec

getNumColumns

public int getNumColumns()
Returns the number of columns.

Returns:
the number of columns

getRowColor

public ColorAttr getRowColor(DataRow row)
Returns the color that an object should have when displaying information concerning this row (for instance in a scatterplot). The color is determined by the ColorHandler of this spec, which is associated with exactly one column. The color therefore depends on the value of the corresponding cell of the given row.

Parameters:
row - the row for which the color is requested
Returns:
a color attr object holding the colors associate to that row

getRowShape

public ShapeFactory.Shape getRowShape(DataRow row)
Return the shape that an object should have when displaying information concerning this row (for instance in a scatterplot). The shape is determined by the ShapeHandler of this spec, which is associated with exactly one column. The shape therefore depends on the value of the corresponding cell of the given row.

Parameters:
row - the row for which the shape is requested
Returns:
the shape object associated with this row

getRowSize

@Deprecated
public double getRowSize(DataRow row)
Deprecated. use row size factor instead

Return the size (in percent) that an object should have when displaying information concerning this row (for instance in a scatterplot). The size is determined by the SizeHandler of this spec, which is associated with exactly one column. The size therefore depends on the value of the corresponding cell of the given row.

Parameters:
row - the row for which the size is requested
Returns:
size in [0,1] or 0 if an error occurred (illegal cell, missing)

getRowSizeFactor

public double getRowSizeFactor(DataRow row)
Return the size (as a scaling factor) that an object should have when displaying information concerning this row (for instance in a scatterplot). The size is determined by the SizeHandler of this spec, which is associated with exactly one column. The size therefore depends on the value of the corresponding cell of the given row.

Parameters:
row - the row for which the size is requested
Returns:
size in [1, ) or 1 if an error occurred (illegal cell, missing)

hashCode

public int hashCode()

Overrides:
hashCode in class Object

iterator

public Iterator<DataColumnSpec> iterator()
Returns an iterator for the contained DataColumnSpec elements. The iterator does not support the remove method (table specs are immutable).

Specified by:
iterator in interface Iterable<DataColumnSpec>
Returns:
iterator of the underlying list of DataColumnSpecs
See Also:
Iterable.iterator()

save

public void save(ConfigWO config)
Saves the table spec name and all DataColumnSpecs to the given ConfigWO object.

Parameters:
config - the config object to save this table specs to

mergeDataTableSpecs

public static DataTableSpec mergeDataTableSpecs(DataTableSpec... specs)
This method merges two or more DataTableSpecs. If the DataTableSpecs have equal structure (which is required if you call this method) their domains, Color-, Shape and Size-Handlers are merged. That means:

This factory method is used when two or more tables shall be (row-wise) concatenated, for instance in ExecutionContext#createConcatenateTable.

Parameters:
specs - The DataTableSpecs to merge.
Returns:
a DataTableSpec with merged domain information from both input DataTableSpecs.
Throws:
IllegalArgumentException - if the structures of the DataTableSpecs do not match, the array is empty, or the array or one of its elements is null.

getUniqueColumnName

public static String getUniqueColumnName(DataTableSpec spec,
                                         String columnName)
Returns a column name, which is not contained in specified DataTableSpec. This method is used when the argument spec serves as basis for a new DataTableSpec, which is extended by additional columns. In order to ensure uniqueness of column names, one can use this method to check if the argument string is contained in the argument spec. If this is the case, this method will "uniquify" the argument string and append a "(# i)" where i is a running index.

Parameters:
spec - The argument spec to check.
columnName - The desired column name
Returns:
columnName if it is not contained in the argument spec or columnName amended by some index otherwise.
Throws:
NullPointerException - If one of the arguments is null.

guessNominalClassColumn

public static final String guessNominalClassColumn(DataTableSpec spec,
                                                   boolean withValues)
Guesses the column in the argument spec that likely contains the class attribute. The guessing is based on column names, whereby names as specified in CLASS_COLUMN_NAMES are preferably considered. The returned column's name, if not null, is ensured to be compatible to NominalValue and also has possible values attached, if so specified by the boolean argument; it returns null if there are no such columns fulfilling these constraints.

Parameters:
spec - the argument spec
withValues - with or without possible values
Returns:
first hit in spec or null

toString

public String toString()
The string summary of all column specs of this table spec.

Overrides:
toString in class Object
Returns:
A string summary of all column specs.

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 PortObjectSpec
Returns:
an array of views for the port object spec, each displayed as a tab in the out port view


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.