org.eclipse.viatra.query.runtime.matchers.scopes

## Class TabularRuntimeContext

- java.lang.Object
- - org.eclipse.viatra.query.runtime.matchers.context.AbstractQueryRuntimeContext
  - - org.eclipse.viatra.query.runtime.matchers.scopes.TabularRuntimeContext

- All Implemented Interfaces:
    IQueryRuntimeContext, ITableContext
  Direct Known Subclasses:
    SimpleRuntimeContext

      public abstract class TabularRuntimeContext
      extends AbstractQueryRuntimeContext
      implements ITableContext

  An abstract runtime context that serves enumerable input key instances from tables.

  Usage: first, instantiate `IIndexTable` tables with this as the 'tableContext' argument. Call `registerIndexTable(IIndexTable)` to register them; this may happen either during a coalesced indexing, or on external initiation. Afterwards, they will be visible to the query backends.

  EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is no guarantee that this API will work or that it will remain the same.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TabularRuntimeContext()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addUpdateListener(IInputKey key, Tuple seed, IQueryRuntimeContextListener listener)` Subscribes for updates in the extensional relation identified by the input key, optionally seeded with the given tuple.
    `boolean` | `containsTuple(IInputKey key, ITuple seed)` Simpler form of `#enumerateTuples(IInputKey, TupleMask, Tuple)` in the case where all values of the tuples are bound by the seed.
    `int` | `countTuples(IInputKey key, TupleMask seedMask, ITuple seed)` Returns the number of tuples in the extensional relation identified by the input key seeded with the given mask and tuple.
    `java.lang.Iterable<Tuple>` | `enumerateTuples(IInputKey key, TupleMask seedMask, ITuple seed)` Returns the tuples in the extensional relation identified by the input key, optionally seeded with the given tuple.
    `java.lang.Iterable<? extends java.lang.Object>` | `enumerateValues(IInputKey key, TupleMask seedMask, ITuple seed)` Simpler form of `#enumerateTuples(IInputKey, TupleMask, Tuple)` in the case where all values of the tuples are bound by the seed except for one.
    `java.util.Optional<java.lang.Long>` | `estimateCardinality(IInputKey key, TupleMask groupMask, Accuracy requiredAccuracy)` Gives an estimate of the number of different groups the tuples of the given relation are projected into by the given mask (e.g.
    `IIndexTable` | `getIndexTable(IInputKey key)` If the table is not registered, `handleUnregisteredTableRequest(IInputKey)` is invoked; it may handle it by raising an error or e.g.
    `protected IIndexTable` | `handleUnregisteredTableRequest(IInputKey key)` Override this to provide on-demand table registration
    `protected abstract boolean` | `isContainedInStatelessKey(IInputKey key, ITuple seed)` Handles non-enumerable input keys that are not backed by a table
    `IIndexTable` | `peekIndexTable(IInputKey key)`
    `void` | `registerIndexTable(IIndexTable table)`
    `void` | `removeUpdateListener(IInputKey key, Tuple seed, IQueryRuntimeContextListener listener)` Unsubscribes from updates in the extensional relation identified by the input key, optionally seeded with the given tuple.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.scopes.tables.ITableContext

      `logError`

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.context.IQueryRuntimeContext

      `coalesceTraversals, ensureIndexed, ensureWildcardIndexing, estimateAverageBucketSize, executeAfterTraversal, getMetaContext, isCoalescing, isIndexed, unwrapElement, unwrapTuple, wrapElement, wrapTuple`

- - ### Constructor Detail

    - #### TabularRuntimeContext

          public TabularRuntimeContext()

  - ### Method Detail

    - #### registerIndexTable

          public void registerIndexTable(IIndexTable table)

    - #### peekIndexTable

          public IIndexTable peekIndexTable(IInputKey key)

      Returns:
        null if the table is not registered

    - #### getIndexTable

          public IIndexTable getIndexTable(IInputKey key)

      If the table is not registered, `handleUnregisteredTableRequest(IInputKey)` is invoked; it may handle it by raising an error or e.g. on-demand index construction

    - #### handleUnregisteredTableRequest

          protected IIndexTable handleUnregisteredTableRequest(IInputKey key)

      Override this to provide on-demand table registration

    - #### countTuples

          public int countTuples(IInputKey key,
                                 TupleMask seedMask,
                                 ITuple seed)

      Description copied from interface: `IQueryRuntimeContext`
      Returns the number of tuples in the extensional relation identified by the input key seeded with the given mask and tuple.
      Specified by:
        `countTuples` in interface `IQueryRuntimeContext`
      Parameters:
        `key` - an input key
        `seedMask` - a mask that extracts those parameters of the input key (from the entire parameter list) that should be bound to a fixed value; must not be null. Note: any given index must occur at most once in seedMask.
        `seed` - the tuple of fixed values restricting the match set to be considered, in the same order as given in parameterSeedMask, so that for each considered match tuple, projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold. Must not be null.
      Returns:
        the number of tuples in the model for the given key and seed

        Precondition: the given key is enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### estimateCardinality

          public java.util.Optional<java.lang.Long> estimateCardinality(IInputKey key,
                                                                        TupleMask groupMask,
                                                                        Accuracy requiredAccuracy)

      Description copied from interface: `IQueryRuntimeContext`
      Gives an estimate of the number of different groups the tuples of the given relation are projected into by the given mask (e.g. for an identity mask, this means the full relation size). The estimate must meet the required accuracy.

      Must accept any input key, even non-enumerables or those not recognized by this runtime context. If there is insufficient information to provide an answer up to the required precision, `Optional.empty()` is returned.

      PRE: `TupleMask.isNonrepeating()` must hold for the group mask.

      Specified by:
        `estimateCardinality` in interface `IQueryRuntimeContext`
      Returns:
        if available, an estimate of the cardinality of the projection of the given extensional relation, with the desired accuracy.

    - #### enumerateTuples

          public java.lang.Iterable<Tuple> enumerateTuples(IInputKey key,
                                                           TupleMask seedMask,
                                                           ITuple seed)

      Description copied from interface: `IQueryRuntimeContext`
      Returns the tuples in the extensional relation identified by the input key, optionally seeded with the given tuple.
      Specified by:
        `enumerateTuples` in interface `IQueryRuntimeContext`
      Parameters:
        `key` - an input key
        `seedMask` - a mask that extracts those parameters of the input key (from the entire parameter list) that should be bound to a fixed value; must not be null. Note: any given index must occur at most once in seedMask.
        `seed` - the tuple of fixed values restricting the match set to be considered, in the same order as given in parameterSeedMask, so that for each considered match tuple, projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold. Must not be null.
      Returns:
        the tuples in the model for the given key and seed

        Precondition: the given key is enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### enumerateValues

          public java.lang.Iterable<? extends java.lang.Object> enumerateValues(IInputKey key,
                                                                                TupleMask seedMask,
                                                                                ITuple seed)

      Description copied from interface: `IQueryRuntimeContext`
      Simpler form of `#enumerateTuples(IInputKey, TupleMask, Tuple)` in the case where all values of the tuples are bound by the seed except for one.

      Selects the tuples in the extensional relation identified by the input key, optionally seeded with the given tuple, and then returns the single value from each tuple which is not bound by the ssed mask.

      Specified by:
        `enumerateValues` in interface `IQueryRuntimeContext`
      Parameters:
        `key` - an input key
        `seedMask` - a mask that extracts those parameters of the input key (from the entire parameter list) that should be bound to a fixed value; must not be null. Note: any given index must occur at most once in seedMask, and seedMask must include all parameters in any arbitrary order except one.
        `seed` - the tuple of fixed values restricting the match set to be considered, in the same order as given in parameterSeedMask, so that for each considered match tuple, projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold. Must not be null.
      Returns:
        the objects in the model for the given key and seed

        Precondition: the given key is enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### containsTuple

          public boolean containsTuple(IInputKey key,
                                       ITuple seed)

      Description copied from interface: `IQueryRuntimeContext`
      Simpler form of `#enumerateTuples(IInputKey, TupleMask, Tuple)` in the case where all values of the tuples are bound by the seed.

      Returns whether the given tuple is in the extensional relation identified by the input key.

      Note: this call works for non-enumerable input keys as well.

      Specified by:
        `containsTuple` in interface `IQueryRuntimeContext`
      Parameters:
        `key` - an input key
        `seed` - the tuple of fixed values restricting the match set to be considered, in the same order as given in parameterSeedMask, so that for each considered match tuple, projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold. Must not be null.
      Returns:
        true iff there is at least a single tuple contained in the relation that corresponds to the seed tuple

    - #### addUpdateListener

          public void addUpdateListener(IInputKey key,
                                        Tuple seed,
                                        IQueryRuntimeContextListener listener)

      Description copied from interface: `IQueryRuntimeContext`
      Subscribes for updates in the extensional relation identified by the input key, optionally seeded with the given tuple.

      This should be called after invoking

      Specified by:
        `addUpdateListener` in interface `IQueryRuntimeContext`
      Parameters:
        `key` - an input key
        `seed` - can be null or a tuple with matching arity; if non-null, only those updates in the model are notified about that match the seed at positions where the seed is non-null.
        `listener` - will be notified of future changes

        Precondition: the given key is enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### removeUpdateListener

          public void removeUpdateListener(IInputKey key,
                                           Tuple seed,
                                           IQueryRuntimeContextListener listener)

      Description copied from interface: `IQueryRuntimeContext`
      Unsubscribes from updates in the extensional relation identified by the input key, optionally seeded with the given tuple.
      Specified by:
        `removeUpdateListener` in interface `IQueryRuntimeContext`
      Parameters:
        `key` - an input key
        `seed` - can be null or a tuple with matching arity; if non-null, only those updates in the model are notified about that match the seed at positions where the seed is non-null.
        `listener` - will no longer be notified of future changes

        Precondition: the given key is enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### isContainedInStatelessKey

          protected abstract boolean isContainedInStatelessKey(IInputKey key,
                                                               ITuple seed)

      Handles non-enumerable input keys that are not backed by a table