6 files changed, 251 insertions, 0 deletions

diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IBaseIndex.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IBaseIndex.java
new file mode 100644
index 00000000..1795a8ef
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IBaseIndex.java
@@ -0,0 +1,91 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2014, 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.scope;
+
+import java.lang.reflect.InvocationTargetException;
+import java.util.concurrent.Callable;
+
+/**
+ * Represents the index maintained on the model.
+ * @author Bergmann Gabor
+ * @since 0.9
+ * 
+ */
+public interface IBaseIndex {
+    // TODO lightweightObserver?
+    // TODO ViatraBaseIndexChangeListener?
+    
+    /**
+     * The given callback will be executed, and all model traversals and index registrations will be delayed until the
+     * execution is done. If there are any outstanding feature, class or datatype registrations, a single coalesced model
+     * traversal will initialize the caches and deliver the notifications.
+     * 
+     * @param callable
+     */
+    public <V> V coalesceTraversals(Callable<V> callable) throws InvocationTargetException;
+    
+    /**
+     * Adds a coarse-grained listener that will be invoked after the NavigationHelper index or the underlying model is changed. Can be used
+     * e.g. to check model contents. Not intended for general use.
+     * 
+     * <p/> See {@link #removeBaseIndexChangeListener(ViatraBaseIndexChangeListener)}
+     * @param listener
+     */
+    public void addBaseIndexChangeListener(ViatraBaseIndexChangeListener listener);
+    
+    /**
+     * Removes a registered listener.
+     * 
+     * <p/> See {@link #addBaseIndexChangeListener(ViatraBaseIndexChangeListener)}
+     * 
+     * @param listener
+     */
+    public void removeBaseIndexChangeListener(ViatraBaseIndexChangeListener listener);
+    
+    /**
+     * Updates the value of indexed derived features that are not well-behaving.
+     */
+    void resampleDerivedFeatures();
+
+    /**
+     * Adds a listener for internal errors in the index. A listener can only be added once.
+     * @param listener
+     * @returns true if the listener was not already added
+     * @since 0.8.0
+     */
+    boolean addIndexingErrorListener(IIndexingErrorListener listener);
+    /**
+     * Removes a listener for internal errors in the index
+     * @param listener
+     * @returns true if the listener was successfully removed (e.g. it did exist)
+     * @since 0.8.0
+     */
+    boolean removeIndexingErrorListener(IIndexingErrorListener listener);
+
+    /**
+     * Register a lightweight observer that is notified if any edge starting at the given Object changes.
+     * 
+     * @param observer the listener instance
+     * @param observedObject the observed instance object
+     * @return false if no observer can be registered for the given instance (e.g. it is a primitive), 
+     *  or observer was already registered (call has no effect)
+     */
+    public boolean addInstanceObserver(IInstanceObserver observer, Object observedObject);
+    
+    /**
+     * Unregisters a lightweight observer for the given Object.
+     * 
+     * @param observer the listener instance
+     * @param observedObject the observed instance object
+     * @return false if no observer can be registered for the given instance (e.g. it is a primitive), 
+     *  or no observer was registered previously (call has no effect)
+     */
+    public boolean removeInstanceObserver(IInstanceObserver observer, Object observedObject);
+
+}
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IEngineContext.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IEngineContext.java
new file mode 100644
index 00000000..55060853
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IEngineContext.java
@@ -0,0 +1,49 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2014, 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.scope;
+
+import tools.refinery.viatra.runtime.matchers.ViatraQueryRuntimeException;
+import tools.refinery.viatra.runtime.matchers.context.IQueryRuntimeContext;
+
+/**
+ * The context of the engine is instantiated by the scope, 
+ * and provides information and services regarding the model the towards the engine.  
+ * 
+ * @author Bergmann Gabor
+ *
+ */
+public interface IEngineContext {
+    
+    /**
+     * Returns the base index. 
+     * @throws ViatraQueryRuntimeException if the base index cannot be accessed 
+     */ 
+    IBaseIndex getBaseIndex();
+
+    /**
+     * Disposes this context object. Resources in the index may now be freed up.
+     * No more methods should be called after this one.
+     * 
+     * @throws IllegalStateException if there are any active listeners to the underlying index
+     */
+    void dispose();
+
+    /**
+     * Provides instance model information for pattern matching.
+     * 
+     * <p> Implementors note: must be reentrant. 
+     * If called while index loading is already in progress, must return the single runtime context instance that will eventually index the model. 
+     * When the runtime query context is invoked in such a case, incomplete indexes are tolerable, but change notifications must be correctly provided as loading commences. 
+     * 
+     * @return a runtime context for pattern matching
+     * @since 1.2
+     * @throws ViatraQueryRuntimeException if the runtime context cannot be initialized
+     */
+    public IQueryRuntimeContext getQueryRuntimeContext();
+}
\ No newline at end of file
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IIndexingErrorListener.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IIndexingErrorListener.java
new file mode 100644
index 00000000..f61a5edb
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IIndexingErrorListener.java
@@ -0,0 +1,23 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2014, Zoltan Ujhelyi, 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.scope;
+
+/**
+ *
+ * This interface contains callbacks for various internal errors from the {@link NavigationHelper base index}.
+ *
+ * @author Zoltan Ujhelyi
+ * @since 0.9
+ *
+ */
+public interface IIndexingErrorListener {
+
+    void error(String description, Throwable t);
+    void fatal(String description, Throwable t);
+}
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IInstanceObserver.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IInstanceObserver.java
new file mode 100644
index 00000000..8ef29cbe
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/IInstanceObserver.java
@@ -0,0 +1,21 @@
+/*******************************************************************************

+ * Copyright (c) 2010-2014, 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.scope;

+

+

+/**

+ * Listener interface for lightweight observation of changes in edges leaving from given source instance elements.

+ * @author Bergmann Gabor

+ * @since 0.9

+ *

+ */

