Package com.illumon.iris.db.v2.locations

Interface TableLocation<CLT extends ColumnLocation>

All Superinterfaces:
com.fishlib.base.log.LogOutputAppendable, NamedImplementation, TableLocationKey, TableLocationState
All Known Subinterfaces:
DeephavenFormatTableLocation<CLT>, IWritableLocalTableLocation, ParquetFormatTableLocation<CLT>
All Known Implementing Classes:
AbstractTableLocation, DeferredTableLocation, DeferredTableLocation.DataDriven, DeferredTableLocation.SnapshotDriven, LocalTableLocation, ReadOnlyLocalTableLocation, ReadOnlyParquetTableLocation, WritableLocalTableLocation
public interface TableLocation<CLT extends ColumnLocation>
extends TableLocationKey, TableLocationState

=====================================================================================================================

Building block for Iris DB file-based tables, with helper methods for discovering locations and their sizes.

================================================= INTERFACE =========================================================

A location specifies the column and size data location for a splayed table. The location may be either:
(1) the sole location of a stand-alone splayed table, or
(2) a single location of a nested partitioned table, in which case it belongs to an internal partition and a column partition.

================================================== LAYOUTS ==========================================================

There are exactly two layouts in use for file-based tables:

---------------------------------------------------------------------------------------------------------------------
Splayed: (stand-alone)
---------------------------------------------------------------------------------------------------------------------
Such tables have exactly one location.

The layout looks like:
L0 ROOT (e.g. /db/<namespace type>/<namespace name>/Tables)
L1 <table name>
L2 COLUMN FILES [<column name>.[dat, ovr, bytes, sym, sym.bytes]], SIZE FILE [table.size]

---------------------------------------------------------------------------------------------------------------------
Nested Partitioned:
---------------------------------------------------------------------------------------------------------------------
Such tables are horizontally partitioned at two levels:
- The first ("internal") partitioning divides data into manageable fragments or distinct streams.
- The second ("column") partitioning specifies a String column (named by the table's definition, by convention nearly-always "Date").
The locations in use by such a table are identical to those used by a splayed table, except that they are contained within a column partition, which is in turn contained within an internal partition.

The layout looks like:
L0 ROOT (e.g. /db/<namespace type>/<namespace name>/Partitions)
L1 "Internal" Partitions (e.g. "0", "1", ...)
L2 "Column" Partitions (e.g. "2011-10-13", "2011-10-14", ...)
L3 <table name>
L4 COLUMN FILES [<column name>.[dat, ovr, bytes, sym, sym.bytes]], METADATA FILE [table.size]

================================================== COMMENTS =========================================================

Future work may allow more fields from TableLocationKey or TableLocationState to be accessed as columns.

=====================================================================================================================

  • Method Details

    • visit

      TableLocation<CLT> visit​(long stamp)
      Mark this table location as visited, with the given (time)stamp.
      Parameters:
      stamp - a monotonically increasing value indicating when this location was visited.
      Returns:
      returns itself for chaining

    • getVisit

      long getVisit()
      return the last value set in visit(long)
      Returns:
      the last value set in visit()

    • getTableKey

      @NotNull TableKey getTableKey()
      Returns:
      A TableKey instance for the enclosing table

    • getFormat

      @NotNull TableLocation.Format getFormat()
      Get the format that was used to persist this table location.
      Returns:
      The format for this table location

    • supportsSubscriptions

      boolean supportsSubscriptions()
      Does this location support subscriptions? That is, can this location ever have ticking data?
      Returns:
      True if this location supports subscriptions

    • subscribe

      void subscribe​(@NotNull TableLocation.Listener listener)

      Subscribe to pushed location updates. Subscribing more than once with the same listener without an intervening unsubscribe is an error, and may result in undefined behavior.

      This is a possibly asynchronous operation - listener will receive 1 or more handleUpdate callbacks, followed by 0 or 1 handleException callbacks during invocation and continuing after completion, on a thread determined by the implementation. Don't hold a lock that prevents notification delivery while subscribing!

      This method only guarantees eventually consistent state. To force a state update, use refresh() after subscription completes.

      Parameters:
      listener - A listener

    • unsubscribe

      void unsubscribe​(@NotNull TableLocation.Listener listener)
      Unsubscribe from pushed location updates.
      Parameters:
      listener - The listener to forget about

    • refresh

      void refresh()
      Initialize or refresh state information.

    • getSortedColumns

      @NotNull List<SortPair> getSortedColumns()
      Get an ordered list of columns this location is sorted by.
      Returns:
      a non-null ordered list of SortPairs

    • hasDataIndexFor

      boolean hasDataIndexFor​(@NotNull com.illumon.dataobjects.ColumnDefinition<?>... columns)
      Check if this location has a data index for the specified columns.
      Parameters:
      columns - the set of columns to check for.
      Returns:
      true if the table has a Data Index for the specified columns

    • getDataIndex

      @Nullable Table getDataIndex​(@NotNull com.illumon.dataobjects.ColumnDefinition<?>... columns)
      Get the data index table for the specified set of columns. Note that the order of columns does not matter here.
      Parameters:
      columns - the key columns for the index
      Returns:
      the index table or null if one does not exist.

    • getColumnLocation

      @NotNull CLT getColumnLocation​(@NotNull CharSequence name)
      Parameters:
      name - The column name
      Returns:
      The ColumnLocation for the defined column under this table location

    • getColumnVersion

      int getColumnVersion()
      Get the column version for this location.
      Returns:
      the column version

    • append

      @FinalDefault default com.fishlib.base.log.LogOutput append​(@NotNull com.fishlib.base.log.LogOutput logOutput)
      Specified by:
      append in interface com.fishlib.base.log.LogOutputAppendable
      Specified by:
      append in interface TableLocationKey

    • toStringHelper

      @FinalDefault default String toStringHelper()
      Specified by:
      toStringHelper in interface TableLocationKey

    • toGenericString

      @FinalDefault default String toGenericString()
      Format the table key without implementation specific bits.
      Returns:
      a formatted string

    • toStringDetailed

      @FinalDefault default String toStringDetailed()
      Optional toString path with more implementation detail.
      Returns:
      detailed conversion to string