Package org.eclipse.viatra.query.patternlanguage.emf.specification

## Class SpecificationBuilder

- java.lang.Object
- - org.eclipse.viatra.query.patternlanguage.emf.specification.SpecificationBuilder

-     public final class SpecificationBuilder
      extends java.lang.Object

  An instance class to initialize `PBody` instances from `Pattern` definitions. A single instance of this builder is used during construction, that maintains the mapping between `Pattern` and `PQuery` objects, and can be initialized with a pre-defined set of mappings.

  The SpecificationBuilder is stateful: it stores all previously built specifications, allowing further re-use.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SpecificationBuilder()` | Initializes a query builder with no previously known query specifications
    `SpecificationBuilder​(java.util.Collection<? extends IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>> specifications)` | Sets up a query builder with a predefined collection of specifications
    `SpecificationBuilder​(org.eclipse.viatra.query.patternlanguage.emf.specification.internal.NameToSpecificationMap patternMap)` |
    `SpecificationBuilder​(IQuerySpecification<?>... specifications)` | Sets up a query builder with a predefined set of specifications

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `buildAnnotations​(Pattern pattern, InitializablePQuery query)` |
    `java.util.Set<PBody>` | `buildBodies​(Pattern pattern, InitializablePQuery query)` |
    `IQuerySpecification<?>` | `buildErroneousSpecification​(Pattern pattern, java.lang.String errorMessage, boolean storeInMaps)` | Creates an erroneous query specification from a given pattern object with a stream of precalculated issues.
    `IQuerySpecification<?>` | `buildErroneousSpecification​(Pattern pattern, java.util.stream.Stream<org.eclipse.xtext.validation.Issue> issues, boolean storeInMaps)` | Creates an erroneous query specification from a given pattern object with a stream of precalculated issues.
    `protected QueryEvaluationHint` | `buildHints​(Pattern pattern)` | Build a `QueryEvaluationHint` based on the pattern modifiers and annotations.
    `protected IQuerySpecification<?>` | `buildSpecification​(Pattern pattern)` |
    `protected IQuerySpecification<?>` | `buildSpecification​(Pattern pattern, boolean skipPatternValidation, java.util.List<IQuerySpecification<?>> newSpecifications)` |
    `protected IQuerySpecification<?>` | `buildSpecification​(Pattern pattern, java.util.List<IQuerySpecification<?>> newSpecifications)` |
    `void` | `forgetSpecification​(IQuerySpecification<?> specification)` | Forgets a specification in the builder.
    `java.util.Set<IQuerySpecification<?>>` | `forgetSpecificationTransitively​(IQuerySpecification<?> specification)` | Forgets a specification in the builder, and also removes anything that depends on it.
    `void` | `forgetURI​(org.eclipse.emf.common.util.URI uri)` | Removes `IQuerySpecification` objects from the cache that originate from a given URI
    `java.util.Set<PBody>` | `getBodies​(Pattern pattern, PQuery query)` |
    `IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>` | `getOrCreateSpecification​(Pattern pattern)` | Creates a new or returns an existing query specification for the pattern.
    `IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>` | `getOrCreateSpecification​(Pattern pattern, boolean skipPatternValidation)` | Creates a new or returns an existing query specification for the pattern.
    `IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>` | `getOrCreateSpecification​(Pattern pattern, java.util.List<IQuerySpecification<?>> createdPatternList, boolean skipPatternValidation)` |
    `java.util.Optional<IQuerySpecification<?>>` | `getSpecification​(java.lang.String fqn)` |
    `java.util.Optional<IQuerySpecification<?>>` | `getSpecification​(Pattern pattern)` |
    `boolean` | `hasSpecification​(java.lang.String fqn)` | Returns whether the builder knows a specification with the selected name
    `boolean` | `hasSpecification​(Pattern pattern)` | Returns whether the builder knows a specification with the selected name

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

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

- - ### Constructor Detail

    - #### SpecificationBuilder

          public SpecificationBuilder()

      Initializes a query builder with no previously known query specifications

    - #### SpecificationBuilder

          public SpecificationBuilder​(IQuerySpecification<?>... specifications)

      Sets up a query builder with a predefined set of specifications

    - #### SpecificationBuilder

          public SpecificationBuilder​(java.util.Collection<? extends IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>> specifications)

      Sets up a query builder with a predefined collection of specifications

    - #### SpecificationBuilder

          public SpecificationBuilder​(org.eclipse.viatra.query.patternlanguage.emf.specification.internal.NameToSpecificationMap patternMap)

  - ### Method Detail

    - #### getOrCreateSpecification

          public IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>> getOrCreateSpecification​(Pattern pattern)

      Creates a new or returns an existing query specification for the pattern. It is expected, that the builder will not be called with different patterns having the same fqn over its entire lifecycle.
      Parameters:
        `pattern` -
      Throws:
        `ViatraQueryRuntimeException`
      Since:
        2.0

    - #### getOrCreateSpecification

          public IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>> getOrCreateSpecification​(Pattern pattern,
                                                                                                                     boolean skipPatternValidation)

      Creates a new or returns an existing query specification for the pattern. It is expected, that the builder will not be called with different patterns having the same fqn over its entire lifecycle.
      Parameters:
        `pattern` -
        `skipPatternValidation` - if set to true, detailed pattern validation is skipped - true for model inferrer; not recommended for generic API
      Throws:
        `ViatraQueryRuntimeException`
      Since:
        2.0

    - #### getOrCreateSpecification

          public IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>> getOrCreateSpecification​(Pattern pattern,
                                                                                                                     java.util.List<IQuerySpecification<?>> createdPatternList,
                                                                                                                     boolean skipPatternValidation)

      Since:
        2.0

    - #### buildSpecification

          protected IQuerySpecification<?> buildSpecification​(Pattern pattern)

    - #### buildSpecification

          protected IQuerySpecification<?> buildSpecification​(Pattern pattern,
                                                              java.util.List<IQuerySpecification<?>> newSpecifications)

    - #### buildSpecification

          protected IQuerySpecification<?> buildSpecification​(Pattern pattern,
                                                              boolean skipPatternValidation,
                                                              java.util.List<IQuerySpecification<?>> newSpecifications)

    - #### buildErroneousSpecification

          public IQuerySpecification<?> buildErroneousSpecification​(Pattern pattern,
                                                                    java.lang.String errorMessage,
                                                                    boolean storeInMaps)

      Creates an erroneous query specification from a given pattern object with a stream of precalculated issues. The resulting query specification may or may not be stored for future reference in this specification.
      Parameters:
        `pattern` - the pattern definition to start from
        `errorMessage` - an error message to fill the erroneous specification
        `storeInMaps` - if true, all future references for this query, including references by fqn; if a query is already stored with this name, an `IllegalStateException` is thrown.
      Since:
        2.0

    - #### buildErroneousSpecification

          public IQuerySpecification<?> buildErroneousSpecification​(Pattern pattern,
                                                                    java.util.stream.Stream<org.eclipse.xtext.validation.Issue> issues,
                                                                    boolean storeInMaps)

      Creates an erroneous query specification from a given pattern object with a stream of precalculated issues. The resulting query specification may or may not be stored for future reference in this specification.
      Parameters:
        `pattern` - the pattern definition to start from
        `issues` - a stream of issues that are to be stored in the created specification
        `storeInMaps` - if true, all future references for this query, including references by fqn; if a query is already stored with this name, an `IllegalStateException` is thrown.
      Since:
        2.0

    - #### buildAnnotations

          protected void buildAnnotations​(Pattern pattern,
                                          InitializablePQuery query)

    - #### buildBodies

          public java.util.Set<PBody> buildBodies​(Pattern pattern,
                                                  InitializablePQuery query)

      Throws:
        `ViatraQueryRuntimeException`
      Since:
        2.0

    - #### getBodies

          public java.util.Set<PBody> getBodies​(Pattern pattern,
                                                PQuery query)

      Throws:
        `ViatraQueryRuntimeException`
      Since:
        2.0

    - #### hasSpecification

          public boolean hasSpecification​(Pattern pattern)

      Returns whether the builder knows a specification with the selected name
      Since:
        2.0

    - #### hasSpecification

          public boolean hasSpecification​(java.lang.String fqn)

      Returns whether the builder knows a specification with the selected name
      Since:
        2.0

    - #### getSpecification

          public java.util.Optional<IQuerySpecification<?>> getSpecification​(Pattern pattern)

      Since:
        2.0

    - #### getSpecification

          public java.util.Optional<IQuerySpecification<?>> getSpecification​(java.lang.String fqn)

      Since:
        2.0

    - #### forgetSpecification

          public void forgetSpecification​(IQuerySpecification<?> specification)

      Forgets a specification in the builder.

      Warning! Removing a specification does not change any specification created previously, even if they are referring to the old version of the specification. Only use this if you are sure all dependant queries are also removed, otherwise use `forgetSpecificationTransitively(IQuerySpecification)` instead.

    - #### forgetURI

          public void forgetURI​(org.eclipse.emf.common.util.URI uri)

      Removes `IQuerySpecification` objects from the cache that originate from a given URI
      Since:
        2.1

    - #### forgetSpecificationTransitively

          public java.util.Set<IQuerySpecification<?>> forgetSpecificationTransitively​(IQuerySpecification<?> specification)

      Forgets a specification in the builder, and also removes anything that depends on it.
      Parameters:
        `specification` -

    - #### buildHints

          protected QueryEvaluationHint buildHints​(Pattern pattern)

      Build a `QueryEvaluationHint` based on the pattern modifiers and annotations.
      Since:
        1.5