1 /*
2 * #%L
3 * prolobjectlink-jpi
4 * %%
5 * Copyright (C) 2019 Prolobjectlink Project
6 * %%
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 * THE SOFTWARE.
24 * #L%
25 */
26 package io.github.prolobjectlink.prolog;
27
28 import java.util.Collection;
29 import java.util.Iterator;
30 import java.util.List;
31 import java.util.Map;
32
33 /**
34 * <p>
35 * Prolog query is the mechanism to query the prolog database loaded in prolog
36 * engine. The way to create a new prolog query is invoking
37 * {@link PrologEngine#query(String)},
38 * {@link PrologEngine#query(PrologTerm, PrologTerm...)} or
39 * {@link PrologEngine#query(PrologTerm[])}. When this methods are called the
40 * prolog query is open an only with {@link #dispose()} close the current query
41 * and release all internal resources.
42 * </p>
43 *
44 * <p>
45 * Prolog query implement {@link Iterable} and {@link Iterator}. This
46 * implementation help to obtain successive solutions present in the query.
47 * </p>
48 *
49 * <pre>
50 * PrologEngine engine = provider.newEngine("zoo.pl");
51 * PrologVariable x = provider.newVariable("X", 0);
52 * PrologQuery query = engine.query(provider.newStructure("dark", x));
53 * while (query.hasNext()) {
54 * PrologTerm value = query.nextVariablesSolution().get("X");
55 * System.out.println(value);
56 * }
57 * query.dispose();
58 * </pre>
59 *
60 * <pre>
61 * PrologEngine engine = provider.newEngine("zoo.pl");
62 * PrologVariable x = provider.newVariable("X", 0);
63 * PrologQuery query = engine.query(provider.newStructure("dark", x));
64 * for (Collection<PrologTerm> col : query) {
65 * for (PrologTerm prologTerm : col) {
66 * System.out.println(prologTerm);
67 * }
68 * }
69 * query.dispose();
70 * </pre>
71 *
72 * @author Jose Zalacain
73 * @since 1.0
74 */
75 public interface PrologQuery extends Iterator<Collection<PrologTerm>>, Iterable<Collection<PrologTerm>> {
76
77 /**
78 * Provider instance
79 *
80 * @return provider instance
81 * @since 1.0
82 */
83 public PrologProvider getProvider();
84
85 /**
86 * Engine hold by the current query
87 *
88 * @return used by the current query
89 * @since 1.0
90 */
91 public PrologEngine getEngine();
92
93 /**
94 * <p>
95 * Check that the current query has solution.
96 * </p>
97 *
98 * @return true if the current query has solution, false if not
99 * @since 1.0
100 */
101 public boolean hasSolution();
102
103 /**
104 * <p>
105 * Check if the current query has more solutions.
106 * </p>
107 *
108 * @return true if the current query has more solutions, false if not
109 * @since 1.0
110 */
111 public boolean hasMoreSolutions();
112
113 /**
114 * Return the prolog terms that conform the solution set for the current query.
115 * The solution is a prolog terms array and every term is an instance value for
116 * the variables not anonymous involved in the query.
117 *
118 * @return prolog terms solution array for the current query
119 * @since 1.0
120 */
121 public PrologTerm[] oneSolution();
122
123 /**
124 * Return the prolog terms that conform the solution set for the current query.
125 * The solution set is a prolog terms map and every map entry is a pair variable
126 * name and variable instance value for the variables not anonymous involved in
127 * the query.
128 *
129 * @return variable name - variable instance (key - value) map that conform the
130 * solution set for the current query.
131 * @since 1.0
132 */
133 public Map<String, PrologTerm> oneVariablesSolution();
134
135 /**
136 * Return the next prolog terms solution array for the current query. The
137 * solution is a prolog terms array and every term is an instance value for the
138 * variables not anonymous involved in the query.
139 *
140 * @return prolog terms solution array for the current query
141 * @since 1.0
142 */
143 public PrologTerm[] nextSolution();
144
145 /**
146 * Return the next prolog terms that conform the solution set for the current
147 * query. The solution set is a prolog terms map and every map entry is a pair
148 * variable name and variable instance value for the variables not anonymous
149 * involved in the query.
150 *
151 * @return variable name - variable instance (key - value) map that conform the
152 * solution set for the current query.
153 * @since 1.0
154 */
155 public Map<String, PrologTerm> nextVariablesSolution();
156
157 /**
158 * Return a Prolog terms matrix of n x m order that conform the solution set for
159 * the current query where n is the solution number and m is a free variable
160 * number in the query.
161 *
162 * @param n array order or Prolog term rows number
163 * @return a Prolog terms matrix of n x m order that conform the solution set
164 * @since 1.0
165 */
166 public PrologTerm[][] nSolutions(int n);
167
168 /**
169 * Return an array of n size with maps of variables name key and Prolog terms as
170 * value that conform the solution set for the current query where n is the
171 * solution number.
172 *
173 * @param n array order or Prolog term items number
174 * @return an array of n size with maps of variables name key and Prolog terms
175 * as value that conform the solution set
176 * @since 1.0
177 */
178 public Map<String, PrologTerm>[] nVariablesSolutions(int n);
179
180 /**
181 * Return a Prolog terms matrix of n x m order that conform the solution set for
182 * the current query where n is the solution number and m is a free variable
183 * number in the query.
184 *
185 * @return a Prolog terms matrix of n x m order that conform the solution set
186 * @since 1.0
187 */
188 public PrologTerm[][] allSolutions();
189
190 /**
191 * Return an array of map of variables name key and Prolog terms as value that
192 * conform the solution set for the current query.
193 *
194 * @return an array of map of variables name key and Prolog terms as value that
195 * conform the solution set
196 * @since 1.0
197 */
198 public Map<String, PrologTerm>[] allVariablesSolutions();
199
200 /**
201 *
202 * Return the equivalent Java objects that conform the solution set for the
203 * current query. The solution set is a Java objects list and every term is a
204 * conversion of the instance value for the variables not anonymous involved in
205 * the query.
206 *
207 *
208 * <pre>
209 * List<Object> solution = query.oneResult();
210 * for (int i = 0; i < solution.size(); i++) {
211 * System.out.println(solution.get(i));
212 * }
213 * </pre>
214 *
215 * @return Java objects solution list for the current query
216 * @since 1.0
217 */
218 public List<Object> oneResult();
219
220 /**
221 *
222 * Return the equivalent Java objects that conform the solution set for the
223 * current query. The solution set is a Java object map and every map entry is a
224 * pair variable name and a Java object conversion of the variable instance
225 * value for the variables not anonymous involved in the query.
226 *
227 * @return variable name - Java object conversion of the variable instance (key
228 * - value) map that conform the solution set for the current query.
229 * @since 1.0
230 */
231 public Map<String, Object> oneVariablesResult();
232
233 /**
234 * Return the next Java objects solution list for the current query. The
235 * solution is a Java objects list and every object is an instance value for the
236 * variables not anonymous involved in the query.
237 *
238 * @return Java objects solution list for the current query
239 * @since 1.1
240 */
241 public List<Object> nextResult();
242
243 /**
244 * Return the next Java objects that conform the solution set for the current
245 * query. The solution set is an objects map and every map entry is a pair
246 * variable name and variable instance value for the variables not anonymous
247 * involved in the query.
248 *
249 * @return variable name - variable instance (key - value) map that conform the
250 * solution set for the current query.
251 * @since 1.1
252 */
253 public Map<String, Object> nextVariablesResult();
254
255 /**
256 * Return a list of list of Java Objects that conform the solution set for the
257 * current query where n is the solution number and m is a free variable number
258 * in the query.
259 *
260 * @param n list order or Java objects rows number
261 * @return a list of list of Java Objects that conform the solution set
262 * @since 1.1
263 */
264 public List<List<Object>> nResult(int n);
265
266 /**
267 * Return a list of n size with maps of variables name key and Java objects as
268 * value that conform the solution set for the current query where n is the
269 * solution number.
270 *
271 * @param n list order or Java objects items number
272 * @return a list of n size with maps of variables name key and Java objects as
273 * value that conform the solution set
274 * @since 1.1
275 */
276 public List<Map<String, Object>> nVariablesResults(int n);
277
278 /**
279 * Return a list of list of Java Objects that conform the solution set for the
280 * current query.
281 *
282 * @return a list of list of Java Objects that conform the solution set for the
283 * current query.
284 * @since 1.0
285 */
286 public List<List<Object>> allResults();
287
288 /**
289 * Return a list of map of variables name key and Java objects as value that
290 * conform the solution set for the current query.
291 *
292 * @return a list of map of variables name key and Java objects as value that
293 * conform the solution set
294 * @since 1.0
295 */
296 public List<Map<String, Object>> allVariablesResults();
297
298 /**
299 * Return a map of variables name key and Prolog terms as value that conform the
300 * solution set for the current query.
301 *
302 * @return a map of variables name key and Prolog terms as value that conform
303 * the solution set
304 * @since 1.0
305 */
306 public Map<String, PrologTerm> one();
307
308 /**
309 * Return the next prolog terms that conform the solution set for the current
310 * query. The solution set is a prolog terms map and every map entry is a pair
311 * variable name and variable instance value for the variables not anonymous
312 * involved in the query.
313 *
314 * @return variable name - variable instance (key - value) map that conform the
315 * solution set for the current query.
316 * @since 1.1
317 */
318 public Map<String, PrologTerm> more();
319
320 /**
321 * Return a list of n size with maps of variables name key and Prolog terms as
322 * value that conform the solution set for the current query where n is the
323 * solution number.
324 *
325 * @return an list of n size with maps of variables name key and Prolog terms as
326 * value that conform the solution set
327 * @param n list order or Prolog term items number
328 * @since 1.1
329 */
330 public List<Map<String, PrologTerm>> nths(int n);
331
332 /**
333 * Return a list of map of variables name key and Prolog terms as value that
334 * conform the solution set for the current query.
335 *
336 * @return a list of map of variables name key and Prolog terms as value that
337 * conform the solution set
338 * @since 1.0
339 */
340 public List<Map<String, PrologTerm>> all();
341
342 /**
343 * Release all allocations for the query
344 *
345 * @since 1.0
346 */
347 public void dispose();
348
349 }