1 files changed, 363 insertions, 0 deletions

diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/AdvancedViatraQueryEngine.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/AdvancedViatraQueryEngine.java
new file mode 100644
index 00000000..32a3430d
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/AdvancedViatraQueryEngine.java
@@ -0,0 +1,363 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2013, Bergmann Gabor, Istvan Rath and Daniel Varro
+ * 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.QueryScope;
+import tools.refinery.viatra.runtime.internal.apiimpl.ViatraQueryEngineImpl;
+import tools.refinery.viatra.runtime.matchers.ViatraQueryRuntimeException;
+import tools.refinery.viatra.runtime.matchers.backend.*;
+
+import java.lang.reflect.InvocationTargetException;
+import java.util.concurrent.Callable;
+
+/**
+ * Advanced interface to a VIATRA incremental evaluation engine.
+ *
+ * <p>
+ * You can create a new, private, unmanaged {@link AdvancedViatraQueryEngine} instance using
+ * {@link #createUnmanagedEngine(QueryScope)}. Additionally, you can access the advanced interface on any
+ * {@link ViatraQueryEngine} by {@link AdvancedViatraQueryEngine#from(ViatraQueryEngine)}.
+ *
+ * <p>
+ * While the default interface {@link ViatraQueryEngine}, is suitable for most users, this advanced interface provides more
+ * control over the engine. The most important added functionality is the following:
+ * <ul>
+ * <li>You can have tighter control over the lifecycle of the engine, if you create a private, unmanaged engine
+ * instance. For instance, a (non-managed) engine can be disposed in order to detach from the EMF model and stop
+ * listening on update notifications. The indexes built previously in the engine can then be garbage collected, even if
+ * the model itself is retained. Total lifecycle control is only available for private, unmanaged engines (created using
+ * {@link #createUnmanagedEngine(QueryScope)}); a managed engine (obtained via {@link ViatraQueryEngine#on(QueryScope)}) is
+ * shared among clients and can not be disposed or wiped.
+ * <li>You can add and remove listeners to receive notification when the model or the match sets change.
+ * <li>You can add and remove listeners to receive notification on engine lifecycle events, such as creation of new
+ * matchers. For instance, if you explicitly share a private, unmanaged engine between multiple sites, you should
+ * register a callback using {@link #addLifecycleListener(ViatraQueryEngineLifecycleListener)} to learn when another client
+ * has called the destructive methods {@link #dispose()} or {@link #wipe()}.
+ * </ul>
+ *
+ * @author Bergmann Gabor
+ * @noextend This class is not intended to be subclassed by clients.
+ */
+public abstract class AdvancedViatraQueryEngine extends ViatraQueryEngine {
+
+    /**
+     * Creates a new unmanaged VIATRA Query engine to evaluate queries over a given scope specified by an {@link QueryScope}.
+     *
+     * <p> Repeated invocations will return different instances, so other clients are unable to independently access
+     * and influence the returned engine. Note that unmanaged engines do not benefit from some performance improvements
+     * that stem from sharing incrementally maintained indices and caches between multiple clients using the same managed
+     * engine instance.
+     *
+     * <p>
+     * Client is responsible for the lifecycle of the returned engine, hence the usage of the advanced interface
+     * {@link AdvancedViatraQueryEngine}.
+     *
+     * <p>
+     * The match set of any patterns will be incrementally refreshed upon updates from this scope.
+     *
+     * @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 the advanced interface to a newly created unmanaged engine
+     * @since 0.9
+     */
+    public static AdvancedViatraQueryEngine createUnmanagedEngine(QueryScope scope) {
+        return new ViatraQueryEngineImpl(null, scope);
+    }
+
+    /**
+     * Creates a new unmanaged VIATRA Query engine to evaluate queries over a given scope specified by an {@link QueryScope}.
+     *
+     * <p> Repeated invocations will return different instances, so other clients are unable to independently access
+     * and influence the returned engine. Note that unmanaged engines do not benefit from some performance improvements
+     * that stem from sharing incrementally maintained indices and caches between multiple clients using the same managed
+     * engine instance.
+     *
+     * <p>
+     * Client is responsible for the lifecycle of the returned engine, hence the usage of the advanced interface
+     * {@link AdvancedViatraQueryEngine}.
+     *
+     * <p>
+     * The match set of any patterns will be incrementally refreshed upon updates from this scope.
+     *
+     * @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 the advanced interface to a newly created unmanaged engine
+     * @since 1.4
+     */
+    public static AdvancedViatraQueryEngine createUnmanagedEngine(QueryScope scope, ViatraQueryEngineOptions options) {
+        return new ViatraQueryEngineImpl(null, scope, options);
+    }
+
+    /**
+     * Provides access to a given existing engine through the advanced interface.
+     *
+     * <p>
+     * Caveat: if the referenced engine is managed (i.e. created via {@link ViatraQueryEngine#on(QueryScope)}), the advanced
+     * methods {@link #dispose()} and {@link #wipe()} will not be allowed.
+     *
+     * @param engine
+     *            the engine to access using the advanced interface
+     * @return a reference to the same engine conforming to the advanced interface
+     */
+    public static AdvancedViatraQueryEngine from(ViatraQueryEngine engine) {
+        return (AdvancedViatraQueryEngine) engine;
+    }
+
+    /**
+     * Add an engine lifecycle listener to this engine instance.
+     *
+     * @param listener
+     *            the {@link ViatraQueryEngineLifecycleListener} that should listen to lifecycle events from this engine
+     */
+    public abstract void addLifecycleListener(ViatraQueryEngineLifecycleListener listener);
+
+    /**
+     * Remove an existing lifecycle listener from this engine instance.
+     *
+     * @param listener
+     *            the {@link ViatraQueryEngineLifecycleListener} that should not listen to lifecycle events from this
+     *            engine anymore
+     */
+    public abstract void removeLifecycleListener(ViatraQueryEngineLifecycleListener listener);
+
+    /**
+     * Add an model update event listener to this engine instance (that fires its callbacks according to its
+     * notification level).
+     *
+     * @param listener
+     *            the {@link ViatraQueryModelUpdateListener} that should listen to model update events from this engine.
+     */
+    public abstract void addModelUpdateListener(ViatraQueryModelUpdateListener listener);
+
+    /**
+     * Remove an existing model update event listener to this engine instance.
+     *
+     * @param listener
+     *            the {@link ViatraQueryModelUpdateListener} that should not listen to model update events from this engine
+     *            anymore
+     */
+    public abstract void removeModelUpdateListener(ViatraQueryModelUpdateListener listener);
+
+    /**
+     * Registers low-level callbacks for match appearance and disappearance on this pattern matcher.
+     *
+     * <p>
+     * <b>Caution: </b> 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. Most users should use the
+     * databinding support ({@link org.eclipse.viatra.addon.databinding.runtime.api.ViatraObservables ViatraObservables}) or the event-driven API
+     * ({@link org.eclipse.viatra.transformation.evm.api.EventDrivenVM EventDrivenVM}) instead.
+     *
+     * <p>
+     * Performance note: expected to be much more efficient than polling at {@link #addCallbackAfterUpdates(Runnable)},
+     * but prone to "signal hazards", e.g. spurious match appearances that will disappear immediately afterwards.
+     *
+     * <p>
+     * The callback can be unregistered via {@link #removeCallbackOnMatchUpdate(IMatchUpdateListener)}.
+     *
+     * @param fireNow
+     *            if true, appearCallback will be immediately invoked on all current matches as a one-time effect. See
+     *            also {@link ViatraQueryMatcher#forEachMatch(IMatchProcessor)}.
+     * @param listener
+     *            the listener that will be notified of each new match that appears or disappears, starting from now.
+     * @param matcher
+     *            the {@link ViatraQueryMatcher} for which this listener should be active
+     */
+    public abstract <Match extends IPatternMatch> void addMatchUpdateListener(ViatraQueryMatcher<Match> matcher,
+            IMatchUpdateListener<? super Match> listener, boolean fireNow);
+
+    /**
+     * Remove an existing match update event listener to this engine instance.
+     *
+     * @param matcher
+     *            the {@link ViatraQueryMatcher} for which this listener should not be active anymore
+     * @param listener
+     *            the {@link IMatchUpdateListener} that should not receive the callbacks anymore
+     */
+    public abstract <Match extends IPatternMatch> void removeMatchUpdateListener(ViatraQueryMatcher<Match> matcher,
+            IMatchUpdateListener<? super Match> listener);
+
+
+    /**
+     * Access a pattern matcher based on a {@link IQuerySpecification}, overriding some of the default query evaluation hints.
+     * Multiple calls may return the same matcher depending on the actual evaluation hints.
+     *
+     * <p> It is guaranteed that this method will always return a matcher instance which is functionally compatible
+     *   with the requested functionality (see {@link IMatcherCapability}).
+     *   Otherwise, the query evaluator is free to ignore any hints.
+     *
+     * <p> For stateful query backends (Rete), hints may be effective only the first time a matcher is created.
+     * @param querySpecification a {@link IQuerySpecification} that describes a VIATRA query
+     * @return a pattern matcher corresponding to the specification
+     * @param optionalEvaluationHints additional / overriding options on query evaluation; passing null means default options associated with the query
+     * @throws ViatraQueryRuntimeException if the matcher could not be initialized
+     * @since 0.9
+     */
+    public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getMatcher(
+            IQuerySpecification<Matcher> querySpecification,
+            QueryEvaluationHint optionalEvaluationHints);
+
+    /**
+     * Initializes matchers for a group of patterns as one step (optionally overriding some of the default query evaluation hints).
+     * If some of the pattern matchers are already
+     * constructed in the engine, no task is performed for them.
+     *
+     * <p>
+     * This preparation step has the advantage that it prepares pattern matchers for an arbitrary number of patterns in a
+     * single-pass traversal of the model.
+     * This is typically more efficient than traversing the model each time an individual pattern matcher is initialized on demand.
+     * The performance benefit only manifests itself if the engine is not in wildcard mode.
+     *
+     * @param queryGroup a {@link IQueryGroup} identifying a set of VIATRA queries
+     * @param optionalEvaluationHints additional / overriding options on query evaluation; passing null means default options associated with each query
+     * @throws ViatraQueryRuntimeException
+     *             if there was an error in preparing the engine
+     * @since 0.9
+     */
+    public abstract void prepareGroup(IQueryGroup queryGroup, QueryEvaluationHint optionalEvaluationHints);
+
+    /**
+     * Indicates whether the engine is managed, i.e. the default engine assigned to the given scope root by
+     * {@link ViatraQueryEngine#on(QueryScope)}.
+     *
+     * <p>
+     * If the engine is managed, there may be other clients using it, as all calls to
+     * {@link ViatraQueryEngine#on(QueryScope)} return the same managed engine instance for a given scope root. Therefore the
+     * destructive methods {@link #wipe()} and {@link #dispose()} are not allowed.
+     *
+     * <p>
+     * On the other hand, if the engine is unmanaged (i.e. a private instance created using
+     * {@link #createUnmanagedEngine(QueryScope)}), then {@link #wipe()} and {@link #dispose()} can be called. If you
+     * explicitly share a private, unmanaged engine between multiple sites, register a callback using
+     * {@link #addLifecycleListener(ViatraQueryEngineLifecycleListener)} to learn when another client has called these
+     * destructive methods.
+     *
+     * @return true if the engine is managed, and therefore potentially shared with other clients querying the same EMF
+     *         model
+     */
+    public abstract boolean isManaged();
+
+    /**
+     * Indicates whether the engine is in a tainted, inconsistent state due to some internal errors. If true, results
+     * are no longer reliable; engine should be disposed.
+     *
+     * <p>
+     * The engine is in a tainted state if any of its internal processes report back a fatal error. The
+     * {@link ViatraQueryEngineLifecycleListener} interface provides a callback method for entering the tainted state.
+     *
+     * @return the tainted state
+     */
+    public abstract boolean isTainted();
+
+    /**
+     * Discards any pattern matcher caches and forgets known patterns. The base index built directly on the underlying
+     * EMF model, however, is kept in memory to allow reuse when new pattern matchers are built. Use this method if you
+     * have e.g. new versions of the same patterns, to be matched on the same model.
+     *
+     * <p>
+     * Matcher objects will continue to return stale results. If no references are retained to the matchers, they can
+     * eventually be GC'ed.
+     * <p>
+     * Disallowed if the engine is managed (see {@link #isManaged()}), as there may be other clients using it.
+     * <p>
+     * If you explicitly share a private, unmanaged engine between multiple sites, register a callback using
+     * {@link #addLifecycleListener(ViatraQueryEngineLifecycleListener)} to learn when another client has called this
+     * destructive method.
+     *
+     * @throws UnsupportedOperationException
+     *             if engine is managed
+     */
+    public abstract void wipe();
+
+    /**
+     * Completely disconnects and dismantles the engine. Cannot be reversed.
+     * <p>
+     * Matcher objects will continue to return stale results. If no references are retained to the matchers or the
+     * engine, they can eventually be GC'ed, and they won't block the EMF model from being GC'ed anymore.
+     * <p>
+     * The base indexer (see {@link #getBaseIndex()}) built on the model will be disposed alongside the engine, unless
+     * the user has manually added listeners on the base index that were not removed yet.
+     * <p>
+     * Disallowed if the engine is managed (see {@link #isManaged()}), as there may be other clients using it.
+     * <p>
+     * If you explicitly share a private, unmanaged engine between multiple sites, register a callback using
+     * {@link #addLifecycleListener(ViatraQueryEngineLifecycleListener)} to learn when another client has called this
+     * destructive method.
+     *
+     * @throws UnsupportedOperationException
+     *             if engine is managed
+     */
+    public abstract void dispose();
+
+    /**
+     * Provides access to the selected query backend component of the VIATRA Query engine.
+     * @noreference for internal use only
+     * @throws ViatraQueryRuntimeException
+     */
+    public abstract IQueryBackend getQueryBackend(IQueryBackendFactory iQueryBackendFactory);
+
+    /**
+     * Access an existing pattern matcher based on a {@link IQuerySpecification}, and optional hints override.
+     * @param querySpecification a {@link IQuerySpecification} that describes a VIATRA query specification
+     * @param optionalOverrideHints a {@link QueryEvaluationHint} that may override the pattern hints (can be null)
+     * @return a pattern matcher corresponding to the specification, <code>null</code> if a matcher does not exist yet.
+     * @since 1.4
+     */
+    public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getExistingMatcher(IQuerySpecification<Matcher> querySpecification, QueryEvaluationHint optionalOverrideHints);
+
+    /**
+     * Returns the immutable {@link ViatraQueryEngineOptions} of the engine.
+     *
+     * @return the engine options
+     * @since 1.4
+     */
+    public abstract ViatraQueryEngineOptions getEngineOptions();
+
+    /**
+     * Return the underlying result provider for the given matcher.
+     *
+     * @beta This method may change in future versions
+     * @since 1.4
+     * @noreference This method is considered internal API
+     */
+    public abstract IQueryResultProvider getResultProviderOfMatcher(ViatraQueryMatcher<? extends IPatternMatch> matcher);
+
+    /**
+     * The given callable will be executed, and all update propagation in stateful query backends
+     * will be delayed until the execution is done. Within the callback, these backends will provide stale results.
+     *
+     * <p> It is optional for a {@link IQueryBackend} to support the delaying of update propagation; stateless backends will display up-to-date results.
+     * In this case, the given callable shall be executed, and the update propagation shall happen just like in non-delayed execution.
+     *
+     * <p> Example: in the Rete network, no messages will be propagated until the given callable is executed.
+     * After the execution of the callable, all accumulated messages will be delivered.
+     *
+     * <p> The purpose of this method is that stateful query backends may save work when multiple model modifications are performed within the callback that partially cancel each other out.
+     *
+     * @param callable the callable to be executed
+     * @return the result of the callable
+     * @since 1.6
+     */
+    public abstract <V> V delayUpdatePropagation(Callable<V> callable) throws InvocationTargetException;
+
+    /**
+     * Returns true if the update propagation in this engine is currently delayed, false otherwise.
+     *
+     * @see {@link #delayUpdatePropagation(Callable)}
+     * @since 1.6
+     */
+    public abstract boolean isUpdatePropagationDelayed();
+
+    /**
+     * Returns true if the {@link #dispose()} method was called on this engine previously.
+     * @since 2.0
+     */
+    public abstract boolean isDisposed();
+}