org.knime.core.data
Class DataType

java.lang.Object
  org.knime.core.data.DataType

public final class DataType
extends Object

Type description associated with a certain implementation of a DataCell. It essentially keeps the list of compatible DataValue interfaces (i.e. for which a type cast is possible), a list of DataValueRenderer for this type, and (potentially more than one) DataValueComparator for DataCell of this type.

There are two forms of DataTypes: the so-called native type, which is assigned to a certain DataCell, and the non-native type, which only consists of a list of compatible DataValue classes.

Furthermore, it provides the possibility to get a common super type for two DataCells. In case they are not compatible to each other, the returned DataType is calculated based on the intersection of both compatible DataValue lists.

In addition, the DataCell representing missing values is defined in this class and can be accessed via getMissingCell().

On details of DataType in KNIME see the package description and the manual on how to define customized DataTypes.

Author:

Bernd Wiswedel, University of Konstanz

See Also:

DataCell, DataValue

Method Summary

static DataType	cloneChangePreferredValue(DataType from, Class<? extends DataValue> preferred) Clones the given DataType but changes its preferred value class to the passed preferred value.
boolean	equals(Object other) Types are equal if the list of compatible DataValue classes matches (ordering does not matter), both types have the same preferred value class or both do not have a preferred value class.
static <T extends DataCell> DataCellSerializer<T>	getCellSerializer(Class<T> cl) Returns a DataCellSerializer for the runtime class of a DataCell or null if the passed class of type DataCell does not implement
DataType	getCollectionElementType() Get the type of the elements in collection or null if this type does not represent a collection.
static DataType	getCommonSuperType(DataType type1, DataType type2) Returns a type which is compatible to only those values, both given types are compatible to, i.e.
DataValueComparator	getComparator() A comparator for DataCell objects of this type.
Icon	getIcon() Gets and returns an icon from the DataValue.UtilityFactory representing this type.
static DataCell	getMissingCell() A cell representing a missing DataCell where the value is unknown.
Class<? extends DataValue>	getPreferredValueClass() Returns the preferred value class of the current DataType or null if not available.
DataValueRendererFamily	getRenderer(DataColumnSpec spec) Returns a family of all renderers that are available for this DataType.
static DataType	getType(Class<? extends DataCell> cell) Returns the runtime DataType for a DataCell implementation.
static DataType	getType(Class<? extends DataCell> cellImplementsCollectionDataValue, DataType collectionElementType) Implementation of getType(Class) dedicated for special cell classes that represent collections of DataCell.
static DataValue.UtilityFactory	getUtilityFor(Class<? extends DataValue> value) Determines the UtilityFactory for a given DataValue implementation.
List<Class<? extends DataValue>>	getValueClasses() Returns a copy of all DataValues to which this DataType is compatible to.
int	hashCode() The hash code is based on the preferred value flag and the hash codes of all DataValue classes.
boolean	isASuperTypeOf(DataType type) Returns true if this type is a supertype of the passed type, that is, the argument is compatible to all DataValue classes of this type (and may be more).
boolean	isCollectionType() Does this type represent a collection.
boolean	isCompatible(Class<? extends DataValue> valueClass) Checks if the given DataValue.class is compatible to this type.
static DataType	load(ConfigRO config) Loads a DataType from a given ConfigRO.
void	save(ConfigWO config) Saves this DataType to the given ConfigWO.
String	toString() Returns the simple name of the DataCell class (if any) or Non-Native the toString() results of all compatible values classes.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

cloneChangePreferredValue

public static DataType cloneChangePreferredValue(DataType from,
                                                 Class<? extends DataValue> preferred)

Clones the given DataType but changes its preferred value class to the passed preferred value. The returned non-native DataType may or may not be equal to the from DataType depending on the preferred value class of from DataType and will be created newly.

Parameters:

from - the DataType to clone

preferred - the new preferred value class

Returns:

a new DataType with the given preferred value class

Throws:

IllegalArgumentException - if from.isCompatible(preferred) returns false

NullPointerException - if any argument is null

getCellSerializer

public static <T extends DataCell> DataCellSerializer<T> getCellSerializer(Class<T> cl)

