org.eclipse.viatra.query.runtime.localsearch.matcher.integration

## Class AbstractLocalSearchResultProvider

- java.lang.Object
- - org.eclipse.viatra.query.runtime.localsearch.matcher.integration.AbstractLocalSearchResultProvider

- All Implemented Interfaces:
    IQueryResultProvider
  Direct Known Subclasses:
    GenericLocalSearchResultProvider, LocalSearchResultProvider

      public abstract class AbstractLocalSearchResultProvider
      extends java.lang.Object
      implements IQueryResultProvider

  Since:
    1.7

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected LocalSearchBackend` | `backend`
    `protected IQueryBackendContext` | `backendContext`
    `protected java.util.Map<PQuery,LocalSearchHints>` | `hintCache`
    `protected IPlanProvider` | `planProvider`
    `protected PQuery` | `query`
    `protected ResultProviderRequestor` | `resultProviderRequestor`
    `protected IQueryRuntimeContext` | `runtimeContext`
    `protected ISearchContext` | `searchContext`
    `protected QueryEvaluationHint` | `userHints`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractLocalSearchResultProvider(LocalSearchBackend backend, IQueryBackendContext context, PQuery query, IPlanProvider planProvider, QueryEvaluationHint userHints)`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete 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 parameters)` Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
    `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.
    `double` | `estimateCost(TupleMask inputBindingMask)`
    `void` | `forgetAllPlans()` Forgets all stored plans in this result provider.
    `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.
    `IMatcherCapability` | `getCapabilites()`
    `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.
    `protected abstract IOperationCompiler` | `getOperationCompiler(IQueryBackendContext backendContext, LocalSearchHints configuration)`
    `IQueryBackend` | `getQueryBackend()` The underlying query evaluator backend.
    `IPlanDescriptor` | `getSearchPlan(java.util.Set<PParameter> adornment)` Returns a search plan for a given adornment if exists
    `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 parameters)` Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
    `protected void` | `indexInitializationBeforePlanning()` This method is called before planning start to allow indexing.
    `protected void` | `indexReferredTypesOfQuery(PQuery query, IndexingService requiredIndexingServices)` Collects and indexes all types _directly_ referred by the PQuery `query`.
    `LocalSearchMatcher` | `newLocalSearchMatcher(ITuple parameters)`
    `LocalSearchMatcher` | `newLocalSearchMatcher(java.lang.Object[] parameters)`
    `void` | `prepare()` Prepare this result provider.
    `protected void` | `prepareDirectDependencies()`
    `protected void` | `preparePlansForExpectedAdornments()`
    `void` | `removeUpdateListener(java.lang.Object listenerTag)` Removes an existing listener previously registered with the given tag.

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

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

