Class ColumnDefinition<TYPE>

java.lang.Object
io.deephaven.engine.table.ColumnDefinition<TYPE>
All Implemented Interfaces:
LogOutputAppendable

public class ColumnDefinition<TYPE> extends Object implements LogOutputAppendable
Column definition for all Deephaven columns.

Every column definition has a valid column name: each factory method throws NameValidator.InvalidNameException (an IllegalArgumentException) if the name is not, as determined by NameValidator.validateColumnName(String).

  • Field Details

    • ZERO_LENGTH_COLUMN_DEFINITION_ARRAY

      public static final ColumnDefinition<?>[] ZERO_LENGTH_COLUMN_DEFINITION_ARRAY
  • Method Details

    • ofBoolean

      public static ColumnDefinition<Boolean> ofBoolean(@NotNull @NotNull String name)
      Creates a normal boolean column definition, with data type Boolean.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofByte

      public static ColumnDefinition<Byte> ofByte(@NotNull @NotNull String name)
      Creates a normal byte column definition, with data type byte.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofChar

      public static ColumnDefinition<Character> ofChar(@NotNull @NotNull String name)
      Creates a normal char column definition, with data type char.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofShort

      public static ColumnDefinition<Short> ofShort(@NotNull @NotNull String name)
      Creates a normal short column definition, with data type short.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofInt

      public static ColumnDefinition<Integer> ofInt(@NotNull @NotNull String name)
      Creates a normal int column definition, with data type int.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofLong

      public static ColumnDefinition<Long> ofLong(@NotNull @NotNull String name)
      Creates a normal long column definition, with data type long.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofFloat

      public static ColumnDefinition<Float> ofFloat(@NotNull @NotNull String name)
      Creates a normal float column definition, with data type float.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofDouble

      public static ColumnDefinition<Double> ofDouble(@NotNull @NotNull String name)
      Creates a normal double column definition, with data type double.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofString

      public static ColumnDefinition<String> ofString(@NotNull @NotNull String name)
      Creates a normal string column definition, with data type String.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofTime

      public static ColumnDefinition<Instant> ofTime(@NotNull @NotNull String name)
      Creates a normal timestamp column definition, with data type Instant.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofLocalTime

      public static ColumnDefinition<LocalTime> ofLocalTime(@NotNull @NotNull String name)
      Creates a normal time-of-day column definition, with data type LocalTime.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofLocalDate

      public static ColumnDefinition<LocalDate> ofLocalDate(@NotNull @NotNull String name)
      Creates a normal date column definition, with data type LocalDate.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • ofDuration

      public static ColumnDefinition<Duration> ofDuration(@NotNull @NotNull String name)
      Creates a normal duration column definition, with data type Duration.
      Parameters:
      name - the column name
      Returns:
      the column definition
    • of

      public static ColumnDefinition<?> of(String name, Type<?> type)
      Creates a normal column definition for a qst Type. The data type is:
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if type is a CustomType for void or Void
    • of

      public static ColumnDefinition<?> of(String name, PrimitiveType<?> type)
      Creates a normal column definition for a qst PrimitiveType. The data type is the primitive type, except Boolean for BooleanType.
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
    • of

      public static ColumnDefinition<?> of(String name, GenericType<?> type)
      Creates a normal column definition for a qst GenericType. The data type is the same as for the corresponding primitive type for boxed types, and otherwise the type's class, with the array or Vector component type as the component type for array types. A CustomType whose class is a Vector implementation gets an inferred component type, as by fromGenericType(String, Class).
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if type is a CustomType for void or Void
    • of

      public static <T> ColumnDefinition<T> of(String name, ArrayType<T,?> type)
      Creates a normal column definition for a qst ArrayType: a native array or Vector type. The data type is the type's class, and the component type is the type's component type.
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
    • of

      public static <T> ColumnDefinition<T> of(String name, PrimitiveVectorType<T,?> type)
      Creates a normal column definition for a qst PrimitiveVectorType, such as IntVector. The data type is the Vector type, and the component type is its primitive component type.
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
    • of

      public static <T> ColumnDefinition<T> of(String name, GenericVectorType<T,?> type)
      Creates a normal column definition for a qst GenericVectorType, an ObjectVector of a generic type. The data type is ObjectVector, and the component type is the class of the type's component type, which supplies the element type that ObjectVector only expresses through generics: ObjectVector<Number> has component type Number, making it the Vector equivalent of Number[].
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
    • of

      public static <T> ColumnDefinition<T> of(String name, NativeArrayType<T,?> type)
      Creates a normal column definition for a qst NativeArrayType. The data type is the array type, and the component type is the class of its component type.
      Parameters:
      name - the column name
      type - the type
      Returns:
      the column definition
    • ofVector

      public static <T extends Vector<?>> ColumnDefinition<T> ofVector(@NotNull @NotNull String name, @NotNull @NotNull Class<T> vectorType)
      Creates a normal Vector column definition. The data type is vectorType, and the component type is its element type: the primitive type for primitive Vectors, such as int for IntVector (the Vector equivalent of int[]); and Object for ObjectVector, making it ObjectVector<Object>, the Vector equivalent of Object[]. To give an ObjectVector a more specific element type, use ofVector(String, Class, Class).
      Parameters:
      name - the column name
      vectorType - the Vector type
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if vectorType is not a recognized Vector type
    • ofVector

      public static <T extends Vector<?>> ColumnDefinition<T> ofVector(@NotNull @NotNull String name, @NotNull @NotNull Class<T> vectorType, @Nullable @Nullable Class<?> componentType)
      Creates a normal Vector column definition. The data type is vectorType, and the component type is its element type.

      ObjectVector expresses its element type only through generics, so componentType supplies it: ofVector(name, ObjectVector.class, Number.class) describes ObjectVector<Number>, the Vector equivalent of Number[]. Primitive Vectors fix their element type, so for them componentType must be that primitive type, such as int for IntVector.

      Parameters:
      name - the column name
      vectorType - the Vector type
      componentType - the element type: any reference type but Void for ObjectVector, or the primitive type for a primitive Vector; or null for the default, which is Object for ObjectVector
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if vectorType is not a recognized Vector type, or componentType is not valid for it
    • fromGenericType

      public static <T> ColumnDefinition<T> fromGenericType(@NotNull @NotNull String name, @NotNull @NotNull Class<T> dataType)
      Creates a normal column definition for an arbitrary data type, inferring the component type. Equivalent to fromGenericType(name, dataType, null, ColumnType.Normal); see fromGenericType(String, Class, Class, ColumnType) for how the data and component types are determined.
      Parameters:
      name - the column name
      dataType - the data type
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if dataType is not a valid column data type
    • fromGenericType

      public static <T> ColumnDefinition<T> fromGenericType(@NotNull @NotNull String name, @NotNull @NotNull Class<T> dataType, @Nullable @Nullable Class<?> componentType)
      Creates a normal column definition for an arbitrary data type. Equivalent to fromGenericType(name, dataType, componentType, ColumnType.Normal); see fromGenericType(String, Class, Class, ColumnType) for how the data and component types are determined.
      Parameters:
      name - the column name
      dataType - the data type
      componentType - the component type, for array and Vector data types; inferred when null
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if dataType is not a valid column data type, or componentType is not valid for dataType
    • fromGenericType

      public static <T> ColumnDefinition<T> fromGenericType(@NotNull @NotNull String name, @NotNull @NotNull Class<T> dataType, @Nullable @Nullable Class<?> componentType, @NotNull @NotNull ColumnDefinition.ColumnType columnType)
      Creates a column definition for an arbitrary data type.

      Like column sources, column definitions use Boolean for boolean columns and the primitive type for other primitive columns, so dataType is normalized: boolean becomes Boolean, and the other boxed primitive types become their primitive types. Other data types are used as is.

      For array and Vector data types, the component type is the element type. When componentType is null, it is inferred: the array's component type for array data types; the primitive type for primitive Vectors, such as int for IntVector; and Object for ObjectVector. Since ObjectVector expresses its element type only through generics, give componentType to describe, for example, ObjectVector<Number>, the Vector equivalent of Number[]. Other data types have no component type unless one is given.

      Parameters:
      name - the column name
      dataType - the data type; may not be void or Void, nor an array of Void
      componentType - the element type for array and Vector data types: for arrays, the array's component type or a more specific one; for ObjectVector, any reference type; for primitive Vectors, their primitive type. Never void or Void, nor an array of them. Or null to infer it
      columnType - the column type
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if dataType is not a valid column data type, or componentType is not valid for dataType
    • from

      public static ColumnDefinition<?> from(ColumnHeader<?> header)
      Creates a normal column definition from a qst ColumnHeader. The name is the header's name, and the data type is determined from the header's type as by of(String, Type).
      Parameters:
      header - the column header
      Returns:
      the column definition
      Throws:
      IllegalArgumentException - if the header's type is a CustomType for void or Void
    • create

      public static <T> ColumnDefinition<T> create(@NotNull @NotNull String name, @NotNull @NotNull Class<T> dataType)
      Creates a normal column definition with no component type, after checking that it is valid. This calls create(String, Class, Class, ColumnType) with a null component type, and so, as there, uses the values as provided without normalization or inference.
      Parameters:
      name - the column name
      dataType - the data type; array and Vector data types are invalid here, as they require a component type
      Returns:
      the column definition
      Throws:
      NameValidator.InvalidNameException - if name is not a valid column name
      IllegalArgumentException - if dataType is not valid
    • create

      public static <T> ColumnDefinition<T> create(@NotNull @NotNull String name, @NotNull @NotNull Class<T> dataType, @Nullable @Nullable Class<?> componentType, @NotNull @NotNull ColumnDefinition.ColumnType columnType)
      Creates a column definition, after checking that it is valid: that name is a valid column name, that dataType is a valid column data type, and that componentType is valid for dataType.

      The values are used exactly as provided, without normalization or inference. Unlike fromGenericType(String, Class, Class, ColumnType), this does not map boolean or the boxed primitive types to the types that columns use, and does not infer a missing component type: a dataType of boolean or Integer is rejected rather than converted to Boolean or int, and an array or Vector data type with a null componentType is rejected rather than given one. Callers that want normalization or inference should use fromGenericType, of, or one of the ofVector methods.

      Parameters:
      name - the column name
      dataType - the data type, as column definitions represent it: Boolean rather than boolean, and the primitive type rather than its boxed type for other primitives; never void or Void
      componentType - the component type; required for array and Vector data types, where it is validated against the data type as described at getComponentType(); may be null for other data types
      columnType - the column type
      Returns:
      the column definition
      Throws:
      NameValidator.InvalidNameException - if name is not a valid column name
      IllegalArgumentException - if dataType or componentType is not valid
    • getName

      @NotNull public @NotNull String getName()
      The column name. It is always a valid column name, as determined by NameValidator.validateColumnName(String).
      Returns:
      the column name
    • getDataType

      @NotNull public @NotNull Class<TYPE> getDataType()
      The data type: the type of the column's values.

      Like column sources, column definitions use Boolean for boolean columns, and the primitive type for other primitive columns (such as int, never Integer). The data type is never void or Void. For array and Vector data types, the type of the elements is the component type.

      Returns:
      the data type
    • getComponentType

      @Nullable public @Nullable Class<?> getComponentType()
      The component type: for array and Vector data types, the type of the elements.

      A native array type already carries its element type, so for an array data type the component type is the array's component type (Number for Number[]), or a more specific type that all elements are known to have (Integer for a Number[] holding only Integers). Primitive Vectors likewise fix their element type: the component type of an IntVector column is int, as for int[]. ObjectVector, however, expresses its element type only through generics, so the component type supplies it: an ObjectVector column with component type Number is an ObjectVector<Number>, the Vector equivalent of Number[], not an Object[]-like column with a narrower component type.

      Other data types have no component type, unless one was given when creating the definition.

      Returns:
      the component type, or null if there is none
    • getColumnType

      @NotNull public @NotNull ColumnDefinition.ColumnType getColumnType()
    • withPartitioning

      public ColumnDefinition<TYPE> withPartitioning()
    • withNormal

      public ColumnDefinition<TYPE> withNormal()
    • withDataType

      public <Other> ColumnDefinition<Other> withDataType(@NotNull @NotNull Class<Other> newDataType)
    • withDataType

      public <Other> ColumnDefinition<Other> withDataType(@NotNull @NotNull Class<Other> newDataType, @Nullable @Nullable Class<?> newComponentType)
    • withName

      public ColumnDefinition<?> withName(@NotNull @NotNull String newName)
    • isPartitioning

      public boolean isPartitioning()
    • isDirect

      public boolean isDirect()
    • isCompatible

      public boolean isCompatible(@NotNull @NotNull ColumnDefinition<?> other)
      Compares two ColumnDefinitions somewhat more permissively than equals, disregarding matters of storage and derivation. Checks for equality of name, dataType, and componentType. As such, this method has an equivalence relation, ie A.isCompatible(B) == B.isCompatible(A).
      Parameters:
      other - The ColumnDefinition to compare to
      Returns:
      Whether the ColumnDefinition defines a column whose name and data are compatible with this ColumnDefinition
    • hasCompatibleDataType

      public boolean hasCompatibleDataType(@NotNull @NotNull ColumnDefinition<?> other)
      Compares two ColumnDefinitions somewhat more permissively than equals, disregarding matters of name, storage and derivation. Checks for equality of dataType, and componentType. As such, this method has an equivalence relation, ie A.hasCompatibleDataType(B) == B.hasCompatibleDataType(A).
      Parameters:
      other - - The ColumnDefinition to compare to.
      Returns:
      True if the ColumnDefinition defines a column whose data is compatible with this ColumnDefinition.
    • describeForCompatibility

      public String describeForCompatibility()
      Describes the column definition with respect to the fields that are checked in isCompatible(ColumnDefinition).
      Returns:
      the description for compatibility
    • describeDifferences

      public void describeDifferences(@NotNull @NotNull List<String> differences, @NotNull @NotNull ColumnDefinition<?> other, @NotNull @NotNull String lhs, @NotNull @NotNull String rhs, @NotNull @NotNull String prefix, boolean includeColumnType)
      Enumerate the differences between this ColumnDefinition, and another one. Lines will be of the form "lhs attribute 'value' does not match rhs attribute 'value'.
      Parameters:
      differences - an array to which differences can be added
      other - the ColumnDefinition under comparison
      lhs - what to call "this" definition
      rhs - what to call the other definition
      prefix - begin each difference with this string
      includeColumnType - whether to include columnType comparisons
    • checkCastTo

      public final void checkCastTo(Class<?> destDataType)
      Checks if objects of type dataType can be cast to destDataType (equivalent to destDataType.isAssignableFrom(dataType)). If not, this throws a ClassCastException.
      Parameters:
      destDataType - the destination data type
    • checkCastTo

      public final void checkCastTo(Class<?> destDataType, @Nullable @Nullable Class<?> destComponentType)
      Checks if objects of type dataType can be cast to destDataType (equivalent to destDataType.isAssignableFrom(dataType)) and checks that objects of type componentType can be cast to destComponentType (both component types must be present and cast-able, or both must be null; when both present, is equivalent to destComponentType.isAssignableFrom(componentType)). If not, this throws a ClassCastException.
      Parameters:
      destDataType - the destination data type
      destComponentType - the destination component type, may be null
    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • append

      public LogOutput append(LogOutput logOutput)
      Specified by:
      append in interface LogOutputAppendable