diff options
Diffstat (limited to 'subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/queries/PQuery.java')
-rw-r--r-- | subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/queries/PQuery.java | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/queries/PQuery.java b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/queries/PQuery.java new file mode 100644 index 00000000..a909c650 --- /dev/null +++ b/subprojects/viatra-runtime/src/main/java/tools/refinery/viatra/runtime/matchers/psystem/queries/PQuery.java | |||
@@ -0,0 +1,154 @@ | |||
1 | /******************************************************************************* | ||
2 | * Copyright (c) 2010-2013, Zoltan Ujhelyi, Istvan Rath 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 | package tools.refinery.viatra.runtime.matchers.psystem.queries; | ||
10 | |||
11 | import java.util.List; | ||
12 | import java.util.Set; | ||
13 | |||
14 | import tools.refinery.viatra.runtime.matchers.ViatraQueryRuntimeException; | ||
15 | import tools.refinery.viatra.runtime.matchers.backend.IQueryBackend; | ||
16 | import tools.refinery.viatra.runtime.matchers.backend.IQueryBackendHintProvider; | ||
17 | import tools.refinery.viatra.runtime.matchers.backend.QueryEvaluationHint; | ||
18 | import tools.refinery.viatra.runtime.matchers.psystem.PBody; | ||
19 | import tools.refinery.viatra.runtime.matchers.psystem.PTraceable; | ||
20 | import tools.refinery.viatra.runtime.matchers.psystem.TypeJudgement; | ||
21 | |||
22 | /** | ||
23 | * Internal representation of a query / graph pattern (using a constraint system formalism), | ||
24 | * to be interpreted by a query evaluator ({@link IQueryBackend}). | ||
25 | * End-users of VIATRA Query should access a query as an IQuerySpecification instead. | ||
26 | * | ||
27 | * <p> | ||
28 | * PQuerys are definitions of queries usable inside pattern descriptions. Such description always has (a non-null) name. The query | ||
29 | * itself is defined as a (non-empty) set of {@link PBody} instances, the result is the disjunction of the single | ||
30 | * {@link PBody} instances. </p> | ||
31 | * <p> | ||
32 | * A PQuery might be constructed from erroneous patterns or might be uninitialized - this is represented by its status. | ||
33 | * | ||
34 | * @author Zoltan Ujhelyi | ||
35 | * @since 0.8.0 | ||
36 | * @noimplement This interface is not intended to be implemented by clients. Use {@link BasePQuery} as a base class instead. | ||
37 | */ | ||
38 | public interface PQuery extends PQueryHeader, PTraceable { | ||
39 | |||
40 | // TODO rewritten as / rewritten from traceability to PDisjunction? | ||
41 | |||
42 | /** | ||
43 | * @author Zoltan Ujhelyi | ||
44 | * | ||
45 | */ | ||
46 | public enum PQueryStatus { | ||
47 | /** | ||
48 | * Marks that the query definition is not initialized | ||
49 | */ | ||
50 | UNINITIALIZED, | ||
51 | /** | ||
52 | * Marks that the query definition is being initialized | ||
53 | * @since 1.4 | ||
54 | */ | ||
55 | INITIALIZING, | ||
56 | /** | ||
57 | * The query definition was successfully initialized | ||
58 | */ | ||
59 | OK, | ||
60 | /** | ||
61 | * The query definition was initialized, but some issues were present | ||
62 | */ | ||
63 | WARNING, | ||
64 | /** | ||
65 | * The query definition was not successfully initialized because of an error | ||
66 | */ | ||
67 | ERROR | ||
68 | } | ||
69 | |||
70 | /** | ||
71 | * Returns all bodies associated with the query in their canonical form. If called multiple times, the same set with | ||
72 | * the same contents will be returned. | ||
73 | * | ||
74 | */ | ||
75 | PDisjunction getDisjunctBodies(); | ||
76 | |||
77 | /** | ||
78 | * Returns all queries directly referred in the constraints. They are all required to evaluate this query | ||
79 | * | ||
80 | * @return a non-null, but possibly empty list of query definitions | ||
81 | */ | ||
82 | Set<PQuery> getDirectReferredQueries(); | ||
83 | |||
84 | /** | ||
85 | * Returns all queries required to evaluate this query (transitively). | ||
86 | * | ||
87 | * @return a non-null, but possibly empty list of query definitions | ||
88 | */ | ||
89 | Set<PQuery> getAllReferredQueries(); | ||
90 | |||
91 | /** | ||
92 | * Returns the initialization status of the definition | ||
93 | * | ||
94 | */ | ||
95 | PQueryStatus getStatus(); | ||
96 | |||
97 | /** | ||
98 | * Returns a list describing the problems that were found in this query. | ||
99 | * | ||
100 | * <p> TODO: formulate invariant connecting {@link #getPProblems()} and {@link #getStatus()}. | ||
101 | * | ||
102 | * @return a non-null, but possibly empty list of problems | ||
103 | */ | ||
104 | List<PProblem> getPProblems(); | ||
105 | |||
106 | /** | ||
107 | * Before a modification operation is executed, a mutability check is performed (via the {@link #getStatus()} | ||
108 | * implementation, and in case of problems an {@link IllegalStateException} is thrown. | ||
109 | */ | ||
110 | void checkMutability(); | ||
111 | |||
112 | /** | ||
113 | * An option to check mutability of the query. It can be used to avoid getting an {@link IllegalStateException} by | ||
114 | * the execution of {@link #checkMutability()}. | ||
115 | * | ||
116 | * @return true if the query specification is still editable | ||
117 | */ | ||
118 | boolean isMutable(); | ||
119 | |||
120 | /** | ||
121 | * Optional hints regarding the query evaluation strategy, to be interpreted by the query engine. | ||
122 | * <p> To ensure the possibility of external overrides, | ||
123 | * the evaluation engine should not directly consult this field, | ||
124 | * but use an {@link IQueryBackendHintProvider} instead. | ||
125 | */ | ||
126 | public QueryEvaluationHint getEvaluationHints(); | ||
127 | |||
128 | |||
129 | /** | ||
130 | * Type information, expressed on query parameters, that all matches of the query are guaranteed to respect. | ||
131 | * <p> At the very minimum, this should include the declared types of the parameters. | ||
132 | * <p> The type judgement tuples shall contain the <i>parameter index</i>, NOT the {@link PParameter} object. | ||
133 | * | ||
134 | * @return a non-null set of type judgements that the query guarantees for its matches | ||
135 | */ | ||
136 | public Set<TypeJudgement> getTypeGuarantees(); | ||
137 | |||
138 | /** | ||
139 | * If the query definition is uninitialized, initializes it. | ||
140 | * @throws ViatraQueryRuntimeException if initialization of query specification fails | ||
141 | */ | ||
142 | public abstract void ensureInitialized(); | ||
143 | |||
144 | /** | ||
145 | * Returns the end-user query specification API objects that wrap this query. | ||
146 | * | ||
147 | * <p> Intended for traceability and debug purposes, not part of normal operation. | ||
148 | * Returned list is intended to be appended during query specification construction time. | ||
149 | * | ||
150 | * @return a non-null, but possibly empty list of query specification objects; | ||
151 | */ | ||
152 | List<Object> publishedAs(); | ||
153 | |||
154 | } \ No newline at end of file | ||