Merge pull request #39 from kris7t/partial-interpretation

Implement partial interpretation based model generation

1 files changed, 153 insertions, 0 deletions

diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryEngine.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryEngine.java
new file mode 100644
index 00000000..0f402b49
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryEngine.java
@@ -0,0 +1,153 @@
+/*******************************************************************************
+ * Copyright (c) 2004-2010 Gabor Bergmann and Daniel Varro
+ * Copyright (c) 2023 The Refinery Authors <https://refinery.tools>
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-v20.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+package tools.refinery.viatra.runtime.api;
+
+import tools.refinery.viatra.runtime.api.scope.IBaseIndex;
+import tools.refinery.viatra.runtime.api.scope.QueryScope;
+import tools.refinery.viatra.runtime.matchers.ViatraQueryRuntimeException;
+
+import java.util.Set;
+import java.util.function.Supplier;
+import java.util.stream.Collectors;
+
+/**
+ * A Viatra Query (incremental) evaluation engine, attached to a model such as an EMF resource. The engine hosts pattern matchers, and
+ * will listen on model update notifications stemming from the given model in order to maintain live results.
+ *
+ * <p>
+ * By default, ViatraQueryEngines do not need to be separately disposed; they will be garbage collected along with the model.
+ * Advanced users: see {@link AdvancedViatraQueryEngine} if you want fine control over the lifecycle of an engine.
+ *
+ * <p>
+ * Pattern matchers within this engine may be instantiated in the following ways:
+ * <ul>
+ * <li>Recommended: instantiate the specific matcher class generated for the pattern by e.g. MyPatternMatcher.on(engine).
+ * <li>Use {@link #getMatcher(IQuerySpecification)} if the pattern-specific generated matcher API is not available.
+ * <li>Advanced: use the query specification associated with the generated matcher class to achieve the same.
+ * </ul>
+ * Additionally, a group of patterns (see {@link IQueryGroup}) can be initialized together before usage; this may improve
+ * the performance of pattern matcher construction by trying to gather all necessary information from the model in one go.
+ * Note that no such improvement is to be expected if the engine is specifically constructed in wildcard mode,
+ * an option available in some scope implementations
+ * (see {@link EMFScope#EMFScope(Notifier, BaseIndexOptions)} and {@link BaseIndexOptions#withWildcardMode(boolean)}).
+ *
+ *
+ * @author Bergmann Gábor
+ * @noextend This class is not intended to be subclassed by clients.
+ */
+public abstract class ViatraQueryEngine {
+
+
+    /**
+     * Obtain a (managed) {@link ViatraQueryEngine} to evaluate queries over a given scope specified by an {@link QueryScope}.
+     *
+     * <p> For a given matcher scope, the same engine will be returned to any client.
+     * This facilitates the reuse of internal caches of the engine, greatly improving performance.
+     *
+     * <p> The lifecycle of this engine is centrally managed, and will not be disposed as long as the model is retained in memory.
+     * The engine will be garbage collected along with the model.
+     *
+     * <p>
+     * Advanced users: see {@link AdvancedViatraQueryEngine#createUnmanagedEngine(QueryScope)} to obtain a private,
+     * unmanaged engine that is not shared with other clients and allows tight control over its lifecycle.
+     *
+     * @param scope
+     *          the scope of query evaluation; the definition of the set of model elements that this engine is operates on.
+     *          Provide e.g. a {@link EMFScope} for evaluating queries on an EMF model.
+     * @return a (managed) {@link ViatraQueryEngine} instance
+     */
+    public static ViatraQueryEngine on(QueryScope scope) {
+        return ViatraQueryEngineManager.getInstance().getQueryEngine(scope);
+    }
+
+    /**
+     * Obtain a (managed) {@link ViatraQueryEngine} to evaluate queries over a given scope specified by an {@link QueryScope}.
+     *
+     * <p> For a given matcher scope, the same engine will be returned to any client.
+     * This facilitates the reuse of internal caches of the engine, greatly improving performance.
+     *
+     * <p> The lifecycle of this engine is centrally managed, and will not be disposed as long as the model is retained in memory.
+     * The engine will be garbage collected along with the model.
+     *
+     * <p>
+     * Advanced users: see {@link AdvancedViatraQueryEngine#createUnmanagedEngine(QueryScope)} to obtain a private,
+     * unmanaged engine that is not shared with other clients and allows tight control over its lifecycle.
+     *
+     * @param scope
+     *      the scope of query evaluation; the definition of the set of model elements that this engine is operates on.
+     *      Provide e.g. a {@link EMFScope} for evaluating queries on an EMF model.
+     * @return a (managed) {@link ViatraQueryEngine} instance
+     * @since 1.4
+     */
+    public static ViatraQueryEngine on(QueryScope scope, ViatraQueryEngineOptions options) {
+        return ViatraQueryEngineManager.getInstance().getQueryEngine(scope, options);
+    }
+
+    /**
+     * Provides access to the internal base index component of the engine, responsible for keeping track of basic
+     * contents of the model.
+     *
+     * <p>If using an {@link EMFScope},
+     *  consider {@link EMFScope#extractUnderlyingEMFIndex(ViatraQueryEngine)} instead to access EMF-specific details.
+     *
+     * @return the baseIndex the NavigationHelper maintaining the base index
+     * @throws ViatraQueryRuntimeException
+     *             if the base index could not be constructed
+     */
+    public abstract IBaseIndex getBaseIndex();
+
+    /**
+     * Access a pattern matcher based on a {@link IQuerySpecification}.
+     * Multiple calls will return the same matcher.
+     * @param querySpecification a {@link IQuerySpecification} that describes a VIATRA query specification
+     * @return a pattern matcher corresponding to the specification
+     * @throws ViatraQueryRuntimeException if the matcher could not be initialized
+     */
+    public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getMatcher(IQuerySpecification<Matcher> querySpecification);
+
+    /**
+     * Access a pattern matcher for the graph pattern with the given fully qualified name.
+     * Will succeed only if a query specification for this fully qualified name has been generated and registered.
+     * Multiple calls will return the same matcher unless the registered specification changes.
+     *
+     * @param patternFQN the fully qualified name of a VIATRA query specification
+     * @return a pattern matcher corresponding to the specification
+     * @throws ViatraQueryRuntimeException if the matcher could not be initialized
+     */
+    public abstract ViatraQueryMatcher<? extends IPatternMatch> getMatcher(String patternFQN);
+
+    /**
+     * Access an existing pattern matcher based on a {@link IQuerySpecification}.
+     * @param querySpecification a {@link IQuerySpecification} that describes a VIATRA query specification
+     * @return a pattern matcher corresponding to the specification, <code>null</code> if a matcher does not exist yet.
+     */
+    public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getExistingMatcher(IQuerySpecification<Matcher> querySpecification);
+
+
+    /**
+     * Access a copy of available {@link ViatraQueryMatcher} pattern matchers.
+     * @return a copy of the set of currently available pattern matchers registered on this engine instance
+     */
+    public abstract Set<? extends ViatraQueryMatcher<? extends IPatternMatch>> getCurrentMatchers();
+
+    public Set<IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>> getRegisteredQuerySpecifications() {
+        return getCurrentMatchers().stream().map(ViatraQueryMatcher::getSpecification).collect(Collectors.toSet());
+    }
+
+    /**
+     * @return the scope of query evaluation; the definition of the set of model elements that this engine is operates on.
+     */
+    public abstract QueryScope getScope();
+
+        public abstract void flushChanges();
+
+        public abstract <T> T withFlushingChanges(Supplier<T> supplier);
+}