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

## Class SimpleRuntimeContext

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

- All Implemented Interfaces:
    IQueryRuntimeContext, ITableContext

      public class SimpleRuntimeContext
      extends TabularRuntimeContext

  A simple demo implementation of the IQRC interface using tables.

  Usage: first, instantiate `IIndexTable` tables with this as the 'tableContext' argument, and call `TabularRuntimeContext.registerIndexTable(IIndexTable)` manually to register them. 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
    `SimpleRuntimeContext(IQueryMetaContext metaContext)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `<V> V` | `coalesceTraversals(java.util.concurrent.Callable<V> callable)` The given callable will be executed, and all model traversals will be delayed until the execution is done.
    `void` | `ensureIndexed(IInputKey key, IndexingService service)` If the given (enumerable) input key is not yet indexed, the model will be traversed (after the end of the outermost coalescing block, see `IQueryRuntimeContext.coalesceTraversals(Callable)`) so that the index can be built.
    `void` | `ensureWildcardIndexing(IndexingService service)` Starts wildcard indexing for the given service.
    `void` | `executeAfterTraversal(java.lang.Runnable runnable)` Execute the given runnable after traversal.
    `IQueryMetaContext` | `getMetaContext()` Provides metamodel-specific info independent of the runtime instance model.
    `boolean` | `isCoalescing()`
    `protected boolean` | `isContainedInStatelessKey(IInputKey key, ITuple seed)` Handles non-enumerable input keys that are not backed by a table
    `boolean` | `isIndexed(IInputKey key, IndexingService service)` Returns true if index is available for the given key providing the given service.
    `void` | `logError(java.lang.String message)` Indicates that an error has occurred in maintaining an index table, e.g.
    `java.lang.Object` | `unwrapElement(java.lang.Object internalElement)` Unwraps the internal representation of the element into its original form
    `Tuple` | `unwrapTuple(Tuple internalElements)` Unwraps the tuple of internal representations of elements into their original forms
    `java.lang.Object` | `wrapElement(java.lang.Object externalElement)` Wraps the external element into the internal representation that is to be used by the query backend
    `Tuple` | `wrapTuple(Tuple externalElements)` Unwraps the tuple of elements into the internal representation that is to be used by the query backend

    - ### Methods inherited from class org.eclipse.viatra.query.runtime.matchers.scopes.TabularRuntimeContext

      `addUpdateListener, containsTuple, countTuples, enumerateTuples, enumerateValues, estimateCardinality, getIndexTable, handleUnregisteredTableRequest, peekIndexTable, registerIndexTable, removeUpdateListener`

    - ### 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.context.IQueryRuntimeContext

      `estimateAverageBucketSize`

- - ### Constructor Detail

    - #### SimpleRuntimeContext

          public SimpleRuntimeContext(IQueryMetaContext metaContext)

  - ### Method Detail

    - #### logError

          public void logError(java.lang.String message)

      Description copied from interface: `ITableContext`
      Indicates that an error has occurred in maintaining an index table, e.g. duplicate value.

    - #### getMetaContext

          public IQueryMetaContext getMetaContext()

      Description copied from interface: `IQueryRuntimeContext`
      Provides metamodel-specific info independent of the runtime instance model.

    - #### coalesceTraversals

          public <V> V coalesceTraversals(java.util.concurrent.Callable<V> callable)
                                   throws java.lang.reflect.InvocationTargetException

      Description copied from interface: `IQueryRuntimeContext`
      The given callable will be executed, and all model traversals will be delayed until the execution is done. If there are any outstanding information to be read from the model, a single coalesced model traversal will initialize the caches and deliver the notifications.

      Calls may be nested. A single coalesced traversal will happen at the end of the outermost call.

      Caution: results returned by the runtime context may be incomplete during the coalescing period, to be corrected by notifications sent during the final coalesced traversal. For example, if a certain input key is not cached yet, an empty relation may be reported during `callable.call()`; the cache will be constructed after the call terminates and notifications will deliver the entire content of the relation. Non-incremental query backends should therefore never enumerate input keys while coalesced (verify using `IQueryRuntimeContext.isCoalescing()`).

      Throws:
        `java.lang.reflect.InvocationTargetException`

    - #### isCoalescing

          public boolean isCoalescing()

      Returns:
        true iff currently within a coalescing section (i.e. within the callable of a call to `IQueryRuntimeContext.coalesceTraversals(Callable)`).

    - #### isIndexed

          public boolean isIndexed(IInputKey key,
                                   IndexingService service)

      Description copied from interface: `IQueryRuntimeContext`
      Returns true if index is available for the given key providing the given service.

    - #### ensureIndexed

          public void ensureIndexed(IInputKey key,
                                    IndexingService service)

      Description copied from interface: `IQueryRuntimeContext`
      If the given (enumerable) input key is not yet indexed, the model will be traversed (after the end of the outermost coalescing block, see `IQueryRuntimeContext.coalesceTraversals(Callable)`) so that the index can be built. It is possible that the base indexer will select a higher indexing level merging multiple indexing requests to an appropriate level.

      Postcondition: After invoking this method, `#getIndexed(IInputKey, IndexingService)` for the same key and service will be guaranteed to return the requested or a highing indexing level as soon as `IQueryRuntimeContext.isCoalescing()` first returns false.

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

    - #### wrapElement

          public java.lang.Object wrapElement(java.lang.Object externalElement)

      Description copied from interface: `IQueryRuntimeContext`
      Wraps the external element into the internal representation that is to be used by the query backend

      model element -> internal object.

      null must be mapped to null.

    - #### unwrapElement

          public java.lang.Object unwrapElement(java.lang.Object internalElement)

      Description copied from interface: `IQueryRuntimeContext`
      Unwraps the internal representation of the element into its original form

      internal object -> model element

      null must be mapped to null.

    - #### wrapTuple

          public Tuple wrapTuple(Tuple externalElements)

      Description copied from interface: `IQueryRuntimeContext`
      Unwraps the tuple of elements into the internal representation that is to be used by the query backend

      model elements -> internal objects

      null must be mapped to null.

    - #### unwrapTuple

          public Tuple unwrapTuple(Tuple internalElements)

      Description copied from interface: `IQueryRuntimeContext`
      Unwraps the tuple of internal representations of elements into their original forms

      internal objects -> model elements

      null must be mapped to null.

    - #### ensureWildcardIndexing

          public void ensureWildcardIndexing(IndexingService service)

      Description copied from interface: `IQueryRuntimeContext`
      Starts wildcard indexing for the given service. After this call, no registration is required for this `IndexingService`. a previously set wildcard level cannot be lowered, only extended.

    - #### executeAfterTraversal

          public void executeAfterTraversal(java.lang.Runnable runnable)
                                     throws java.lang.reflect.InvocationTargetException

      Description copied from interface: `IQueryRuntimeContext`
      Execute the given runnable after traversal. It is guaranteed that the runnable is executed as soon as the indexing is finished. The callback is executed only once, then is removed from the callback queue.
      Throws:
        `java.lang.reflect.InvocationTargetException`

    - #### isContainedInStatelessKey

          protected boolean isContainedInStatelessKey(IInputKey key,
                                                      ITuple seed)

      Description copied from class: `TabularRuntimeContext`
      Handles non-enumerable input keys that are not backed by a table
      Specified by:
        `isContainedInStatelessKey` in class `TabularRuntimeContext`