Package io.deephaven.engine.table

Interface TableUpdate

All Superinterfaces:
LogOutputAppendable
All Known Implementing Classes:
TableUpdateImpl
public interface TableUpdate extends LogOutputAppendable
Table update propagation structure, describing the rows and columns that were added, removed, modified, and shifted on a given cycle.

TableUpdateListeners must not mutate TableUpdates they receive.

A TableUpdate received by a TableUpdateListener is only valid during the updating phase of the cycle that it was created on. Listeners should be very careful to ensure that any deferred or asynchronous usage respects this constraint.

All deferred or asynchronous usage must be guarded by a successful acquire(), and terminated by a release(). In the typical pattern, the TableUpdateListener acquires the TableUpdate when making a notification, and releases it when the notification has been completely run. Users typically extend a base TableUpdateListener implementation that handles this on their behalf, but must be sure not to inadvertently use the TableUpdate outside its expected context without taking additional precautions.

  • Method Details

    • append

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

    • acquire

      TableUpdate acquire()
      Acquire a reference count for this TableUpdate that will keep it from being cleaned up until it is released. Code that calls this method must be sure to call release() when the TableUpdate is no longer needed. Acquiring a TableUpdate does not change the constraint that it must not be used outside the updating phase for which it was created.
      Returns:
      this for convenience

    • release

      void release()
      Release a previously-acquired reference count for this object.

    • empty

      default boolean empty()
      Returns:
      true if no changes occurred in this update

    • validate

      void validate() throws AssertionFailure
      Throws an AssertionFailure if this update is not structurally valid, i.e. its accessors will return non-null, usable data structures. This does not test for usage outside the appropriate updating phase.
      Throws:
      AssertionFailure

    • getModifiedPreShift

      @NotNull @NotNull RowSet getModifiedPreShift()
      Returns:
      a cached copy of the modified RowSet in pre-shift keyspace

    • forAllModified

      default void forAllModified(BiConsumer<Long,Long> consumer)
      This helper iterates through the modified RowSet and supplies both the pre-shift and post-shift keys per row.
      Parameters:
      consumer - A consumer to feed the modified pre-shift and post-shift key values to

    • added

      @NotNull @NotNull RowSet added()
      Rows added (in post-shift keyspace).

      A validate() update never returns a null RowSet, but the returned RowSet may be empty.

      Note that the TableUpdate object still retains ownership of the returned RowSet object. The caller must not close the returned RowSet. To use the RowSet beyond the scope of a notification, the caller must acquire the update or make a copy of the RowSet.

    • removed

      @NotNull @NotNull RowSet removed()
      Rows removed (in pre-shift keyspace).

      A validate() update never returns a null RowSet, but the returned RowSet may be empty.

      Note that the TableUpdate object still retains ownership of the returned RowSet object. The caller must not close the returned RowSet. To use the RowSet beyond the scope of a notification, the caller must acquire the update or make a copy of the RowSet.

    • modified

      @NotNull @NotNull RowSet modified()
      Rows modified (in post-shift keyspace).

      A validate() update never returns a null RowSet, but the returned RowSet may be empty.

      Note that the TableUpdate object still retains ownership of the returned RowSet object. The caller must not close the returned RowSet. To use the RowSet beyond the scope of a notification, the caller must acquire the update or make a copy of the RowSet.

    • shifted

      @NotNull @NotNull RowSetShiftData shifted()
      Rows that shifted to new row keys.

    • modifiedColumnSet

      @NotNull @NotNull ModifiedColumnSet modifiedColumnSet()
      The set of columns that might have changed for rows in the modified() RowSet.