- - ### Field Detail

    - #### backend

          protected final LocalSearchBackend backend

    - #### backendContext

          protected final IQueryBackendContext backendContext

    - #### runtimeContext

          protected final IQueryRuntimeContext runtimeContext

    - #### query

          protected final PQuery query

    - #### userHints

          protected final QueryEvaluationHint userHints

    - #### hintCache

          protected final java.util.Map<PQuery,LocalSearchHints> hintCache

    - #### planProvider

          protected final IPlanProvider planProvider

    - #### searchContext

          protected final ISearchContext searchContext

    - #### resultProviderRequestor

          protected ResultProviderRequestor resultProviderRequestor

      Since:
        2.1

  - ### Constructor Detail

    - #### AbstractLocalSearchResultProvider

          public AbstractLocalSearchResultProvider(LocalSearchBackend backend,
                                                   IQueryBackendContext context,
                                                   PQuery query,
                                                   IPlanProvider planProvider,
                                                   QueryEvaluationHint userHints)

      Since:
        1.5

  - ### Method Detail

    - #### getOperationCompiler

          protected abstract IOperationCompiler getOperationCompiler(IQueryBackendContext backendContext,
                                                                     LocalSearchHints configuration)

    - #### prepare

          public void prepare()

      Prepare this result provider. This phase is separated from the constructor to allow the backend to cache its instance before requesting preparation for its dependencies.
      Since:
        1.5

    - #### preparePlansForExpectedAdornments

          protected void preparePlansForExpectedAdornments()

    - #### prepareDirectDependencies

          protected void prepareDirectDependencies()

    - #### indexInitializationBeforePlanning

          protected void indexInitializationBeforePlanning()

      This method is called before planning start to allow indexing. It is important to note that this method is called inside a coalesceTraversals block, meaning (1) it is safe to add multiple registration requests as necessary, but (2) no value or statistics is available from the index.
      Throws:
        `ViatraQueryRuntimeException`

    - #### indexReferredTypesOfQuery

          protected void indexReferredTypesOfQuery(PQuery query,
                                                   IndexingService requiredIndexingServices)

      Collects and indexes all types _directly_ referred by the PQuery `query`. Types indirect
      Parameters:
        `requiredIndexingServices` -

    - #### newLocalSearchMatcher

          public LocalSearchMatcher newLocalSearchMatcher(ITuple parameters)

      Throws:
        `ViatraQueryRuntimeException`

    - #### newLocalSearchMatcher

          public LocalSearchMatcher newLocalSearchMatcher(java.lang.Object[] parameters)

      Throws:
        `ViatraQueryRuntimeException`

    - #### hasMatch

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

      Description copied from interface: `IQueryResultProvider`
      Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
      Specified by:
        `hasMatch` in interface `IQueryResultProvider`
      Parameters:
        `parameters` - array where each non-null element binds the corresponding pattern parameter to a fixed value.

    - #### hasMatch

          public boolean hasMatch(TupleMask parameterSeedMask,
                                  ITuple parameters)

      Description copied from interface: `IQueryResultProvider`
      Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
      Specified by:
        `hasMatch` in interface `IQueryResultProvider`
      Parameters:
        `parameterSeedMask` - a mask that extracts those parameters of the query (from the entire parameter list) that should be bound to a fixed value

    - #### getOneArbitraryMatch

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

      Description copied from interface: `IQueryResultProvider`
      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.
      Specified by:
        `getOneArbitraryMatch` in interface `IQueryResultProvider`
      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.

    - #### getOneArbitraryMatch

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

      Description copied from interface: `IQueryResultProvider`
      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.
      Specified by:
        `getOneArbitraryMatch` in interface `IQueryResultProvider`
      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.

    - #### countMatches

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

      Description copied from interface: `IQueryResultProvider`
      Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
      Specified by:
        `countMatches` in interface `IQueryResultProvider`
      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

          public int countMatches(TupleMask parameterSeedMask,
                                  ITuple parameters)

      Description copied from interface: `IQueryResultProvider`
      Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
      Specified by:
        `countMatches` in interface `IQueryResultProvider`
      Parameters:
        `parameterSeedMask` - a mask that extracts those parameters of the query (from the entire parameter list) that should be bound to a fixed value
      Returns:
        the number of pattern matches found.

    - #### estimateCardinality

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

      Description copied from interface: `IQueryResultProvider`
      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.

      Specified by:
        `estimateCardinality` in interface `IQueryResultProvider`
      Returns:
        if available, an estimate of the cardinality of the projection of the match set, with the desired accuracy.

    - #### estimateAverageBucketSize

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

      Description copied from interface: `IQueryResultProvider`
      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.

      Specified by:
        `estimateAverageBucketSize` in interface `IQueryResultProvider`
      Returns:
        if available, an estimate of the average size of each projection group of the match set, with the desired accuracy.

    - #### estimateCost

          public double estimateCost(TupleMask inputBindingMask)

      Since:
        2.1
      No Reference:
        This method is not intended to be referenced by clients.

    - #### getAllMatches

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

      Description copied from interface: `IQueryResultProvider`
      Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
      Specified by:
        `getAllMatches` in interface `IQueryResultProvider`
      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.

    - #### getAllMatches

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

      Description copied from interface: `IQueryResultProvider`
      Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
      Specified by:
        `getAllMatches` in interface `IQueryResultProvider`
      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.

    - #### getQueryBackend

          public IQueryBackend getQueryBackend()

      Description copied from interface: `IQueryResultProvider`
      The underlying query evaluator backend.
      Specified by:
        `getQueryBackend` in interface `IQueryResultProvider`

    - #### addUpdateListener

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

      Description copied from interface: `IQueryResultProvider`
      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 `IQueryResultProvider.removeUpdateListener(Object)` with the same tag.

      Specified by:
        `addUpdateListener` in interface `IQueryResultProvider`
      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 `IQueryResultProvider.removeUpdateListener(Object)`.
        `fireNow` - if true, the insertion update allback will be immediately invoked on all current matches as a one-time effect.

    - #### removeUpdateListener

          public void removeUpdateListener(java.lang.Object listenerTag)

      Description copied from interface: `IQueryResultProvider`
      Removes an existing listener previously registered with the given tag.
      Specified by:
        `removeUpdateListener` in interface `IQueryResultProvider`

    - #### getCapabilites

          public IMatcherCapability getCapabilites()

      Since:
        1.4

    - #### forgetAllPlans

          public void forgetAllPlans()

      Forgets all stored plans in this result provider. If no plans are stored, nothing happens.
      Since:
        2.0
      No Reference:
        This method is not intended to be referenced by clients; it should only used by `LocalSearchBackend`.

    - #### getSearchPlan

          public IPlanDescriptor getSearchPlan(java.util.Set<PParameter> adornment)

      Returns a search plan for a given adornment if exists
      Returns:
        a search plan for the pattern with the given adornment, or null if none exists
      Since:
        2.0
      No Reference:
        This method is not intended to be referenced by clients; it should only used by `LocalSearchBackend`.