+public interface IInstanceObserver {

+    void notifyBinaryChanged(Object sourceElement, Object edgeType);

+    void notifyTernaryChanged(Object sourceElement, Object edgeType);

+}

diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/QueryScope.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/QueryScope.java
new file mode 100644
index 00000000..5456b9ea
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/QueryScope.java
@@ -0,0 +1,33 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2014, 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.scope;
+
+import tools.refinery.viatra.runtime.api.IQuerySpecification;
+import tools.refinery.viatra.runtime.api.ViatraQueryEngine;
+import tools.refinery.viatra.runtime.internal.apiimpl.EngineContextFactory;
+
+/**
+ * Defines a scope for a VIATRA Query engine, which determines the set of model elements that query evaluation operates on.
+ * 
+ * @author Bergmann Gabor
+ *
+ */
+public abstract class QueryScope extends EngineContextFactory {
+    
+    /**
+     * Determines whether a query engine initialized on this scope can evaluate queries formulated against the given scope type.
+     * <p> Every query scope class is compatible with a query engine initialized on a scope of the same class or a subclass.
+     * @param queryScopeClass the scope class returned by invoking {@link IQuerySpecification#getPreferredScopeClass()} on a query specification
+     * @return true if an {@link ViatraQueryEngine} initialized on this scope can consume an {@link IQuerySpecification}
+     */
+    public boolean isCompatibleWithQueryScope(Class<? extends QueryScope> queryScopeClass) {
+        return queryScopeClass.isAssignableFrom(this.getClass());
+    }
+
+}
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/ViatraBaseIndexChangeListener.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/ViatraBaseIndexChangeListener.java
new file mode 100644
index 00000000..b746e637
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/scope/ViatraBaseIndexChangeListener.java
@@ -0,0 +1,34 @@
+/*******************************************************************************
+ * Copyright (c) 2010-2013, Abel Hegedus, 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.scope;
+
+/**
+ * Listener interface for change notifications from the VIATRA Base index.
+ * 
+ * @author Abel Hegedus
+ * @since 0.9
+ *
+ */
+public interface ViatraBaseIndexChangeListener {
+
+    /**
+     * NOTE: it is possible that this method is called only ONCE! Consider returning a constant value that is set in the constructor.
+     * 
+     * @return true, if the listener should be notified only after index changes, false if notification is needed after each model change 
+     */
+    public boolean onlyOnIndexChange();
+    
+    /**
+     * Called after a model change is handled by the VIATRA Base index and if <code>indexChanged == onlyOnIndexChange()</code>.
+     *  
+     * @param indexChanged true, if the model change also affected the contents of the base index
+     */
+    public void notifyChanged(boolean indexChanged);
+    
+}