Package io.deephaven.engine.table

Interface ColumnSource<T>

All Superinterfaces:
ChunkSource<Values>, ChunkSource.WithPrev<Values>, ElementSource<T>, FillContextMaker, GetContextMaker, Releasable, TupleExporter<T>, TupleSource<T>
All Known Subinterfaces:
AggregateColumnSource<VECTOR_TYPE,COMPONENT_TYPE>, ChunkColumnSource<T>, ColumnSourceGetDefaults.ForBoolean, ColumnSourceGetDefaults.ForByte, ColumnSourceGetDefaults.ForChar, ColumnSourceGetDefaults.ForDouble, ColumnSourceGetDefaults.ForFloat, ColumnSourceGetDefaults.ForInt, ColumnSourceGetDefaults.ForLong, ColumnSourceGetDefaults.ForLongAsInstant, ColumnSourceGetDefaults.ForObject<DATA_TYPE>, ColumnSourceGetDefaults.ForShort, ColumnSourceGetDefaults.LongBacked<DATA_TYPE>, ContextualizedObjectColumnSource<DATA_TYPE>, ImmutableColumnSource<DATA_TYPE>, ImmutableColumnSourceGetDefaults.ForBoolean, ImmutableColumnSourceGetDefaults.ForByte, ImmutableColumnSourceGetDefaults.ForChar, ImmutableColumnSourceGetDefaults.ForDouble, ImmutableColumnSourceGetDefaults.ForFloat, ImmutableColumnSourceGetDefaults.ForInt, ImmutableColumnSourceGetDefaults.ForLong, ImmutableColumnSourceGetDefaults.ForLongAsInstant, ImmutableColumnSourceGetDefaults.ForObject<DATA_TYPE>, ImmutableColumnSourceGetDefaults.ForShort, ImmutableColumnSourceGetDefaults.LongBacked<DATA_TYPE>, MutableColumnSource<DATA_TYPE>, MutableColumnSourceGetDefaults.ForBoolean, MutableColumnSourceGetDefaults.ForByte, MutableColumnSourceGetDefaults.ForChar, MutableColumnSourceGetDefaults.ForDouble, MutableColumnSourceGetDefaults.ForFloat, MutableColumnSourceGetDefaults.ForInt, MutableColumnSourceGetDefaults.ForLong, MutableColumnSourceGetDefaults.ForLongAsInstant, MutableColumnSourceGetDefaults.ForObject<DATA_TYPE>, MutableColumnSourceGetDefaults.ForShort, MutableColumnSourceGetDefaults.LongBacked<DATA_TYPE>, RegionedColumnSource<DATA_TYPE>, ReverseLookupColumnSource<DATA_TYPE,EXTRA_VALUE_TYPE>, SizedColumnSource<DATA_TYPE>, SizedContextualizedObjectColumnSource<DATA_TYPE>, SsmBackedColumnSource<K,T>, SymbolTableSource<SYMBOL_TYPE>, WritableColumnSource<T>
All Known Implementing Classes:
AbstractArrowColumnSource, AbstractColumnSource, AbstractColumnSource.DefaultedImmutable, AbstractColumnSource.DefaultedMutable, AlternatingColumnSource, ArrayBackedColumnSource, ArrowBooleanColumnSource, ArrowByteColumnSource, ArrowCharColumnSource, ArrowDoubleColumnSource, ArrowFloatColumnSource, ArrowInstantColumnSource, ArrowIntColumnSource, ArrowLocalTimeColumnSource, ArrowLongColumnSource, ArrowObjectColumnSource, ArrowShortColumnSource, ArrowStringColumnSource, ArrowUInt1ColumnSource, ArrowUInt4ColumnSource, ArrowUInt8ColumnSource, BaseAggregateSlicedColumnSource, BitMaskingColumnSource, BitShiftingColumnSource, BooleanArraySource, BooleanAsByteColumnSource, BooleanSingleValueSource, BooleanSparseArraySource, BooleanSparseArraySource.ReinterpretedAsByte, ByteAggregateColumnSource, ByteArraySource, ByteAsBooleanColumnSource, ByteChunkColumnSource, ByteSingleValueSource, ByteSparseArraySource, ByteSsmBackedSource, CharacterArraySource, CharacterSingleValueSource, CharacterSparseArraySource, CharAggregateColumnSource, CharChunkColumnSource, CharSsmBackedSource, CrossJoinRightColumnSource, DelegatingColumnSource, DeltaAwareColumnSource, DoubleAggregateColumnSource, DoubleArraySource, DoubleChunkColumnSource, DoubleNullToZeroColumnSource, DoubleSingleValueSource, DoubleSparseArraySource, DoubleSsmBackedSource, FloatAggregateColumnSource, FloatArraySource, FloatChunkColumnSource, FloatSingleValueSource, FloatSparseArraySource, FloatSsmBackedSource, HashTableColumnSource, Immutable2DByteArraySource, Immutable2DCharArraySource, Immutable2DDoubleArraySource, Immutable2DFloatArraySource, Immutable2DInstantArraySource, Immutable2DIntArraySource, Immutable2DLongArraySource, Immutable2DNanosBasedTimeArraySource, Immutable2DObjectArraySource, Immutable2DShortArraySource, Immutable2DZonedDateTimeArraySource, ImmutableByteArraySource, ImmutableCharArraySource, ImmutableConstantByteSource, ImmutableConstantCharSource, ImmutableConstantDoubleSource, ImmutableConstantFloatSource, ImmutableConstantInstantSource, ImmutableConstantIntSource, ImmutableConstantLongSource, ImmutableConstantNanosBasedTimeSource, ImmutableConstantObjectSource, ImmutableConstantShortSource, ImmutableConstantZonedDateTimeSource, ImmutableDoubleArraySource, ImmutableFloatArraySource, ImmutableInstantArraySource, ImmutableIntArraySource, ImmutableLongArraySource, ImmutableNanosBasedTimeArraySource, ImmutableObjectArraySource, ImmutableShortArraySource, ImmutableZonedDateTimeArraySource, InstantArraySource, InstantAsLongColumnSource, InstantSparseArraySource, InstantSsmSourceWrapper, IntAggregateColumnSource, IntChunkColumnSource, IntegerArraySource, IntegerSingleValueSource, IntegerSparseArraySource, IntSsmBackedSource, LocalDateWrapperSource, LocalTimeWrapperSource, LongAggregateColumnSource, LongArraySource, LongAsInstantColumnSource, LongAsLocalDateColumnSource, LongAsLocalTimeColumnSource, LongAsTimeSource, LongAsZonedDateTimeColumnSource, LongChunkColumnSource, LongSingleValueSource, LongSparseArraySource, LongSsmBackedSource, MergeSortedHelper.SortedMergeColumnSource, NanosBasedTimeArraySource, NanosBasedTimeSparseArraySource, NullValueColumnSource, ObjectAggregateColumnSource, ObjectArraySource, ObjectChunkColumnSource, ObjectSingleValueSource, ObjectSparseArraySource, ObjectSsmBackedSource, PrevColumnSource, RangeAggregateColumnSource, RangeAggregateColumnSourceByte, RangeAggregateColumnSourceChar, RangeAggregateColumnSourceDouble, RangeAggregateColumnSourceFloat, RangeAggregateColumnSourceInt, RangeAggregateColumnSourceLong, RangeAggregateColumnSourceObject, RangeAggregateColumnSourceShort, RedirectedColumnSource, ReversedColumnSource, RowKeyColumnSource, RowPositionColumnSource, RowSetColumnSourceWrapper, ShiftedColumnSource, ShortAggregateColumnSource, ShortArraySource, ShortChunkColumnSource, ShortSingleValueSource, ShortSparseArraySource, ShortSsmBackedSource, SingleValueColumnSource, SingleValueObjectColumnSource, SlicedByteAggregateColumnSource, SlicedCharAggregateColumnSource, SlicedDoubleAggregateColumnSource, SlicedFloatAggregateColumnSource, SlicedIntAggregateColumnSource, SlicedLongAggregateColumnSource, SlicedObjectAggregateColumnSource, SlicedShortAggregateColumnSource, SparseArrayColumnSource, SwitchColumnSource, SymbolTableToUniqueIdSource, UnboxedLongBackedColumnSource, UnboxedLongBackedColumnSource, UnboxedTimeBackedColumnSource, UngroupedArrayColumnSource, UngroupedBooleanArrayColumnSource, UngroupedBoxedBooleanArrayColumnSource, UngroupedBoxedByteArrayColumnSource, UngroupedBoxedByteObjectVectorColumnSource, UngroupedBoxedCharArrayColumnSource, UngroupedBoxedCharObjectVectorColumnSource, UngroupedBoxedDoubleArrayColumnSource, UngroupedBoxedDoubleObjectVectorColumnSource, UngroupedBoxedFloatArrayColumnSource, UngroupedBoxedFloatObjectVectorColumnSource, UngroupedBoxedIntArrayColumnSource, UngroupedBoxedIntObjectVectorColumnSource, UngroupedBoxedLongArrayColumnSource, UngroupedBoxedLongObjectVectorColumnSource, UngroupedBoxedShortArrayColumnSource, UngroupedBoxedShortObjectVectorColumnSource, UngroupedByteArrayColumnSource, UngroupedByteVectorColumnSource, UngroupedCharArrayColumnSource, UngroupedCharVectorColumnSource, UngroupedColumnSource, UngroupedDoubleArrayColumnSource, UngroupedDoubleVectorColumnSource, UngroupedFloatArrayColumnSource, UngroupedFloatVectorColumnSource, UngroupedIntArrayColumnSource, UngroupedIntVectorColumnSource, UngroupedLongArrayColumnSource, UngroupedLongVectorColumnSource, UngroupedObjectVectorColumnSource, UngroupedShortArrayColumnSource, UngroupedShortVectorColumnSource, UnionColumnSource, ViewColumnSource, WritableByteAsBooleanColumnSource, WritableRedirectedColumnSource, ZonedDateTimeArraySource, ZonedDateTimeAsLongSource, ZonedDateTimeSparseArraySource
public interface ColumnSource<T> extends ChunkSource.WithPrev<Values>, ElementSource<T>, TupleSource<T>, Releasable
A "source" for column data - allows cell values to be looked up by (long) keys.

