org.eclipse.viatra.query.runtime.rete.matcher

## Class RetePatternMatcher

- java.lang.Object
- - org.eclipse.viatra.query.runtime.rete.network.BaseNode
  - - org.eclipse.viatra.query.runtime.rete.network.StandardNode
    - - org.eclipse.viatra.query.runtime.rete.single.SingleInputNode
      - - org.eclipse.viatra.query.runtime.rete.single.TransformerNode
        - - org.eclipse.viatra.query.runtime.rete.matcher.RetePatternMatcher

- All Implemented Interfaces:
    IQueryResultProvider, NetworkStructureChangeSensitiveNode, Node, Receiver, Supplier, Tunnel

      public class RetePatternMatcher
      extends TransformerNode
      implements IQueryResultProvider

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `connected`
    `protected IQueryRuntimeContext` | `context`
    `protected ReteEngine` | `engine`
    `protected java.util.Map<java.lang.String,java.lang.Integer>` | `posMapping`
    `protected ProductionNode` | `productionNode`
    `protected RecipeTraceInfo` | `productionNodeTrace`
    `protected java.util.Map<java.lang.Object,Receiver>` | `taggedChildren`

    - ### Fields inherited from class org.eclipse.viatra.query.runtime.rete.single.SingleInputNode

      `mailbox, parent`

    - ### Fields inherited from class org.eclipse.viatra.query.runtime.rete.network.StandardNode

      `childMailboxes, children`

    - ### Fields inherited from class org.eclipse.viatra.query.runtime.rete.network.BaseNode

      `nodeId, reteContainer, tag, traceInfos`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RetePatternMatcher(ReteEngine engine, RecipeTraceInfo productionNodeTrace)`

  - ### Method Summary

    All Methods Instance 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.
    `void` | `connect(Receiver receiver, boolean synchronize)` Connects a new external receiver that will receive update notifications from now on.
    `void` | `connect(Receiver receiver, java.lang.Object tag, boolean synchronize)` Connects a new external receiver that will receive update notifications from now on.
    `int` | `count(java.lang.Object[] inputMapping, boolean[] fixed)` Counts the number of occurrences of the pattern that match inputMapping on positions where fixed is true.
    `int` | `count(TupleMask mask, ITuple inputSignature)` Counts the number of occurrences of the pattern that match inputMapping on positions where fixed is true.
    `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.
    `void` | `disconnect(Receiver receiver)` Disconnects a child node.
    `boolean` | `disconnectByTag(java.lang.Object tag)` Disconnects the child node that was connected by specifying the given tag.
    `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.
    `ProductionNode` | `getProductionNode()`
    `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 parameters)` Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
    `java.util.stream.Stream<Tuple>` | `matchAll(java.lang.Object[] inputMapping, boolean[] fixed)`
    `java.util.stream.Stream<Tuple>` | `matchAll(TupleMask mask, ITuple inputSignature)`
    `java.util.Optional<Tuple>` | `matchOne(java.lang.Object[] inputMapping, boolean[] fixed)`
    `java.util.Optional<Tuple>` | `matchOne(TupleMask mask, ITuple inputSignature)`
    `Tuple` | `matchOneRandomly(java.lang.Object[] inputMapping, boolean[] fixed)`
    `int` | `projectionSize(TupleMask groupMask)` Counts the number of distinct tuples attainable from the match set by projecting match tuples according to the given mask.
    `void` | `removeUpdateListener(java.lang.Object listenerTag)` Removes an existing listener previously registered with the given tag.
    `protected Tuple` | `transform(Tuple input)`

    - ### Methods inherited from class org.eclipse.viatra.query.runtime.rete.single.TransformerNode

      `pullInto, pullIntoWithTimeline, update`

    - ### Methods inherited from class org.eclipse.viatra.query.runtime.rete.single.SingleInputNode

      `appendParent, assignTraceInfo, getCommunicationTracker, getMailbox, getParents, instantiateMailbox, propagatePullInto, propagatePullIntoWithTimestamp, removeParent`

    - ### Methods inherited from class org.eclipse.viatra.query.runtime.rete.network.StandardNode

      `appendChild, constructIndex, getChildMailboxes, getPulledContents, getReceivers, issueError, networkStructureChanged, propagateUpdate, removeChild`

    - ### Methods inherited from class org.eclipse.viatra.query.runtime.rete.network.BaseNode

      `acceptPropagatedTraceInfo, getContainer, getNodeId, getTag, getTraceInfoPatternsEnumerated, getTraceInfos, setTag, toString, toStringCore`

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

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

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.backend.IQueryResultProvider

      `estimateAverageBucketSize`

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.rete.network.Supplier

      `appendChild, constructIndex, getPulledContents, getPulledContents, getReceivers, removeChild`

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.rete.network.Node

      `acceptPropagatedTraceInfo, getContainer, getNodeId, getTag, getTraceInfos, setTag`

- - ### Field Detail

    - #### engine

          protected ReteEngine engine

    - #### context

          protected IQueryRuntimeContext context

    - #### productionNode

          protected ProductionNode productionNode

    - #### productionNodeTrace

          protected RecipeTraceInfo productionNodeTrace

    - #### posMapping

          protected java.util.Map<java.lang.String,java.lang.Integer> posMapping

    - #### taggedChildren

          protected java.util.Map<java.lang.Object,Receiver> taggedChildren

    - #### connected

          protected boolean connected

  - ### Constructor Detail

    - #### RetePatternMatcher

          public RetePatternMatcher(ReteEngine engine,
                                    RecipeTraceInfo productionNodeTrace)

      Parameters:
        `productionNode` - a production node that matches this pattern without any parameter bindings

  - ### Method Detail

    - #### getProductionNode

          public ProductionNode getProductionNode()

      Since:
        1.6

    - #### matchOneRandomly

          public Tuple matchOneRandomly(java.lang.Object[] inputMapping,
                                        boolean[] fixed)

    - #### matchAll

          public java.util.stream.Stream<Tuple> matchAll(java.lang.Object[] inputMapping,
                                                         boolean[] fixed)

      Since:
        2.0

    - #### matchAll

          public java.util.stream.Stream<Tuple> matchAll(TupleMask mask,
                                                         ITuple inputSignature)

      Since:
        2.0

    - #### matchOne

          public java.util.Optional<Tuple> matchOne(java.lang.Object[] inputMapping,
                                                    boolean[] fixed)

      Since:
        2.0

    - #### matchOne

          public java.util.Optional<Tuple> matchOne(TupleMask mask,
                                                    ITuple inputSignature)

      Since:
        2.0

    - #### count

          public int count(java.lang.Object[] inputMapping,
                           boolean[] fixed)

      Counts the number of occurrences of the pattern that match inputMapping on positions where fixed is true.
      Returns:
        the number of occurrences

    - #### count

          public int count(TupleMask mask,
                           ITuple inputSignature)

      Counts the number of occurrences of the pattern that match inputMapping on positions where fixed is true.
      Returns:
        the number of occurrences
      Since:
        1.7

    - #### projectionSize

          public int projectionSize(TupleMask groupMask)

      Counts the number of distinct tuples attainable from the match set by projecting match tuples according to the given mask.
      Returns:
        the size of the projection
      Since:
        2.1

    - #### connect

          public void connect(Receiver receiver,
                              boolean synchronize)

      Connects a new external receiver that will receive update notifications from now on. The receiver will practically connect to the production node, the added value is unwrapping the updates for external use.
      Parameters:
        `synchronize` - if true, the contents of the production node will be inserted into the receiver after the connection is established.

    - #### connect

          public void connect(Receiver receiver,
                              java.lang.Object tag,
                              boolean synchronize)

      Connects a new external receiver that will receive update notifications from now on. The receiver will practically connect to the production node, the added value is unwrapping the updates for external use. The external receiver will be disconnectable later based on its tag.
      Parameters:
        `tag` - an identifier to recognize the child node by.
        `synchronize` - if true, the contents of the production node will be inserted into the receiver after the connection is established.

    - #### disconnect

          public void disconnect(Receiver receiver)

      Disconnects a child node.

    - #### disconnectByTag

          public boolean disconnectByTag(java.lang.Object tag)

      Disconnects the child node that was connected by specifying the given tag.
      Returns:
        if a child node was found registered with this tag.

    - #### transform

          protected Tuple transform(Tuple input)

      Specified by:
        `transform` in class `TransformerNode`

    - #### 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

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

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

    - #### 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`