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

Interface TableLocationProvider

All Superinterfaces:
com.fishlib.base.log.LogOutputAppendable, NamedImplementation, TableKey
All Known Implementing Classes:
AbstractTableLocationProvider, ReadOnlyLocalTableLocationProvider, RemoteTableDataService.TableLocationProviderImpl, SingleTableLocationProvider, TableLocationProvider.Null, WritableLocalTableLocationProvider
public interface TableLocationProvider
extends TableKey
Discovery utility for table locations for a given table.

  • Field Details

  • Method Details

    • getNextMark

      static long getNextMark()

    • mark

      void mark​(long mark)
      Indicate the start of a sweep of locations. This will be used to detect locations that have been removed from downstream.
      Parameters:
      mark - the value to set

    • removeUnvisited

      boolean removeUnvisited​(long mark)
      Removes any locations that were not visited after the given mark time.
      Parameters:
      mark - any locations last visited before this mark will be removed.
      Returns:
      true if any locations were removed.

    • supportsSubscriptions

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

    • subscribe

      void subscribe​(@NotNull TableLocationProvider.Listener listener)

      Subscribe to pushed location additions. 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 0 or more handleTableLocation callbacks, followed by 0 or 1 handleException callbacks during invocation and continuing after completion, on a thread determined by the implementation. As noted in BasicTableDataListener.handleException(TableDataException), an exception callback signifies that the subscription is no longer valid, and no unsubscribe is required in that case. Callers must not hold any lock that prevents notification delivery while subscribing. Callers must guard against duplicate notifications.

      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 TableLocationProvider.Listener listener)
      Unsubscribe from pushed location additions.
      Parameters:
      listener - The listener to forget about.

    • refresh

      void refresh()
      Initialize or refresh state information about the list of existing locations.

    • refreshAndRescan

      default void refreshAndRescan​(@NotNull Consumer<TableLocationKey> locationKeyObserver)
      Initialize or refresh state information about the list of existing locations. If applicable, perform extra work to ensure any cached information is up to date.
      Parameters:
      locationKeyObserver - call this TableLocationKey consumer with each location encountered (instead of the default)

    • refreshAndRescan

      default void refreshAndRescan()
      Initialize or refresh state information about the list of existing locations. If applicable, perform extra work to ensure any cached information is up to date.

    • ensureInitialized

      TableLocationProvider ensureInitialized()
      Ensure that this location provider is initialized. Mainly useful in cases where it cannot be otherwise guaranteed that refresh() or subscribe(Listener) has been called prior to calls to the various table location fetch methods.
      Returns:
      this, to allow method chaining

    • getTableLocations

      @NotNull Collection<TableLocation> getTableLocations()
      Get this provider's currently available locations. Locations returned may have null size - that is, they may not "exist" for application purposes.
      Returns:
      A collection of locations available from this provider

    • getTableLocation

      @NotNull default TableLocation getTableLocation​(@NotNull String internalPartition, @NotNull String columnPartition)
      Parameters:
      internalPartition - The internal partition
      columnPartition - The column partition
      Returns:
      The TableLocation matching the given partition names

    • getTableLocation

      @NotNull default TableLocation getTableLocation​(@NotNull TableLocationKey tableLocationKey)
      Parameters:
      tableLocationKey - A key specifying the location to get
      Returns:
      The TableLocation matching the given key

    • getTableLocationIfPresent

      @Nullable TableLocation getTableLocationIfPresent​(@NotNull TableLocationKey tableLocationKey)
      Parameters:
      tableLocationKey - A key specifying the location to get
      Returns:
      The TableLocation matching the given key if present, else null

    • getName

      default String getName()
      allow TableLocationProvider instances to have names.

    • removeTableLocationKey

      void removeTableLocationKey​(@NotNull TableLocationKey locationKey)
      Remove the given table location from the tableLocations map. Use with caution: the intent is that when a TableLocationProvider is told that a location is gone, we should quit providing it in the list of locations, and quit asking downstream providers how big it is.
      Parameters:
      locationKey - the TableLocation to remove