org.eclipse.incquery.runtime.matchers.context

## Interface IQueryRuntimeContext

- All Known Implementing Classes:
    DynamicEMFQueryRuntimeContext, EMFQueryRuntimeContext

      public interface IQueryRuntimeContext

  Provides instance model information (relations corresponding to input keys) to query evaluator backends at runtime.
  Author:
    Bergmann Gabor

- - ### Method Summary

    All Methods Instance Methods Abstract 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.
    `<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.
    `boolean` | `containsTuple(IInputKey key, Tuple seed)` Simpler form of `enumerateTuples(IInputKey, Tuple)` in the case where all values of the tuples are bound by the seed.
    `int` | `countTuples(IInputKey key, Tuple seed)` Returns the number of tuples in the extensional relation identified by the input key, optionally seeded with the given tuple.
    `void` | `ensureIndexed(IInputKey key)` If the given (enumerable) input key is not yet indexed, the model will be traversed (after the end of the outermost coalescing block, see `coalesceTraversals(Callable)`) so that the index can be built.
    `java.lang.Iterable<Tuple>` | `enumerateTuples(IInputKey key, Tuple 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, Tuple seed)` Simpler form of `enumerateTuples(IInputKey, Tuple)` in the case where all values of the tuples are bound by the seed except for one.
    `IQueryMetaContext` | `getMetaContext()` Provides metamodel-specific info independent of the runtime instance model.
    `boolean` | `isCoalescing()`
    `boolean` | `isIndexed(IInputKey key)`
    `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.
    `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

- - ### Method Detail

    - #### getMetaContext

          IQueryMetaContext getMetaContext()

      Provides metamodel-specific info independent of the runtime instance model.

    - #### coalesceTraversals

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

      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 `isCoalescing()`).

      Parameters:
        `callable` -
      Throws:
        `java.lang.reflect.InvocationTargetException`

    - #### isCoalescing

          boolean isCoalescing()

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

    - #### isIndexed

          boolean isIndexed(IInputKey key)

      Returns:
        true iff the given input key is already indexed, and contents are available without costly model traversal.

    - #### ensureIndexed

          void ensureIndexed(IInputKey key)

      If the given (enumerable) input key is not yet indexed, the model will be traversed (after the end of the outermost coalescing block, see `coalesceTraversals(Callable)`) so that the index can be built.

      Postcondition: After invoking this method, `isIndexed(IInputKey)` for the same key will be guaranteed to return true as soon as `isCoalescing()` first returns false.

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

      Throws:
        `java.lang.IllegalArgumentException` - if key is not enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### countTuples

          int countTuples(IInputKey key,
                          Tuple seed)

      Returns the number of tuples in the extensional relation identified by the input key, optionally seeded with the given tuple.
      Parameters:
        `key` - an input key
        `seed` - can be null or a tuple with matching arity; if non-null, only those tuples in the model are counted that match the seed at positions where the seed is non-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)`.

      Throws:
        `java.lang.IllegalArgumentException` - if key is not enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### enumerateTuples

          java.lang.Iterable<Tuple> enumerateTuples(IInputKey key,
                                                    Tuple seed)

      Returns the tuples in the extensional relation identified by the input key, optionally seeded with the given tuple.
      Parameters:
        `key` - an input key
        `seed` - can be null or a tuple with matching arity; if non-null, only those tuples in the model are enumerated that match the seed at positions where the seed is non-null.
      Returns:
        the tuples in the model for the given key and seed

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

      Throws:
        `java.lang.IllegalArgumentException` - if key is not enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### enumerateValues

          java.lang.Iterable<? extends java.lang.Object> enumerateValues(IInputKey key,
                                                                         Tuple seed)

      Simpler form of `enumerateTuples(IInputKey, 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 corresponds to the only null value in the seed.

      Parameters:
        `key` - an input key
        `seed` - can be null (if key is unary) or a tuple with matching arity; if non-null, only those tuples in the model are enumerated that match the seed at positions where the seed is non-null; the seed is null at exactly one position.
      Returns:
        the objects in the model for the given key and seed

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

      Throws:
        `java.lang.IllegalArgumentException` - if key is not enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### containsTuple

          boolean containsTuple(IInputKey key,
                                Tuple seed)

      Simpler form of `enumerateTuples(IInputKey, 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.

      Parameters:
        `key` - an input key
        `seed` - a tuple with matching arity, consisting of non-null elements (null can be used in the 0-ary case).
      Returns:
        true iff the seed tuple is contained in the relation

    - #### addUpdateListener

          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.

      This should be called after invoking

      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)`.

      Throws:
        `java.lang.IllegalArgumentException` - if key is not enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### removeUpdateListener

          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.
      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)`.

      Throws:
        `java.lang.IllegalArgumentException` - if key is not enumerable, see `IQueryMetaContext.isEnumerable(IInputKey)`.

    - #### wrapElement

          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

      model element -> internal object.

      null must be mapped to null.

    - #### unwrapElement

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

      Unwraps the internal representation of the element into its original form

      internal object -> model element

      null must be mapped to null.

    - #### wrapTuple

          Tuple wrapTuple(Tuple externalElements)

      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

          Tuple unwrapTuple(Tuple internalElements)

      Unwraps the tuple of internal representations of elements into their original forms

      internal objects -> model elements

      null must be mapped to null.