Returns a DataCellSerializer for the runtime class of a DataCell or null if the passed class of type DataCell does not implement

   public static <T extends DataCell> 
       DataCellSerializer<T> getCellSerializer(
       final Class<T> cl) {
 

The DataCellSerializer is defined through a static access method in DataCell. If no such method exists or the method can't be invoked (using reflection), this method returns null and ordinary Java serialization is used for saving and loading the cell. See also the class documentation of DataCell for more information on the static access method.

Type Parameters:

T - the runtime class of the DataCell

Parameters:

cl - the DataCell's class

Returns:

the DataCellSerializer defined in the DataCell implementation or null if no such serializer is available

Throws:

NullPointerException - if the argument is null

getCommonSuperType

public static DataType getCommonSuperType(DataType type1,
                                          DataType type2)

Returns a type which is compatible to only those values, both given types are compatible to, i.e. it contains the intersection of both value lists. This super type can be safely asked for a comparator for cells of both specified types, or a renderer for DataCells of any of the given types. The returned object could be one of the arguments passed in, if one type is compatible to all (and more) types the other is compatible to.

As there could be more than one common compatible type (if both cells implement multiple value interfaces), the common super type could be a new instance of DataType with no native type, which only contains the list of those common compatible types.

If both types have no common data values, the resulting DataType has no preferred value class; its list of compatible value classes will only contain (the class representation of) DataValue, and the cell class is null.

Parameters:

type1 - type 1

type2 - type 2

Returns:

a type compatible to types both arguments are compatible to

Throws:

NullPointerException - if one of the given types is null

getMissingCell

public static DataCell getMissingCell()

A cell representing a missing DataCell where the value is unknown. The type of the returned data cell is compatible to any DataValue interface (although you can't cast the returned cell to the value) and has default icons, renderers, and comparators.

Returns:

singleton of a missing cell

getType

public static DataType getType(Class<? extends DataCell> cell)

Returns the runtime DataType for a DataCell implementation. If no such DataType has been created before (i.e. this method is called the first time with the current argument), the return value is created and hashed. The returned DataType will claim to be compatible to all DataValue classes the cell is implementing (i.e. what DataValue interfaces are implemented by cell) and will bundle meta information of the cell such as renderer, icon, and comparators.

This method is the only way to determine the DataType of a DataCell. However, most standard cell implementations have a static member for convenience access, e.g. DoubleCell.TYPE.

If the argument class implements a CollectionDataValue (a special cell that bundles multiple cells into one), consider to use getType(Class, DataType) in order to retain the sub element type. In most cases, however, this method is the preferred way to determine the DataType to a cell class.

Parameters:

cell - the runtime class of DataCell for which the DataType is requested

Returns:

the corresponding DataType cell, never null

Throws:

NullPointerException - if the argument is null

See Also:

DataCell, DataValue, DataCell.getType()

getType

public static DataType getType(Class<? extends DataCell> cellImplementsCollectionDataValue,
                               DataType collectionElementType)

Implementation of getType(Class) dedicated for special cell classes that represent collections of DataCell. The second argument collectionElementType must be non-null if and only if cellImplementsCollectionDataValue implements CollectionDataValue, otherwise an IllegalArgumentException is thrown.

For a general description of types representing collections, refer to the section in the manual.

Parameters:

cellImplementsCollectionDataValue - The cell class hosting the collection by implementing CollectionDataValue. (Other cell are also accepted, but then collectionElementType must be null.)

collectionElementType - The type of the elements in the collection.

Returns:

A data type representing that type of collection.

Throws:

IllegalArgumentException - As outlined above.

NullPointerException - If the class argument is null.

getUtilityFor

public static DataValue.UtilityFactory getUtilityFor(Class<? extends DataValue> value)

Determines the UtilityFactory for a given DataValue implementation. This method tries to access a static field in the DataValue class:

   public static final UtilityFactory UTILITY;
 

If no such field exists, this method returns the factory of one of the super interfaces. If it exists but has the wrong access scope or if it is not static, a warning message is logged and the member of one of the super interfaces is returned. If no UTILITY member can be found, finally the DataValue class returns a correct implementation, since it is at the top of the hierarchy.

Parameters:

value - the runtime class of the DataCell

Returns:

the UtilityFactory given in the cell implementation

Throws:

NullPointerException - if the argument or the found UTILITY member is null

load

public static DataType load(ConfigRO config)
                     throws InvalidSettingsException

Loads a DataType from a given ConfigRO.

Parameters:

config - load DataType from

Returns:

a DataType which fits the given ConfigRO

Throws:

InvalidSettingsException - if the DataType could not be loaded from the given ConfigRO

getCollectionElementType

public DataType getCollectionElementType()

Get the type of the elements in collection or null if this type does not represent a collection. This method returns a non-null value if and only if this type is is compatible to CollectionDataValue.

Returns:

the type of the elements in a collection or null.

isCollectionType

public boolean isCollectionType()

Does this type represent a collection. This method is a convenience short cut for isCompatible(CollectionDataValue.class).

If this method returns true, getCollectionElementType() is guaranteed to return a non-null value.

Returns:

If this type represent

equals

public boolean equals(Object other)

Types are equal if the list of compatible DataValue classes matches (ordering does not matter), both types have the same preferred value class or both do not have a preferred value class.

Overrides:

equals in class Object

Parameters:

other - the object to check with

Returns:

true if the both types have the same preferred value class and the list of compatible types matches, otherwise false

See Also:

Object.equals(java.lang.Object)

getComparator

public DataValueComparator getComparator()

A comparator for DataCell objects of this type. Will return the native comparator (if provided), or the first comparator of the value classes found. If no comparator is available the comparator of the String representation will be returned.

Returns:

a comparator for cells of this type

getIcon

public Icon getIcon()

Gets and returns an icon from the DataValue.UtilityFactory representing this type. This is used in table headers and lists, for instance.

Returns:

an icon for this type

getPreferredValueClass

public Class<? extends DataValue> getPreferredValueClass()

Returns the preferred value class of the current DataType or null if not available. The preferred value class is defined through the DataCell implementation. This method returns null if either the cell implementation lacks the information or this DataType has been created as an intersection of two types whose preferred value classes do not match.

Returns:

the preferred value class or null

getRenderer

public DataValueRendererFamily getRenderer(DataColumnSpec spec)

Returns a family of all renderers that are available for this DataType. The returned DataValueRendererFamily will contain all renderers that are supported or available through the compatible DataValue interfaces. If no renderer was declared by the DataValue interfaces, this method will make sure that at least a default renderer (using the DataCell.toString() method) is returned.

The DataColumnSpec is passed to all renderer families retrieved from the underlying DataValue.UtilityFactory. Most of the renderer implementations won't need column domain information but some do. For instance a class that renders the double value in the column according to the minimum/maximum values in the DataColumnDomain.

Parameters:

spec - the column spec to the column for which the renderer will be used

Returns:

a family of all renderers that are available for this DataType

getValueClasses

public List<Class<? extends DataValue>> getValueClasses()

Returns a copy of all DataValues to which this DataType is compatible to. The returned List is non-modifiable, subsequent changes to the list will fail with an exception. The list does not contain duplicates.

Returns:

a non-modifiable list of compatible DataTypes

hashCode

public int hashCode()

The hash code is based on the preferred value flag and the hash codes of all DataValue classes.

Overrides:

hashCode in class Object

isASuperTypeOf

public boolean isASuperTypeOf(DataType type)

Returns true if this type is a supertype of the passed type, that is, the argument is compatible to all DataValue classes of this type (and may be more). In other words, this object is more general than the argument or this object supports less compatible values than the argument.

This is mostly used to test if a given DataCell can be added to a given DataColumnSpec. The DataCell's type must be compatible to (at least) all DataValue interfaces the column's type is compatible to. If the column's type is a supertype of the cell's type, it's safe to add the cell to the column.

Parameters:

type - the type to test, whether this is a supertype of it

Returns:

true if this type is a (one of many possible) supertype of the argument type, otherwise false

Throws:

NullPointerException - if the type argument is null

See Also:

isCompatible(Class)

isCompatible

public boolean isCompatible(Class<? extends DataValue> valueClass)

Checks if the given DataValue.class is compatible to this type. It returns true, if DataCells of this type can be type-casted to the valueClass or if one assignable value class was found or if this type represents the missing cell. This method returns false, if the argument is null or if no assignable class was found.

Parameters:

valueClass - class to check compatibility for

Returns:

true if compatible

save

public void save(ConfigWO config)

Saves this DataType to the given ConfigWO. If it is a native type only the class name of the cell class is stored. Otherwise the names of all value classes and whether it has a preferred value is written to the ConfigWO.

Parameters:

config - write to this ConfigWO

toString

public String toString()

Returns the simple name of the DataCell class (if any) or Non-Native the toString() results of all compatible values classes.

Overrides:

toString in class Object