Package io.deephaven.engine.table

Interface Table

All Superinterfaces:
AttributeMap<Table>, DynamicNode, GridAttributes<Table>, LivenessManager, LivenessNode, LivenessReferent, LogOutputAppendable, LongSizedDataStructure, NotificationQueue.Dependency, SystemicObject<Table>, TableOperations<Table,Table>
All Known Subinterfaces:
LazySnapshotTable, TableAdapter, TableDefaults
All Known Implementing Classes:
AppendOnlyArrayBackedInputTable, BarrageBlinkTable, BarrageRedirectedTable, BarrageTable, BaseTable, DeferredViewTable, InitialSnapshotTable, InMemoryTable, KeyedArrayBackedInputTable, PartitionAwareSourceTable, QueryReplayGroupedTable, QueryTable, QueryTable.FilteredTable, RedefinableTable, ReplayGroupedFullTable, ReplayLastByGroupedTable, ReplayTable, ReplayTableBase, SimpleSourceTable, SourceTable, TimeTable, UncoalescedTable, UpdatableTable, UpdateSourceQueryTable
public interface Table extends LongSizedDataStructure, LivenessNode, NotificationQueue.Dependency, DynamicNode, SystemicObject<Table>, TableOperations<Table,Table>, AttributeMap<Table>, GridAttributes<Table>
A Deephaven table.

  • Field Details

    • INPUT_TABLE_ATTRIBUTE

      static final String INPUT_TABLE_ATTRIBUTE
      See Also:

    • KEY_COLUMNS_ATTRIBUTE

      static final String KEY_COLUMNS_ATTRIBUTE
      See Also:

    • UNIQUE_KEYS_ATTRIBUTE

      static final String UNIQUE_KEYS_ATTRIBUTE
      See Also:

    • FILTERABLE_COLUMNS_ATTRIBUTE

      static final String FILTERABLE_COLUMNS_ATTRIBUTE
      See Also:

    • TOTALS_TABLE_ATTRIBUTE

      static final String TOTALS_TABLE_ATTRIBUTE
      See Also:

    • ADD_ONLY_TABLE_ATTRIBUTE

      static final String ADD_ONLY_TABLE_ATTRIBUTE
      If this attribute is set, we can only add new row keys, we can never shift them, modify them, or remove them.
      See Also:

    • APPEND_ONLY_TABLE_ATTRIBUTE

      static final String APPEND_ONLY_TABLE_ATTRIBUTE
      If this attribute is set, we can only append new row keys to the end of the table. We can never shift them, modify them, or remove them.
      See Also:

    • TEST_SOURCE_TABLE_ATTRIBUTE

      static final String TEST_SOURCE_TABLE_ATTRIBUTE
      See Also:

    • SORTED_COLUMNS_ATTRIBUTE

      static final String SORTED_COLUMNS_ATTRIBUTE
      The query engine may set or read this attribute to determine if a table is sorted by a particular column.
      See Also:

    • SYSTEMIC_TABLE_ATTRIBUTE

      static final String SYSTEMIC_TABLE_ATTRIBUTE
      See Also:

    • AGGREGATION_ROW_LOOKUP_ATTRIBUTE

      static final String AGGREGATION_ROW_LOOKUP_ATTRIBUTE
      Attribute on aggregation results used for hierarchical table construction. Specification is left to the implementation.
      See Also:

    • SORT_REVERSE_LOOKUP_ATTRIBUTE

      static final String SORT_REVERSE_LOOKUP_ATTRIBUTE
      Attribute on sort results used for hierarchical table construction. Specification is left to the implementation.
      See Also:

    • SNAPSHOT_VIEWPORT_TYPE

      static final String SNAPSHOT_VIEWPORT_TYPE
      See Also:

    • MERGED_TABLE_ATTRIBUTE

      static final String MERGED_TABLE_ATTRIBUTE
      This attribute is used internally by TableTools.merge to detect successive merges. Its presence indicates that it is safe to decompose the table into its multiple constituent parts.
      See Also:

    • INITIALLY_EMPTY_COALESCED_SOURCE_TABLE_ATTRIBUTE

      static final String INITIALLY_EMPTY_COALESCED_SOURCE_TABLE_ATTRIBUTE

      This attribute is applied to the descendants of source tables, and takes on Boolean values.

      • True for the result of coalesce() on source tables and their children if the source table was initially empty on coalesce.
      • Missing for all other tables.
      This effectively serves as a hint that filters may have been poorly selected, resulting in an empty result. If size() > 0, this hint should be disregarded.
      See Also:

    • PREVIEW_PARENT_TABLE

      static final String PREVIEW_PARENT_TABLE
      This attribute stores a reference to a table that is the parent table for a Preview Table.
      See Also:

    • NON_DISPLAY_TABLE

      static final String NON_DISPLAY_TABLE
      Set this attribute for tables that should not be displayed in the UI.
      See Also:

    • PLUGIN_NAME

      static final String PLUGIN_NAME
      Set this attribute to load a plugin for this table in the Web Client
      See Also:

    • BARRAGE_PERFORMANCE_KEY_ATTRIBUTE

      static final String BARRAGE_PERFORMANCE_KEY_ATTRIBUTE
      Set this attribute to enable collection of barrage performance stats.
      See Also:

  • Method Details

    • getDefinition

      @ConcurrentMethod TableDefinition getDefinition()

    • meta

      @ConcurrentMethod Table meta()
      Provides column metadata in Table form. Convenience method, behaves exactly the same as getDefinition().getColumnDefinitionsTable().
      Returns:
      A Table of metadata about this Table's columns.

    • getDescription

      @ConcurrentMethod String getDescription()

    • numColumns

      @ConcurrentMethod int numColumns()
      Get the number of columns defined for this table. Equivalent to getDefinition().getColumns().length.
      Returns:
      The number of columns defined for this table

    • hasColumns

      @ConcurrentMethod boolean hasColumns(String... columnNames)
      Determines whether this Table contains a column for each string in the specified array of columnNames.
      Parameters:
      columnNames - The array of column names to be checked for inclusion in this table. Must not be null.
      Returns:
      true if this Table contains a column for each and every string in the columnNames array; false if any element of columnNames is not the name of a column in this table

    • hasColumns

      @ConcurrentMethod boolean hasColumns(Collection<String> columnNames)
      Determines whether this Table contains a column for each string in the specified collection of columnNames.
      Parameters:
      columnNames - The collection of column names to be checked for inclusion in this table. Must not be null.
      Returns:
      true if this Table contains a column for each and every string in the columnNames collection; false if any element of columnNames is not the name of a column in this table

    • isRefreshing

      @ConcurrentMethod boolean isRefreshing()
      Description copied from interface: DynamicNode
      Is the node updating?
      Specified by:
      isRefreshing in interface DynamicNode
      Returns:
      true if the node is updating; false otherwise.

    • getRowSet

      TrackingRowSet getRowSet()
      Returns:
      The TrackingRowSet that exposes the row keys present in this Table

    • sizeForInstrumentation

      long sizeForInstrumentation()
      Returns:
      Size if it is currently known without subsequent steps to coalesce the Table, else null

    • isEmpty

      boolean isEmpty()
      Returns true if this table has no rows (i.e. size() == 0).
      Returns:
      true if this table has no rows

    • isFlat

      @ConcurrentMethod boolean isFlat()
      Return true if this table is guaranteed to be flat. The RowSet of a flat table will be from 0...numRows-1.

    • getColumnSource

      <T> ColumnSource<T> getColumnSource(String sourceName)
      Retrieves a ColumnSource. It is conveniently cast to ColumnSource<Object> using the type that caller expects. This differs from getColumnSource(String, Class) which uses the provided Class object to verify that the data type is a subclass of the expected class.

      The success of this call is equivalent to getDefinition().checkColumn(sourceName), which is the preferred way to check for compatibility in scenarios where the caller does not want the implementation to potentially invoke coalesce().

      Type Parameters:
      T - The target type, as a type parameter. Inferred from context.
      Parameters:
      sourceName - The name of the column
      Returns:
      The column source for sourceName, parameterized by T
      See Also:

    • getColumnSource

      <T> ColumnSource<T> getColumnSource(String sourceName, Class<? extends T> clazz)
      Retrieves a ColumnSource and casts it to the target class clazz.

      The success of this call is equivalent to getDefinition().checkColumn(sourceName, clazz), which is the preferred way to check for compatibility in scenarios where the caller does not want to the implementation to potentially invoke coalesce().

      Type Parameters:
      T - The target type, as a type parameter. Intended to be inferred from clazz.
      Parameters:
      sourceName - The name of the column
      clazz - The target type
      Returns:
      The column source for sourceName, parameterized by T
      See Also:

    • getColumnSource

      <T> ColumnSource<T> getColumnSource(String sourceName, Class<? extends T> clazz, @Nullable Class<?> componentType)
      Retrieves a ColumnSource and ColumnSource.cast(Class, Class) casts} it to the target class clazz and componentType.

      The success of this call is equivalent to getDefinition().checkColumn(sourceName, clazz, componentType), which is the preferred way to check for compatibility in scenarios where the caller does not want the implementation to potentially invoke coalesce().

      Type Parameters:
      T - The target type, as a type parameter. Intended to be inferred from clazz.
      Parameters:
      sourceName - The name of the column
      clazz - The target type
      componentType - The target component type, may be null
      Returns:
      The column source for sourceName, parameterized by T
      See Also:

    • getColumnSourceMap

      Map<String,? extends ColumnSource<?>> getColumnSourceMap()

    • getColumnSources

      Collection<? extends ColumnSource<?>> getColumnSources()

    • columnIterator

      <DATA_TYPE> CloseableIterator<DATA_TYPE> columnIterator(@NotNull @NotNull String columnName)

    • characterColumnIterator

      CloseablePrimitiveIteratorOfChar characterColumnIterator(@NotNull @NotNull String columnName)

    • byteColumnIterator

      CloseablePrimitiveIteratorOfByte byteColumnIterator(@NotNull @NotNull String columnName)

    • shortColumnIterator

      CloseablePrimitiveIteratorOfShort shortColumnIterator(@NotNull @NotNull String columnName)

    • integerColumnIterator

      CloseablePrimitiveIteratorOfInt integerColumnIterator(@NotNull @NotNull String columnName)

    • longColumnIterator

      CloseablePrimitiveIteratorOfLong longColumnIterator(@NotNull @NotNull String columnName)

    • floatColumnIterator

      CloseablePrimitiveIteratorOfFloat floatColumnIterator(@NotNull @NotNull String columnName)

    • doubleColumnIterator

      CloseablePrimitiveIteratorOfDouble doubleColumnIterator(@NotNull @NotNull String columnName)

    • objectColumnIterator

      <DATA_TYPE> CloseableIterator<DATA_TYPE> objectColumnIterator(@NotNull @NotNull String columnName)

    • wouldMatch

      @ConcurrentMethod Table wouldMatch(WouldMatchPair... matchers)
      A table operation that applies the supplied predicate to each row in the table and produces columns containing the pass/fail result of the predicate application. This is similar to TableOperations.where(String...) except that instead of selecting only rows that meet the criteria, new columns are added with the result of the comparison.
      Returns:
      a table with new columns containing the filter result for each row.

    • wouldMatch

      @ConcurrentMethod Table wouldMatch(String... expressions)

    • dropColumnFormats

      @ConcurrentMethod Table dropColumnFormats()

    • renameColumns

      @ConcurrentMethod Table renameColumns(Collection<Pair> pairs)
      Produce a new table with the specified columns renamed using the specified pairs. The renames are simultaneous and unordered, enabling direct swaps between column names. The resulting table retains the original column ordering after applying the specified renames.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once
      Parameters:
      pairs - The columns to rename
      Returns:
      The new table, with the columns renamed

    • renameColumns

      @ConcurrentMethod Table renameColumns(String... pairs)
      Produce a new table with the specified columns renamed using the syntax "NewColumnName=OldColumnName". The renames are simultaneous and unordered, enabling direct swaps between column names. The resulting table retains the original column ordering after applying the specified renames.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once
      Parameters:
      pairs - The columns to rename
      Returns:
      The new table, with the columns renamed

    • renameAllColumns

      @ConcurrentMethod Table renameAllColumns(UnaryOperator<String> renameFunction)
      Produce a new table with the specified columns renamed using the provided function. The renames are simultaneous and unordered, enabling direct swaps between column names. The resulting table retains the original column ordering after applying the specified renames.

      IllegalArgumentException will be thrown:

      • if a destination column is used more than once
      Parameters:
      renameFunction - The function to apply to each column name
      Returns:
      The new table, with the columns renamed

    • formatColumns

      @ConcurrentMethod Table formatColumns(String... columnFormats)

    • formatRowWhere

      @ConcurrentMethod Table formatRowWhere(String condition, String formula)

    • formatColumnWhere

      @ConcurrentMethod Table formatColumnWhere(String columnName, String condition, String formula)

    • moveColumnsUp

      @ConcurrentMethod Table moveColumnsUp(String... columnsToMove)
      Produce a new table with the specified columns moved to the leftmost position. Columns can be renamed with the usual syntax, i.e. "NewColumnName=OldColumnName"). The renames are simultaneous and unordered, enabling direct swaps between column names. All other columns are left in their original order.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once
      Parameters:
      columnsToMove - The columns to move to the left (and, optionally, to rename)
      Returns:
      The new table, with the columns rearranged as explained above

    • moveColumnsDown

      @ConcurrentMethod Table moveColumnsDown(String... columnsToMove)
      Produce a new table with the specified columns moved to the rightmost position. Columns can be renamed with the usual syntax, i.e. "NewColumnName=OldColumnName"). The renames are simultaneous and unordered, enabling direct swaps between column names. All other columns are left in their original order.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once
      Parameters:
      columnsToMove - The columns to move to the right (and, optionally, to rename)
      Returns:
      The new table, with the columns rearranged as explained above

    • moveColumns

      @ConcurrentMethod Table moveColumns(int index, String... columnsToMove)
      Produce a new table with the specified columns moved to the specified index. Column indices begin at 0. Columns can be renamed with the usual syntax, i.e. "NewColumnName=OldColumnName"). The renames are simultaneous and unordered, enabling direct swaps between column names. The resulting table retains the original column ordering except for the specified columns, which are inserted at the specified index, in the order of columnsToMove, after the effects of applying any renames.

      IllegalArgumentException will be thrown:

      • if a source column does not exist
      • if a source column is used more than once
      • if a destination column is used more than once

      Values of index outside the range of 0 to the number of columns in the table (exclusive) will be clamped to the nearest valid index.

      Parameters:
      index - The index to which the specified columns should be moved
      columnsToMove - The columns to move to the specified index (and, optionally, to rename)
      Returns:
      The new table, with the columns rearranged as explained above

    • slice

      @ConcurrentMethod Table slice(long firstPositionInclusive, long lastPositionExclusive)
      Extracts a subset of a table by row position.

      If both firstPosition and lastPosition are positive, then the rows are counted from the beginning of the table. The firstPosition is inclusive, and the lastPosition is exclusive. The TableOperations.head(long)(N) call is equivalent to slice(0, N). The firstPosition must be less than or equal to the lastPosition.

      If firstPosition is positive and lastPosition is negative, then the firstRow is counted from the beginning of the table, inclusively. The lastPosition is counted from the end of the table. For example, slice(1, -1) includes all rows but the first and last. If the lastPosition would be before the firstRow, the result is an emptyTable.

      If firstPosition is negative, and lastPosition is zero, then the firstRow is counted from the end of the table, and the end of the slice is the size of the table. slice(-N, 0) is equivalent to TableOperations.tail(long)(N).

      If the firstPosition is negative and the lastPosition is negative, they are both counted from the end of the table. For example, slice(-2, -1) returns the second to last row of the table.

      If firstPosition is negative and lastPosition is positive, then firstPosition is counted from the end of the table, inclusively. The lastPosition is counted from the beginning of the table, exclusively. For example, slice(-3, 5) returns all rows starting from the third-last row to the fifth row of the table. If there are no rows between these positions, the function will return an empty table.

      Parameters:
      firstPositionInclusive - the first position to include in the result
      lastPositionExclusive - the last position to include in the result
      Returns:
      a new Table, which is the request subset of rows from the original table

    • slicePct

      @ConcurrentMethod Table slicePct(double startPercentInclusive, double endPercentExclusive)
      Extracts a subset of a table by row percentages.

      Returns a subset of table in the range [floor(startPercentInclusive * sizeOfTable), floor(endPercentExclusive * sizeOfTable)). For example, for a table of size 10, slicePct(0.1, 0.7) will return a subset from the second row to the seventh row. Similarly, slicePct(0, 1) would return the entire table (because row positions run from 0 to size-1). The percentage arguments must be in range [0,1], otherwise the function returns an error.

      Parameters:
      startPercentInclusive - the starting percentage point for rows to include in the result, range [0, 1]
      endPercentExclusive - the ending percentage point for rows to include in the result, range [0, 1]
      Returns:
      a new Table, which is the requested subset of rows from the original table

    • headPct

      @ConcurrentMethod Table headPct(double percent)
      Provides a head that selects a dynamic number of rows based on a percent.
      Parameters:
      percent - the fraction of the table to return between [0, 1]. The number of rows will be rounded up. For example if there are 3 rows, headPct(50) returns the first two rows. For percent values outside [0, 1], the function will throw an exception.

    • tailPct

      @ConcurrentMethod Table tailPct(double percent)
      Provides a tail that selects a dynamic number of rows based on a percent.
      Parameters:
      percent - the fraction of the table to return between [0, 1]. The number of rows will be rounded up. For example if there are 3 rows, tailPct(50) returns the last two rows. For percent values outside [0, 1], the function will throw an exception.

    • headBy

      Table headBy(long nRows, Collection<String> groupByColumnNames)

    • headBy

      Table headBy(long nRows, String... groupByColumnNames)

    • tailBy

      Table tailBy(long nRows, Collection<String> groupByColumnNames)

    • tailBy

      Table tailBy(long nRows, String... groupByColumnNames)

    • applyToAllBy

      @ConcurrentMethod Table applyToAllBy(String formulaColumn, String columnParamName, Collection<? extends ColumnName> groupByColumns)
      Groups data according to groupByColumns and applies formulaColumn to each of columns not altered by the grouping operation. columnParamName is used as place-holder for the name of each column inside formulaColumn.
      Parameters:
      formulaColumn - Formula applied to each column
      columnParamName - The parameter name used as a placeholder for each column
      groupByColumns - The grouping columns as in TableOperations.groupBy(Collection)

    • applyToAllBy

      @ConcurrentMethod Table applyToAllBy(String formulaColumn, Collection<? extends ColumnName> groupByColumns)
      Groups data according to groupByColumns and applies formulaColumn to each of columns not altered by the grouping operation.
      Parameters:
      formulaColumn - Formula applied to each column, uses parameter each to refer to each colum it being applied to
      groupByColumns - The grouping columns as in TableOperations.groupBy(Collection)

    • applyToAllBy

      @ConcurrentMethod Table applyToAllBy(String formulaColumn, String... groupByColumns)
      Groups data according to groupByColumns and applies formulaColumn to each of columns not altered by the grouping operation.
      Parameters:
      formulaColumn - Formula applied to each column, uses parameter each to refer to each colum it being applied to
      groupByColumns - The grouping columns as in TableOperations.groupBy()

    • removeBlink

      @ConcurrentMethod Table removeBlink()
      If this table is a blink table, i.e. it has BLINK_TABLE_ATTRIBUTE set to true, return a child without the attribute, restoring standard semantics for aggregation operations.
      Returns:
      A non-blink child table, or this table if it is not a blink table

    • partitionBy

      @ConcurrentMethod PartitionedTable partitionBy(boolean dropKeys, String... keyColumnNames)
      Create a PartitionedTable from this table, partitioned according to the specified key columns.

      The underlying partitioned table backing the result contains each row in this table in exactly one of the result's constituent tables.

      Parameters:
      dropKeys - Whether to drop key columns in the output constituent tables
      keyColumnNames - The names of the key columns to partition by
      Returns:
      A PartitionedTable keyed by keyColumnNames

    • partitionBy

      @ConcurrentMethod PartitionedTable partitionBy(String... keyColumnNames)
      Equivalent to partitionBy(false, keyColumnNames)

      Create a PartitionedTable from this table, partitioned according to the specified key columns. Key columns are never dropped from the output constituent tables.

      The underlying partitioned table backing the result contains each row in this table in exactly one of the result's constituent tables.

      Parameters:
      keyColumnNames - The names of the key columns to partition by
      Returns:
      A PartitionedTable keyed by keyColumnNames

    • partitionedAggBy

      @ConcurrentMethod PartitionedTable partitionedAggBy(Collection<? extends Aggregation> aggregations, boolean preserveEmpty, Table initialGroups, String... keyColumnNames)
      Convenience method that performs an TableOperations.aggBy(io.deephaven.api.agg.Aggregation) and wraps the result in a PartitionedTable. If aggregations does not include a partition, one will be added automatically with the default constituent column name and behavior used in partitionBy(String...).
      Parameters:
      aggregations - The aggregations to apply
      preserveEmpty - Whether to keep result rows for groups that are initially empty or become empty as a result of updates. Each aggregation operator defines its own value for empty groups.
      initialGroups - A table whose distinct combinations of values for the groupByColumns should be used to create an initial set of aggregation groups. All other columns are ignored. This is useful in combination with preserveEmpty == true to ensure that particular groups appear in the result table, or with preserveEmpty == false to control the encounter order for a collection of groups and thus their relative order in the result. Changes to initialGroups are not expected or handled; if initialGroups is a refreshing table, only its contents at instantiation time will be used. If initialGroups == null, the result will be the same as if a table with no rows was supplied.
      keyColumnNames - The names of the key columns to aggregate by
      Returns:
      A PartitionedTable keyed by keyColumnNames

    • rollup

      @ConcurrentMethod RollupTable rollup(Collection<? extends Aggregation> aggregations)
      Create a rollup table.

      A rollup table aggregates all rows of the table.

      Parameters:
      aggregations - The aggregations to perform
      Returns:
      a hierarchical table with the rollup applied

    • rollup

      @ConcurrentMethod RollupTable rollup(Collection<? extends Aggregation> aggregations, boolean includeConstituents)
      Create a rollup table.

      A rollup table aggregates all rows of the table.

      Parameters:
      aggregations - The aggregations to perform
      includeConstituents - set to true to include the constituent rows at the leaf level
      Returns:
      a hierarchical table with the rollup applied

    • rollup

      @ConcurrentMethod RollupTable rollup(Collection<? extends Aggregation> aggregations, String... groupByColumns)
      Create a rollup table.

      A rollup table aggregates by the specified columns, and then creates a hierarchical table which re-aggregates using one less aggregation column on each level. The column that is no longer part of the aggregation key is replaced with null on each level.

      Parameters:
      aggregations - The aggregations to perform
      groupByColumns - the columns to group by
      Returns:
      a hierarchical table with the rollup applied

    • rollup

      @ConcurrentMethod RollupTable rollup(Collection<? extends Aggregation> aggregations, boolean includeConstituents, String... groupByColumns)
      Create a rollup table.

      A rollup table aggregates by the specified columns, and then creates a hierarchical table which re-aggregates using one less aggregation column on each level. The column that is no longer part of the aggregation key is replaced with null on each level.

      Parameters:
      aggregations - The aggregations to perform
      groupByColumns - the columns to group by
      includeConstituents - set to true to include the constituent rows at the leaf level
      Returns:
      a hierarchical table with the rollup applied

    • rollup

      @ConcurrentMethod RollupTable rollup(Collection<? extends Aggregation> aggregations, Collection<? extends ColumnName> groupByColumns)
      Create a rollup table.

      A rollup table aggregates by the specified columns, and then creates a hierarchical table which re-aggregates using one less aggregation column on each level. The column that is no longer part of the aggregation key is replaced with null on each level.

      Parameters:
      aggregations - The aggregations to perform
      groupByColumns - the columns to group by
      Returns:
      a hierarchical table with the rollup applied

    • rollup

      @ConcurrentMethod RollupTable rollup(Collection<? extends Aggregation> aggregations, boolean includeConstituents, Collection<? extends ColumnName> groupByColumns)
      Create a rollup table.

      A rollup table aggregates by the specified columns, and then creates a hierarchical table which re-aggregates using one less aggregation column on each level. The column that is no longer part of the aggregation key is replaced with null on each level.

      Parameters:
      aggregations - The aggregations to perform
      includeConstituents - set to true to include the constituent rows at the leaf level
      groupByColumns - the columns to group by
      Returns:
      a hierarchical table with the rollup applied

    • tree

      @ConcurrentMethod TreeTable tree(String idColumn, String parentColumn)
      Create a hierarchical tree table.

      The structure of the table is encoded by an "id" and a "parent" column. The id column should represent a unique identifier for a given row, and the parent column indicates which row is the parent for a given row. Rows that have a null parent are part of the "root" table.

      It is possible for rows to be "orphaned" if their parent is non-null and does not exist in the table. See TreeTable.promoteOrphans(Table, String, String).

      Parameters:
      idColumn - The name of a column containing a unique identifier for a particular row in the table
      parentColumn - The name of a column containing the parent's identifier, null for rows that are part of the root table
      Returns:
      A TreeTable organized according to the parent-child relationships expressed by idColumn and parentColumn

    • coalesce

      @ConcurrentMethod Table coalesce()
      Explicitly ensure that any work needed to make a table addressable, iterable, or queryable has been done, and return the coalesced child table if appropriate.
      Returns:
      This table, or a fully-coalesced child

    • getSubTable

      Table getSubTable(TrackingRowSet rowSet)
      Get a Table that contains a sub-set of the rows from this. The result will share the same column sources and definition as this table.

      The result will not update on its own. The caller must also establish an appropriate listener to update rowSet and propagate updates.

      Parameters:
      rowSet - The row set for the result
      Returns:
      A new sub-table

    • apply

      <R> R apply(Function<Table,R> function)
      Applies a function to this table.

      This is useful if you have a reference to a table or a proxy and want to run a series of operations against the table without each individual operation resulting in an RMI.

      Type Parameters:
      R - the return type of function
      Parameters:
      function - the function to run, its single argument will be this table
      Returns:
      the return value of function
      ImplNote:
      If the UGP is not required the Function.apply(Object) method should be annotated with ConcurrentMethod.

    • flatten

      @ConcurrentMethod Table flatten()
      Creates a version of this table with a flat RowSet.

    • withKeys

      @ConcurrentMethod Table withKeys(String... columns)
      Set the table's key columns.
      Returns:
      A copy of this table with the key columns specified, or this if no change was needed

    • withUniqueKeys

      @ConcurrentMethod Table withUniqueKeys(String... columns)
      Set the table's key columns and indicate that each key set will be unique.
      Returns:
      A copy of this table with the unique key columns specified, or this if no change was needed

    • setTotalsTable

      @ConcurrentMethod Table setTotalsTable(String directive)
      Set a totals table for this Table.
      Parameters:
      directive - A packed string of totals table instructions
      Returns:
      A copy of this Table with the totals table attribute set

    • close

      void close()
      Release resources held by this table, possibly destructively. This may render the table unsuitable or unsafe for further use.
      ApiNote:
      In practice, implementations usually just invoke releaseCachedResources().

    • releaseCachedResources

      void releaseCachedResources()
      Attempt to release cached resources held by this table. Unlike close(), this must not render the table unusable for subsequent read operations. Implementations should be sure to call super.releaseCachedResources().

    • awaitUpdate

      void awaitUpdate() throws InterruptedException

      Wait for updates to this Table. Should not be invoked from a TableListener or other notification on this Table's update graph. It may be suitable to wait from another update graph if doing so does not introduce any cycles.

      In some implementations, this call may also terminate in case of interrupt or spurious wakeup.

      Throws:
      InterruptedException - In the event this thread is interrupted
      See Also:

    • awaitUpdate

      boolean awaitUpdate(long timeout) throws InterruptedException

      Wait for updates to this Table. Should not be invoked from a TableListener or other notification on this Table's update graph. It may be suitable to wait from another update graph if doing so does not introduce any cycles.

      In some implementations, this call may also terminate in case of interrupt or spurious wakeup.

      Parameters:
      timeout - The maximum time to wait in milliseconds.
      Returns:
      false if the timeout elapses without notification, true otherwise.
      Throws:
      InterruptedException - In the event this thread is interrupted
      See Also:

    • addUpdateListener

      void addUpdateListener(ShiftObliviousListener listener)
      Subscribe for updates to this table. listener will be invoked via the NotificationQueue associated with this Table.
      Parameters:
      listener - listener for updates

    • addUpdateListener

      void addUpdateListener(ShiftObliviousListener listener, boolean replayInitialImage)
      Subscribe for updates to this table. After the optional initial image, listener will be invoked via the NotificationQueue associated with this Table.
      Parameters:
      listener - listener for updates
      replayInitialImage - true to process updates for all initial rows in the table plus all changes; false to only process changes

    • addUpdateListener

      void addUpdateListener(TableUpdateListener listener)
      Subscribe for updates to this table. listener will be invoked via the NotificationQueue associated with this Table.
      Parameters:
      listener - listener for updates

    • addUpdateListener

      boolean addUpdateListener(TableUpdateListener listener, long requiredLastNotificationStep)
      Subscribe for updates to this table if its last notification step matches requiredLastNotificationStep. listener will be invoked via the NotificationQueue associated with this Table.
      Parameters:
      listener - listener for updates
      requiredLastNotificationStep - the expected last notification step to match
      Returns:
      true if the listener was added, false if the last notification step requirement was not met

    • removeUpdateListener

      void removeUpdateListener(ShiftObliviousListener listener)
      Unsubscribe the supplied listener.
      Parameters:
      listener - listener for updates

    • removeUpdateListener

      void removeUpdateListener(TableUpdateListener listener)
      Unsubscribe the supplied listener.
      Parameters:
      listener - listener for updates

    • isFailed

      boolean isFailed()
      Returns:
      true if this table is in a failure state.