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
|
/*******************************************************************************
* 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.matchers.backend;
import java.util.Optional;
import java.util.stream.Stream;
import tools.refinery.viatra.runtime.matchers.planning.helpers.StatisticsHelper;
import tools.refinery.viatra.runtime.matchers.tuple.ITuple;
import tools.refinery.viatra.runtime.matchers.tuple.Tuple;
import tools.refinery.viatra.runtime.matchers.tuple.TupleMask;
import tools.refinery.viatra.runtime.matchers.util.Accuracy;
/**
* An internal interface of the query backend that provides results of a given query.
* @author Bergmann Gabor
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IQueryResultProvider {
/**
* Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
*
* @param parameters
* array where each non-null element binds the corresponding pattern parameter to a fixed value.
* @pre size of input array must be equal to the number of parameters.
* @since 2.0
*/
public boolean hasMatch(Object[] parameters);
/**
* Decides whether there are any matches of the pattern that conform to the given fixed values of some parameters.
*
* @param parameterSeedMask
* a mask that extracts those parameters of the query (from the entire parameter list) that should be
* bound to a fixed value
* @param parameters
* the tuple of fixed values restricting the match set to be considered, in the same order as given in
* parameterSeedMask, so that for each considered match tuple,
* projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold
* @since 2.0
*/
public boolean hasMatch(TupleMask parameterSeedMask, ITuple projectedParameterSeed);
/**
* Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
*
* @param parameters
* array where each non-null element binds the corresponding pattern parameter to a fixed value.
* @pre size of input array must be equal to the number of parameters.
* @return the number of pattern matches found.
*/
public int countMatches(Object[] parameters);
/**
* Returns the number of all matches of the pattern that conform to the given fixed values of some parameters.
*
* @param parameterSeedMask
* a mask that extracts those parameters of the query (from the entire parameter list) that should be
* bound to a fixed value
* @param parameters
* the tuple of fixed values restricting the match set to be considered, in the same order as given in
* parameterSeedMask, so that for each considered match tuple,
* projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold
* @return the number of pattern matches found.
* @since 1.7
*/
public int countMatches(TupleMask parameterSeedMask, ITuple projectedParameterSeed);
/**
* Gives an estimate of the number of different groups the matches are projected into by the given mask
* (e.g. for an identity mask, this means the full match set size). The estimate must meet the required accuracy.
*
* <p> If there is insufficient information to provide an answer up to the required precision, {@link Optional#empty()} may be returned.
* In other words, query backends may deny an answer, or do their best to give an estimate without actually determining the match set of the query.
* However, caching backends are expected to simply return the indexed (projection) size, initialized on-demand if necessary.
*
* <p> PRE: {@link TupleMask#isNonrepeating()} must hold for the group mask.
*
* @return if available, an estimate of the cardinality of the projection of the match set, with the desired accuracy.
*
* @since 2.1
*/
public Optional<Long> estimateCardinality(TupleMask groupMask, Accuracy requiredAccuracy);
/**
* Gives an estimate of the average size of different groups the matches are projected into by the given mask
* (e.g. for an identity mask, this means 1, while for an empty mask, the result is match set size).
* The estimate must meet the required accuracy.
*
* <p> If there is insufficient information to provide an answer up to the required precision, {@link Optional#empty()} may be returned.
* In other words, query backends may deny an answer, or do their best to give an estimate without actually determining the match set of the query.
* However, caching backends are expected to simply return the exact value from the index, initialized on-demand if necessary.
*
* <p> For an empty match set, zero is acceptable as an exact answer.
*
* <p> PRE: {@link TupleMask#isNonrepeating()} must hold for the group mask.
*
* @return if available, an estimate of the average size of each projection group of the match set, with the desired accuracy.
*
* @since 2.1
*/
public default Optional<Double> estimateAverageBucketSize(TupleMask groupMask, Accuracy requiredAccuracy) {
return StatisticsHelper.estimateAverageBucketSize(groupMask, requiredAccuracy, this::estimateCardinality);
}
/**
* 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 parameters
* array where each non-null element binds the corresponding pattern parameter to a fixed value.
* @pre size of input array must be equal to the number of parameters.
* @return a match represented in the internal {@link Tuple} representation.
* @since 2.0
*/
public Optional<Tuple> getOneArbitraryMatch(Object[] parameters);
/**
* 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 parameterSeedMask
* a mask that extracts those parameters of the query (from the entire parameter list) that should be
* bound to a fixed value
* @param parameters
* the tuple of fixed values restricting the match set to be considered, in the same order as given in
* parameterSeedMask, so that for each considered match tuple,
* projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold
* @return a match represented in the internal {@link Tuple} representation.
* @since 2.0
*/
public Optional<Tuple> getOneArbitraryMatch(TupleMask parameterSeedMask, ITuple parameters);
/**
* Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
*
* @param parameters
* array where each non-null element binds the corresponding pattern parameter to a fixed value.
* @pre size of input array must be equal to the number of parameters.
* @return matches represented in the internal {@link Tuple} representation.
* @since 2.0
*/
public Stream<Tuple> getAllMatches(Object[] parameters);
/**
* Returns the set of all matches of the pattern that conform to the given fixed values of some parameters.
*
* @param parameterSeedMask
* a mask that extracts those parameters of the query (from the entire parameter list) that should be
* bound to a fixed value
* @param parameters
* the tuple of fixed values restricting the match set to be considered, in the same order as given in
* parameterSeedMask, so that for each considered match tuple,
* projectedParameterSeed.equals(parameterSeedMask.transform(match)) should hold
* @return matches represented in the internal {@link Tuple} representation.
* @since 2.0
*/
public Stream<Tuple> getAllMatches(TupleMask parameterSeedMask, ITuple parameters);
/**
* The underlying query evaluator backend.
*/
public IQueryBackend getQueryBackend();
/**
* Internal method that registers low-level callbacks for match appearance and disappearance.
*
* <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.
*
* <p>
* The callback can be unregistered via invoking {@link #removeUpdateListener(Object)} with the same tag.
*
* @param listener
* the listener that will be notified of each new match that appears or disappears, starting from now.
* @param listenerTag
* a tag by which to identify the listener for later removal by {@link #removeUpdateListener(Object)}.
* @param fireNow
* if true, the insertion update allback will be immediately invoked on all current matches as a one-time effect.
*
* @throws UnsupportedOperationException if this is a non-incremental backend
* (i.e. {@link IQueryBackend#isCaching()} on {@link #getQueryBackend()} returns false)
*/
public void addUpdateListener(final IUpdateable listener, final Object listenerTag, boolean fireNow);
/**
* Removes an existing listener previously registered with the given tag.
*
* @throws UnsupportedOperationException if this is a non-incremental backend
* (i.e. {@link IQueryBackend#isCaching()} on {@link #getQueryBackend()} returns false)
*/
public void removeUpdateListener(final Object listenerTag);
}
|
