1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
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();
}
|