Note for implementors: All ColumnSource implementations must map RowSequence.NULL_ROW_KEY to a null value for all get and getPrev methods.

  • Field Details

    • ZERO_LENGTH_COLUMN_SOURCE_ARRAY

      static final ColumnSource[] ZERO_LENGTH_COLUMN_SOURCE_ARRAY

  • Method Details

    • getType

      Class<T> getType()

    • getComponentType

      Class<?> getComponentType()

    • getChunkType

      @FinalDefault default ChunkType getChunkType()
      Description copied from interface: ChunkSource
      Get the most suitable ChunkType for use with this ChunkSource.
      Specified by:
      getChunkType in interface ChunkSource<T>
      Returns:
      The ChunkType

    • match

      WritableRowSet match(boolean invertMatch, boolean usePrev, boolean caseInsensitive, @Nullable DataIndex dataIndex, @NotNull @NotNull RowSet mapper, Object... keys)
      Return a row set where the values in the column source match the given keys.
      Parameters:
      invertMatch - Whether to invert the match, i.e. return the rows where the values do not match the given keys
      usePrev - Whether to use the previous values for the ColumnSource
      caseInsensitive - Whether to perform a case insensitive match
      dataIndex - An optional data index that can be used to accelerate the match (the index table must be included in snapshot controls or otherwise guaranteed to be current)
      mapper - Restrict results to this row set
      keys - The keys to match in the column
      Returns:
      The rows that match the given keys

    • startTrackingPrevValues

      default void startTrackingPrevValues()
      ColumnSource implementations that track previous values have the option to not actually start tracking previous values until this method is called. This is an option, not an obligation: some simple ColumnSource implementations (like TSingleValueSource for various T) always track previous values; other implementations (like PrevColumnSource) never do; some (like TArrayColumnSource) only start tracking once this method is called. An immutable column source can not have distinct prev values; therefore it is implemented as a no-op.

    • isImmutable

      boolean isImmutable()
      Determine if this column source is immutable, meaning that the values at a given row key never change.
      Returns:
      true if the values at a given row key of the column source never change, false otherwise

    • releaseCachedResources

      @OverridingMethodsMustInvokeSuper default void releaseCachedResources()
      Release any resources held for caching purposes. Implementations need not guarantee that concurrent accesses are correct, as the purpose of this method is to ensure cleanup for column sources that will no longer be used.
      Specified by:
      releaseCachedResources in interface Releasable

    • allowsReinterpret

      <ALTERNATE_DATA_TYPE> boolean allowsReinterpret(@NotNull @NotNull Class<ALTERNATE_DATA_TYPE> alternateDataType)
      Test if a reinterpret call will succeed.
      Parameters:
      alternateDataType - The alternative type to consider
      Returns:
      If a reinterpret on this column source with the supplied alternateDataType will succeed.

    • reinterpret

      <ALTERNATE_DATA_TYPE> ColumnSource<ALTERNATE_DATA_TYPE> reinterpret(@NotNull @NotNull Class<ALTERNATE_DATA_TYPE> alternateDataType) throws IllegalArgumentException
      Provide an alternative view into the data underlying this column source.
      Parameters:
      alternateDataType - The alternative type to expose
      Returns:
      A column source of the alternate data type, backed by the same underlying data.
      Throws:
      IllegalArgumentException - If the alternativeDataType supplied is not supported

    • createTuple

      default T createTuple(long rowKey)
      Description copied from interface: TupleSource
      Create a tuple for key column values at the supplied row key.
      Specified by:
      createTuple in interface TupleSource<T>
      Parameters:
      rowKey - The row key
      Returns:
      The resulting tuple

    • createPreviousTuple

      default T createPreviousTuple(long rowKey)
      Description copied from interface: TupleSource
      Create a tuple for previous key column values at the supplied row key.
      Specified by:
      createPreviousTuple in interface TupleSource<T>
      Parameters:
      rowKey - The row key
      Returns:
      The resulting tuple

    • createTupleFromValues

      default T createTupleFromValues(@NotNull @NotNull Object... values)
      Description copied from interface: TupleSource
      Create a tuple for the supplied (boxed) values.
      Specified by:
      createTupleFromValues in interface TupleSource<T>
      Parameters:
      values - The values
      Returns:
      The resulting tuple

    • tupleLength

      @FinalDefault default int tupleLength()
      Description copied from interface: TupleExporter
      Get the number of elements in tuples supported by this TupleExporter.
      Specified by:
      tupleLength in interface TupleExporter<T>
      Returns:
      The number of elements in tuples supported by this TupleExporter

    • exportElement

      @FinalDefault default <ELEMENT_TYPE> void exportElement(@NotNull T tuple, int elementIndex, @NotNull @NotNull WritableColumnSource<ELEMENT_TYPE> writableSource, long destinationIndexKey)
      Description copied from interface: TupleExporter
      Export a single element from the tuple, identified by its element index, to the destination row key of the supplied writable source.

      For the empty tuple, this is unsupported.

      For singles, this will copy the sole element, possibly in boxed form.

      For doubles and longer, this will copy the specified element without any unnecessary boxing.

      Specified by:
      exportElement in interface TupleExporter<T>
      Parameters:
      tuple - The tuple to export an element from
      elementIndex - The element index to export
      writableSource - The destination
      destinationIndexKey - The destination row key

    • exportElement

      @FinalDefault default Object exportElement(@NotNull T tuple, int elementIndex)
      Description copied from interface: TupleExporter
      Export a single element (identified by elementIndex) from the tuple, boxing as necessary.

      For the empty tuple, this is unsupported.

      Specified by:
      exportElement in interface TupleExporter<T>
      Parameters:
      tuple - The tuple to export an element from
      elementIndex - The element index to export
      Returns:
      The exported element, boxed when necessary

    • exportAllTo

      @FinalDefault default void exportAllTo(Object @NotNull [] dest, @NotNull T tuple)
      Description copied from interface: TupleExporter
      Fill an Object[] with all elements from the tuple, boxing as necessary.

      For the empty tuple, this is unsupported.

      Specified by:
      exportAllTo in interface TupleExporter<T>
      Parameters:
      dest - The destination Object[]
      tuple - The tuple to export from

    • getPrevSource

      ColumnSource<T> getPrevSource()
      Specified by:
      getPrevSource in interface ChunkSource.WithPrev<T>
      Returns:
      a chunk source which accesses the previous values.

    • cast

      @FinalDefault default <TYPE> ColumnSource<TYPE> cast(Class<? extends TYPE> clazz)
      Returns this ColumnSource, parameterized by <TYPE>, if the data type of this column (as given by getType()) can be cast to clazz. This is analogous to casting the objects provided by this column source to clazz.

      For example, the following code will throw an exception if the "MyString" column does not actually contain String data: 

           ColumnSource<String> colSource = table.getColumnSource("MyString").cast(String.class)

      Due to the nature of type erasure, the JVM will still insert an additional cast to TYPE when elements are retrieved from the column source, such as with String myStr = colSource.get(0).

      Type Parameters:
      TYPE - The target type, as a type parameter. Intended to be inferred from clazz.
      Parameters:
      clazz - The target type.
      Returns:
      A ColumnSource parameterized by TYPE.

    • cast

      @FinalDefault default <TYPE> ColumnSource<TYPE> cast(Class<? extends TYPE> clazz, @Nullable String colName)
      Returns this ColumnSource, parameterized by <TYPE>, if the data type of this column (as given by getType()) can be cast to clazz. This is analogous to casting the objects provided by this column source to clazz.

      For example, the following code will throw an exception if the "MyString" column does not actually contain String data: 

           ColumnSource<String> colSource = table.getColumnSource("MyString").cast(String.class, "MyString")

      Due to the nature of type erasure, the JVM will still insert an additional cast to TYPE when elements are retrieved from the column source, such as with String myStr = colSource.get(0).

      Type Parameters:
      TYPE - The target type, as a type parameter. Intended to be inferred from clazz.
      Parameters:
      clazz - The target type.
      colName - An optional column name, which will be included in exception messages.
      Returns:
      A ColumnSource parameterized by TYPE.

    • cast

      @FinalDefault default <TYPE> ColumnSource<TYPE> cast(Class<? extends TYPE> clazz, @Nullable Class<?> componentType)
      Returns this ColumnSource, parameterized by <TYPE>, if the data type of this column (as given by getType()) can be cast to clazz. This is analogous to casting the objects provided by this column source to clazz. Additionally, this checks that the component type of this column (as given by getComponentType()) can be cast to componentType (both must be present and castable, or both must be null).

      For example, the following code will throw an exception if the "MyString" column does not actually contain String data: 

           ColumnSource<String> colSource = table.getColumnSource("MyString").cast(String.class, null)

      Due to the nature of type erasure, the JVM will still insert an additional cast to TYPE when elements are retrieved from the column source, such as with String myStr = colSource.get(0).

      Type Parameters:
      TYPE - The target type, as a type parameter. Intended to be inferred from clazz.
      Parameters:
      clazz - The target type.
      componentType - The target component type, may be null.
      Returns:
      A ColumnSource parameterized by TYPE.

    • cast

      @FinalDefault default <TYPE> ColumnSource<TYPE> cast(Class<? extends TYPE> clazz, @Nullable Class<?> componentType, @Nullable String colName)
      Returns this ColumnSource, parameterized by <TYPE>, if the data type of this column (as given by getType()) can be cast to clazz. This is analogous to casting the objects provided by this column source to clazz. Additionally, this checks that the component type of this column (as given by getComponentType()) can be cast to componentType (both must be present and castable, or both must be null).

      For example, the following code will throw an exception if the "MyString" column does not actually contain String data: 

           ColumnSource<String> colSource = table.getColumnSource("MyString").cast(String.class, null, "MyString")

      Due to the nature of type erasure, the JVM will still insert an additional cast to TYPE when elements are retrieved from the column source, such as with String myStr = colSource.get(0).

      Type Parameters:
      TYPE - The target type, as a type parameter. Intended to be inferred from clazz.
      Parameters:
      clazz - The target type.
      componentType - The target component type, may be null.
      colName - An optional column name, which will be included in exception messages.
      Returns:
      A ColumnSource parameterized by TYPE.

    • isStateless

      default boolean isStateless()
      Most column sources will return the same value for a given row without respect to the order that the rows are read. Those columns sources are considered "stateless" and should return true. Some column sources, however may be dependent on evaluation order. For example, a formula that updates a Map must be evaluated from the first row to the last row. A column source that has the potential to depend on the order of evaluation must return false.
      Returns:
      true if this is a stateless column source