org.eclipse.viatra.query.runtime.matchers.backend

## Interface IQueryResultProvider

- All Known Implementing Classes:
    AbstractLocalSearchResultProvider, GenericLocalSearchResultProvider, LocalSearchResultProvider, RetePatternMatcher

      public interface IQueryResultProvider

  An internal interface of the query backend that provides results of a given query.
  No Implement:
    This interface is not intended to be implemented by clients.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addUpdateListener(IUpdateable listener, java.lang.Object listenerTag, boolean fireNow)` Internal method that registers low-level callbacks for match appearance and disappearance.
    `int` | `countMatches(java.lang.Object[] parameters)` Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
    `int` | `countMatches(TupleMask parameterSeedMask, ITuple projectedParameterSeed)` Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
    `default java.util.Optional<java.lang.Double>` | `estimateAverageBucketSize(TupleMask groupMask, Accuracy requiredAccuracy)` Gives an estimate of the average size of different groups the matches are projected into by the given mask (e.g.
    `java.util.Optional<java.lang.Long>` | `estimateCardinality(TupleMask groupMask, Accuracy requiredAccuracy)` Gives an estimate of the number of different groups the matches are projected into by the given mask (e.g.
    `java.util.stream.Stream<Tuple>` | `getAllMatches(java.lang.Object[] parameters)` Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
    `java.util.stream.Stream<Tuple>` | `getAllMatches(TupleMask parameterSeedMask, ITuple parameters)` Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
    `java.util.Optional<Tuple>` | `getOneArbitraryMatch(java.lang.Object[] parameters)` Returns an arbitrarily chosen match of the pattern that conforms to the given fixed values of some parameters.
    `java.util.Optional<Tuple>` | `getOneArbitraryMatch(TupleMask parameterSeedMask, ITuple parameters)` Returns an arbitrarily chosen match of the pattern that conforms to the given fixed values of some parameters.
    `IQueryBackend` | `getQueryBackend()` The underlying query evaluator backend.
    `boolean` | `hasMatch(java.lang.Object[] parameters)` Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
    `boolean` | `hasMatch(TupleMask parameterSeedMask, ITuple projectedParameterSeed)` Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
    `void` | `removeUpdateListener(java.lang.Object listenerTag)` Removes an existing listener previously registered with the given tag.

- - ### Method Detail

    - #### hasMatch

          boolean hasMatch(java.lang.Object[] parameters)

      Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
      Parameters:
        `parameters` - array where each non-null element binds the corresponding pattern parameter to a fixed value.
      Since:
        2.0

    - #### hasMatch

          boolean hasMatch(TupleMask parameterSeedMask,
                           ITuple projectedParameterSeed)

      Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
      Parameters:
        `parameterSeedMask` - a mask that extracts those parameters of the query (from the entire parameter list) that should be bound to a fixed value
        `parameters` - 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
      Since:
        2.0

    - #### countMatches

          int countMatches(java.lang.Object[] parameters)

      Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
      Parameters:
        `parameters` - array where each non-null element binds the corresponding pattern parameter to a fixed value.
      Returns:
        the number of pattern matches found.

    - #### countMatches

          int countMatches(TupleMask parameterSeedMask,
                           ITuple projectedParameterSeed)

      Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
      Parameters:
        `parameterSeedMask` - a mask that extracts those parameters of the query (from the entire parameter list) that should be bound to a fixed value
        `parameters` - 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
      Returns:
        the number of pattern matches found.
      Since:
        1.7

    - #### estimateCardinality

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

      Gives an estimate of the number of different groups the matches are projected into by the given mask (e.g. for an identity mask, this means the full match set size). The estimate must meet the required accuracy.

      If there is insufficient information to provide an answer up to the required precision, `Optional.empty()` may be returned. In other words, query backends may deny an answer, or do their best to give an estimate without actually determining the match set of the query. However, caching backends are expected to simply return the indexed (projection) size, initialized on-demand if necessary.

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

      Returns:
        if available, an estimate of the cardinality of the projection of the match set, with the desired accuracy.
      Since:
        2.1

    - #### estimateAverageBucketSize

          default java.util.Optional<java.lang.Double> estimateAverageBucketSize(TupleMask groupMask,
                                                                                 Accuracy requiredAccuracy)

      Gives an estimate of the average size of different groups the matches are projected into by the given mask (e.g. for an identity mask, this means 1, while for an empty mask, the result is match set size). The estimate must meet the required accuracy.

      If there is insufficient information to provide an answer up to the required precision, `Optional.empty()` may be returned. In other words, query backends may deny an answer, or do their best to give an estimate without actually determining the match set of the query. However, caching backends are expected to simply return the exact value from the index, initialized on-demand if necessary.

      For an empty match set, zero is acceptable as an exact answer.

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

      Returns:
        if available, an estimate of the average size of each projection group of the match set, with the desired accuracy.
      Since:
        2.1

    - #### getOneArbitraryMatch

          java.util.Optional<Tuple> getOneArbitraryMatch(java.lang.Object[] parameters)

      Returns an arbitrarily chosen match of the pattern that conforms to the given fixed values of some parameters. Neither determinism nor randomness of selection is guaranteed.
      Parameters:
        `parameters` - array where each non-null element binds the corresponding pattern parameter to a fixed value.
      Returns:
        a match represented in the internal `Tuple` representation.
      Since:
        2.0

    - #### getOneArbitraryMatch

          java.util.Optional<Tuple> getOneArbitraryMatch(TupleMask parameterSeedMask,
                                                         ITuple parameters)

      Returns an arbitrarily chosen match of the pattern that conforms to the given fixed values of some parameters. Neither determinism nor randomness of selection is guaranteed.
      Parameters:
        `parameterSeedMask` - a mask that extracts those parameters of the query (from the entire parameter list) that should be bound to a fixed value
        `parameters` - 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
      Returns:
        a match represented in the internal `Tuple` representation.
      Since:
        2.0

    - #### getAllMatches

          java.util.stream.Stream<Tuple> getAllMatches(java.lang.Object[] parameters)

      Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
      Parameters:
        `parameters` - array where each non-null element binds the corresponding pattern parameter to a fixed value.
      Returns:
        matches represented in the internal `Tuple` representation.
      Since:
        2.0

    - #### getAllMatches

          java.util.stream.Stream<Tuple> getAllMatches(TupleMask parameterSeedMask,
                                                       ITuple parameters)

      Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
      Parameters:
        `parameterSeedMask` - a mask that extracts those parameters of the query (from the entire parameter list) that should be bound to a fixed value
        `parameters` - 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
      Returns:
        matches represented in the internal `Tuple` representation.
      Since:
        2.0

    - #### getQueryBackend

          IQueryBackend getQueryBackend()

      The underlying query evaluator backend.

    - #### addUpdateListener

          void addUpdateListener(IUpdateable listener,
                                 java.lang.Object listenerTag,
                                 boolean fireNow)

      Internal method that registers low-level callbacks for match appearance and disappearance.

      Caution: This is a low-level callback that is invoked when the pattern matcher is not necessarily in a consistent state yet. Importantly, no model modification permitted during the callback.

      The callback can be unregistered via invoking `removeUpdateListener(Object)` with the same tag.

      Parameters:
        `listener` - the listener that will be notified of each new match that appears or disappears, starting from now.
        `listenerTag` - a tag by which to identify the listener for later removal by `removeUpdateListener(Object)`.
        `fireNow` - if true, the insertion update allback will be immediately invoked on all current matches as a one-time effect.
      Throws:
        `java.lang.UnsupportedOperationException` - if this is a non-incremental backend (i.e. `IQueryBackend.isCaching()` on `getQueryBackend()` returns false)

    - #### removeUpdateListener

          void removeUpdateListener(java.lang.Object listenerTag)

      Removes an existing listener previously registered with the given tag.
      Throws:
        `java.lang.UnsupportedOperationException` - if this is a non-incremental backend (i.e. `IQueryBackend.isCaching()` on `getQueryBackend()` returns false)