1 files changed, 258 insertions, 0 deletions
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryMatcher.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryMatcher.java
new file mode 100644
index 00000000..1ae0c96f
--- /dev/null
+++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryMatcher.java
@@ -0,0 +1,258 @@
+/*******************************************************************************
+ * Copyright (c) 2004-2010 Gabor Bergmann 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 java.util.Collection;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Consumer;
+import java.util.stream.Stream;
+/**
+ * Interface for a VIATRA Query matcher associated with a graph pattern.
+ * 
+ * @param <Match>
+ *            the IPatternMatch type representing a single match of this pattern.
+ * @author Bergmann Gábor
+ * @noimplement This interface is not intended to be implemented by clients. Implement BaseMatcher instead.
+ */
+public interface ViatraQueryMatcher<Match extends IPatternMatch> {
+    // REFLECTION
+    /** The pattern that will be matched. */
+    IQuerySpecification<? extends ViatraQueryMatcher<Match>> getSpecification();
+    /** Fully qualified name of the pattern. */
+    String getPatternName();
+    /** Returns the index of the symbolic parameter with the given name. */
+    Integer getPositionOfParameter(String parameterName);
+    /** Returns the array of symbolic parameter names. */
+    List<String> getParameterNames();
+    // ALL MATCHES
+    /**
+     * Returns the set of all pattern matches.
+     * 
+     * @return matches represented as a Match object.
+     */
+    Collection<Match> getAllMatches();
+    /**
+     * Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
+     * 
+     * @param partialMatch
+     *            a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
+     *            a fixed value.
+     * @return matches represented as a Match object.
+     */
+    Collection<Match> getAllMatches(Match partialMatch);
+    
+    /**
+     * Returns a stream of all pattern matches.
+     * <p>
+     * <strong>WARNING</strong> If the result set changes while the stream is evaluated, the set of matches included in
+     * the stream are unspecified. In such cases, either rely on {@link #getAllMatches()} or collect the results of the
+     * stream in end-user code.
+     * 
+     * @return matches represented as a Match object.
+     * @since 2.0
+     */
+    Stream<Match> streamAllMatches();
+    
+    /**
+     * Returns a stream of all matches of the pattern that conform to the given fixed values of some parameters.
+     * <p>
+     * <strong>WARNING</strong> If the result set changes while the stream is evaluated, the set of matches included in
+     * the stream are unspecified. In such cases, either rely on {@link #getAllMatches()} or collect the results of the
+     * stream in end-user code.
+     * 
+     * @param partialMatch
+     *            a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
+     *            a fixed value.
+     * @return matches represented as a Match object.
+     * @since 2.0
+     */
+    Stream<Match> streamAllMatches(Match partialMatch);
+    
+    // variant(s) with input binding as pattern-specific parameters: not declared in interface
+    // SINGLE MATCH
+    /**
+     * Returns an arbitrarily chosen pattern match. Neither determinism nor randomness of selection is guaranteed.
+     * 
+     * @return a match represented as a Match object, or an empty Optional if no match is found.
+     * @since 2.0
+     */
+    Optional<Match> getOneArbitraryMatch();
+    /**
+     * 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.
+     * 
+     * @param partialMatch
+     *            a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
+     *            a fixed value.
+     * @return a match represented as a Match object, or an empty Optional if no match is found.
+     * @since 2.0
+     */
+    Optional<Match> getOneArbitraryMatch(Match partialMatch);
+    // variant(s) with input binding as pattern-specific parameters: not declared in interface
+    // MATCH CHECKING
+    /**
+     * Indicates whether the query has any kind of matches.
+     * 
+     * @return true if there exists a valid match of the pattern.
+     * @since 1.7
+     */
+    boolean hasMatch();
+    
+    /**
+     * Indicates whether the given combination of specified pattern parameters constitute a valid pattern match, under
+     * any possible substitution of the unspecified parameters (if any).
+     * 
+     * @param partialMatch
+     *            a (partial) match of the pattern where each non-null field binds the corresponding pattern parameter
+     *            to a fixed value.
+     * @return true if the input is a valid (partial) match of the pattern.
+     */
+    boolean hasMatch(Match partialMatch);
+    // variant(s) with input binding as pattern-specific parameters: not declared in interface
+    // NUMBER OF MATCHES
+    /**
+     * Returns the number of all pattern matches.
+     * 
+     * @return the number of pattern matches found.
+     */
+    int countMatches();
+    /**
+     * Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
+     * 
+     * @param partialMatch
+     *            a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
+     *            a fixed value.
+     * @return the number of pattern matches found.
+     */
+    int countMatches(Match partialMatch);
+    // variant(s) with input binding as pattern-specific parameters: not declared in interface
+    // FOR EACH MATCH
+    /**
+     * Executes the given processor on each match of the pattern.
+     * 
+     * @param processor
+     *            the action that will process each pattern match.
+     * @since 2.0
+     */
+    void forEachMatch(Consumer<? super Match> processor);
+    /**
+     * Executes the given processor on each match of the pattern that conforms to the given fixed values of some
+     * parameters.
+     * 
+     * @param partialMatch
+     *            array where each non-null element binds the corresponding pattern parameter to a fixed value.
+     * @param processor
+     *            the action that will process each pattern match.
+     * @since 2.0
+     */
+    void forEachMatch(Match partialMatch, Consumer<? super Match> processor);
+    // variant(s) with input binding as pattern-specific parameters: not declared in interface
+    // FOR ONE ARBITRARY MATCH
+    /**
+     * Executes the given processor on an arbitrarily chosen match of the pattern. Neither determinism nor randomness of
+     * selection is guaranteed.
+     * 
+     * @param processor
+     *            the action that will process the selected match.
+     * @return true if the pattern has at least one match, false if the processor was not invoked
+     * @since 2.0
+     */
+    boolean forOneArbitraryMatch(Consumer<? super Match> processor);
+    /**
+     * Executes the given processor on 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.
+     * 
+     * @param partialMatch
+     *            array where each non-null element binds the corresponding pattern parameter to a fixed value.
+     * @param processor
+     *            the action that will process the selected match.
+     * @return true if the pattern has at least one match with the given parameter values, false if the processor was
+     *         not invoked
+     * @since 2.0
+     */
+    boolean forOneArbitraryMatch(Match partialMatch, Consumer<? super Match> processor);
+    // variant(s) with input binding as pattern-specific parameters: not declared in interface
+    
+    /**
+     * Returns an empty, mutable Match for the matcher. 
+     * Fields of the mutable match can be filled to create a partial match, usable as matcher input. 
+     * This can be used to call the matcher with a partial match 
+     *  even if the specific class of the matcher or the match is unknown.
+     * 
+     * @return the empty match
+     */
+    Match newEmptyMatch();
+    /**
+     * Returns a new (partial) Match object for the matcher. 
+     * This can be used e.g. to call the matcher with a partial
+     * match. 
+     * 
+     * <p>The returned match will be immutable. Use {@link #newEmptyMatch()} to obtain a mutable match object.
+     * 
+     * @param parameters
+     *            the fixed value of pattern parameters, or null if not bound.
+     * @return the (partial) match object.
+     */
+    Match newMatch(Object... parameters);
+    /**
+     * Retrieve the set of values that occur in matches for the given parameterName.
+     * 
+     * @param parameterName
+     *            name of the parameter for which values are returned
+     * @return the Set of all values for the given parameter, null if the parameter with the given name does not exists,
+     *         empty set if there are no matches
+     */
+    Set<Object> getAllValues(final String parameterName);
+    /**
+     * Retrieve the set of values that occur in matches for the given parameterName, that conforms to the given fixed
+     * values of some parameters.
+     * 
+     * @param parameterName
+     *            name of the parameter for which values are returned
+     * @param partialMatch
+     *            a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
+     *            a fixed value.
+     * @return the Set of all values for the given parameter, null if the parameter with the given name does not exists
+     *         or if the parameter with the given name is set in partialMatch, empty set if there are no matches
+     */
+    Set<Object> getAllValues(final String parameterName, Match partialMatch);
+    /**
+     * Returns the engine that the matcher uses.
+     * 
+     * @return the engine
+     */
+    ViatraQueryEngine getEngine();
+}
+\ No newline at end of file

diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryMatcher.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryMatcher.java new file mode 100644 index 00000000..1ae0c96f --- /dev/null +++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/api/ViatraQueryMatcher.java
@@ -0,0 +1,258 @@
	1	/*******************************************************************************
	2	* Copyright (c) 2004-2010 Gabor Bergmann and Daniel Varro
	3	* This program and the accompanying materials are made available under the
	4	* terms of the Eclipse Public License v. 2.0 which is available at
	5	* http://www.eclipse.org/legal/epl-v20.html.
	6	*
	7	* SPDX-License-Identifier: EPL-2.0
	8	*******************************************************************************/
	9
	10	package tools.refinery.viatra.runtime.api;
	11
	12	import java.util.Collection;
	13	import java.util.List;
	14	import java.util.Optional;
	15	import java.util.Set;
	16	import java.util.function.Consumer;
	17	import java.util.stream.Stream;
	18
	19	/**
	20	* Interface for a VIATRA Query matcher associated with a graph pattern.
	21	*
	22	* @param <Match>
	23	* the IPatternMatch type representing a single match of this pattern.
	24	* @author Bergmann Gábor
	25	* @noimplement This interface is not intended to be implemented by clients. Implement BaseMatcher instead.
	26	*/
	27	public interface ViatraQueryMatcher<Match extends IPatternMatch> {
	28	// REFLECTION
	29	/** The pattern that will be matched. */
	30	IQuerySpecification<? extends ViatraQueryMatcher<Match>> getSpecification();
	31
	32	/** Fully qualified name of the pattern. */
	33	String getPatternName();
	34
	35	/** Returns the index of the symbolic parameter with the given name. */
	36	Integer getPositionOfParameter(String parameterName);
	37
	38	/** Returns the array of symbolic parameter names. */
	39	List<String> getParameterNames();
	40
	41	// ALL MATCHES
	42	/**
	43	* Returns the set of all pattern matches.
	44	*
	45	* @return matches represented as a Match object.
	46	*/
	47	Collection<Match> getAllMatches();
	48
	49	/**
	50	* Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
	51	*
	52	* @param partialMatch
	53	* a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
	54	* a fixed value.
	55	* @return matches represented as a Match object.
	56	*/
	57	Collection<Match> getAllMatches(Match partialMatch);
	58
	59	/**
	60	* Returns a stream of all pattern matches.
	61	* <p>
	62	* <strong>WARNING</strong> If the result set changes while the stream is evaluated, the set of matches included in
	63	* the stream are unspecified. In such cases, either rely on {@link #getAllMatches()} or collect the results of the
	64	* stream in end-user code.
	65	*
	66	* @return matches represented as a Match object.
	67	* @since 2.0
	68	*/
	69	Stream<Match> streamAllMatches();
	70
	71	/**
	72	* Returns a stream of all matches of the pattern that conform to the given fixed values of some parameters.
	73	* <p>
	74	* <strong>WARNING</strong> If the result set changes while the stream is evaluated, the set of matches included in
	75	* the stream are unspecified. In such cases, either rely on {@link #getAllMatches()} or collect the results of the
	76	* stream in end-user code.
	77	*
	78	* @param partialMatch
	79	* a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
	80	* a fixed value.
	81	* @return matches represented as a Match object.
	82	* @since 2.0
	83	*/
	84	Stream<Match> streamAllMatches(Match partialMatch);
	85
	86	// variant(s) with input binding as pattern-specific parameters: not declared in interface
	87
	88	// SINGLE MATCH
	89	/**
	90	* Returns an arbitrarily chosen pattern match. Neither determinism nor randomness of selection is guaranteed.
	91	*
	92	* @return a match represented as a Match object, or an empty Optional if no match is found.
	93	* @since 2.0
	94	*/
	95	Optional<Match> getOneArbitraryMatch();
	96
	97	/**
	98	* Returns an arbitrarily chosen match of the pattern that conforms to the given fixed values of some parameters.
	99	* Neither determinism nor randomness of selection is guaranteed.
	100	*
	101	* @param partialMatch
	102	* a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
	103	* a fixed value.
	104	* @return a match represented as a Match object, or an empty Optional if no match is found.
	105	* @since 2.0
	106	*/
	107	Optional<Match> getOneArbitraryMatch(Match partialMatch);
	108
	109	// variant(s) with input binding as pattern-specific parameters: not declared in interface
	110
	111	// MATCH CHECKING
	112	/**
	113	* Indicates whether the query has any kind of matches.
	114	*
	115	* @return true if there exists a valid match of the pattern.
	116	* @since 1.7
	117	*/
	118	boolean hasMatch();
	119
	120	/**
	121	* Indicates whether the given combination of specified pattern parameters constitute a valid pattern match, under
	122	* any possible substitution of the unspecified parameters (if any).
	123	*
	124	* @param partialMatch
	125	* a (partial) match of the pattern where each non-null field binds the corresponding pattern parameter
	126	* to a fixed value.
	127	* @return true if the input is a valid (partial) match of the pattern.
	128	*/
	129	boolean hasMatch(Match partialMatch);
	130
	131	// variant(s) with input binding as pattern-specific parameters: not declared in interface
	132
	133	// NUMBER OF MATCHES
	134	/**
	135	* Returns the number of all pattern matches.
	136	*
	137	* @return the number of pattern matches found.
	138	*/
	139	int countMatches();
	140
	141	/**
	142	* Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
	143	*
	144	* @param partialMatch
	145	* a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
	146	* a fixed value.
	147	* @return the number of pattern matches found.
	148	*/
	149	int countMatches(Match partialMatch);
	150
	151	// variant(s) with input binding as pattern-specific parameters: not declared in interface
	152
	153	// FOR EACH MATCH
	154	/**
	155	* Executes the given processor on each match of the pattern.
	156	*
	157	* @param processor
	158	* the action that will process each pattern match.
	159	* @since 2.0
	160	*/
	161	void forEachMatch(Consumer<? super Match> processor);
	162
	163	/**
	164	* Executes the given processor on each match of the pattern that conforms to the given fixed values of some
	165	* parameters.
	166	*
	167	* @param partialMatch
	168	* array where each non-null element binds the corresponding pattern parameter to a fixed value.
	169	* @param processor
	170	* the action that will process each pattern match.
	171	* @since 2.0
	172	*/
	173	void forEachMatch(Match partialMatch, Consumer<? super Match> processor);
	174
	175	// variant(s) with input binding as pattern-specific parameters: not declared in interface
	176
	177	// FOR ONE ARBITRARY MATCH
	178	/**
	179	* Executes the given processor on an arbitrarily chosen match of the pattern. Neither determinism nor randomness of
	180	* selection is guaranteed.
	181	*
	182	* @param processor
	183	* the action that will process the selected match.
	184	* @return true if the pattern has at least one match, false if the processor was not invoked
	185	* @since 2.0
	186	*/
	187	boolean forOneArbitraryMatch(Consumer<? super Match> processor);
	188
	189	/**
	190	* Executes the given processor on an arbitrarily chosen match of the pattern that conforms to the given fixed
	191	* values of some parameters. Neither determinism nor randomness of selection is guaranteed.
	192	*
	193	* @param partialMatch
	194	* array where each non-null element binds the corresponding pattern parameter to a fixed value.
	195	* @param processor
	196	* the action that will process the selected match.
	197	* @return true if the pattern has at least one match with the given parameter values, false if the processor was
	198	* not invoked
	199	* @since 2.0
	200	*/
	201	boolean forOneArbitraryMatch(Match partialMatch, Consumer<? super Match> processor);
	202
	203	// variant(s) with input binding as pattern-specific parameters: not declared in interface
	204
	205	/**
	206	* Returns an empty, mutable Match for the matcher.
	207	* Fields of the mutable match can be filled to create a partial match, usable as matcher input.
	208	* This can be used to call the matcher with a partial match
	209	* even if the specific class of the matcher or the match is unknown.
	210	*
	211	* @return the empty match
	212	*/
	213	Match newEmptyMatch();
	214
	215	/**
	216	* Returns a new (partial) Match object for the matcher.
	217	* This can be used e.g. to call the matcher with a partial
	218	* match.
	219	*
	220	* <p>The returned match will be immutable. Use {@link #newEmptyMatch()} to obtain a mutable match object.
	221	*
	222	* @param parameters
	223	* the fixed value of pattern parameters, or null if not bound.
	224	* @return the (partial) match object.
	225	*/
	226	Match newMatch(Object... parameters);
	227
	228	/**
	229	* Retrieve the set of values that occur in matches for the given parameterName.
	230	*
	231	* @param parameterName
	232	* name of the parameter for which values are returned
	233	* @return the Set of all values for the given parameter, null if the parameter with the given name does not exists,
	234	* empty set if there are no matches
	235	*/
	236	Set<Object> getAllValues(final String parameterName);
	237
	238	/**
	239	* Retrieve the set of values that occur in matches for the given parameterName, that conforms to the given fixed
	240	* values of some parameters.
	241	*
	242	* @param parameterName
	243	* name of the parameter for which values are returned
	244	* @param partialMatch
	245	* a partial match of the pattern where each non-null field binds the corresponding pattern parameter to
	246	* a fixed value.
	247	* @return the Set of all values for the given parameter, null if the parameter with the given name does not exists
	248	* or if the parameter with the given name is set in partialMatch, empty set if there are no matches
	249	*/
	250	Set<Object> getAllValues(final String parameterName, Match partialMatch);
	251
	252	/**
	253	* Returns the engine that the matcher uses.
	254	*
	255	* @return the engine
	256	*/
	257	ViatraQueryEngine getEngine();
	258	} \ No newline at end of file