Method: iterator()

1: /*
2: * JOPA
3: * Copyright (C) 2024 Czech Technical University in Prague
4: *
5: * This library is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public
7: * License as published by the Free Software Foundation; either
8: * version 3.0 of the License, or (at your option) any later version.
9: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this library.
17: */
18: package cz.cvut.kbss.ontodriver;
19:
20: import cz.cvut.kbss.ontodriver.exception.OntoDriverException;
21: import cz.cvut.kbss.ontodriver.iteration.ResultRow;
22: import cz.cvut.kbss.ontodriver.iteration.ResultSetIterator;
23: import cz.cvut.kbss.ontodriver.iteration.ResultSetSpliterator;
24:
25: import java.util.Iterator;
26: import java.util.NoSuchElementException;
27: import java.util.Spliterator;
28: import java.util.stream.Stream;
29: import java.util.stream.StreamSupport;
30:
31: /**
32: * Represents a set of results of a SPARQL query.
33: * <p>
34: * This interface declares methods for getting values from a set of results of a SPARQL query issued to an ontology.
35: * <p>
36: * While this class is iterable, it is still necessary to close it either explicitly, or by declaring it within a
37: * try-with-resource block.
38: */
39: public interface ResultSet extends AutoCloseable, Iterable<ResultRow> {
40:
41: /**
42: * Retrieves index of a column with the specified label.
43: *
44: * @param columnLabel Label of the column
45: * @return index of the column or -1 if there is no such column
46: * @throws IllegalStateException If called on a closed result set
47: */
48: int findColumn(String columnLabel);
49:
50: /**
51: * Gets the count of available columns.
52: * <p>
53: * This number corresponds to the number of result variables bound in the query.
54: *
55: * @return Number of columns in the result set
56: * @throws IllegalStateException If called on a closed result set
57: */
58: int getColumnCount();
59:
60: /**
61: * Checks whether a value at the specified index is bound in the current result row.
62: * <p>
63: * Note that this method will return {@code false} also in case the index is out of range of the variables known to
64: * the result set as a whole.
65: *
66: * @param variableIndex Index of the variable
67: * @return {@code true} when value is bound in the current row, {@code false} otherwise
68: * @throws IllegalStateException If called on a closed result set
69: * @throws OntoDriverException When unable to resolve binding status
70: */
71: boolean isBound(int variableIndex) throws OntoDriverException;
72:
73: /**
74: * Checks whether a value of the specified variable is bound in the current result row.
75: * <p>
76: * Note that this method will return {@code false} also in case the variable is not known to the result set at all.
77: *
78: * @param variableName Variable name
79: * @return {@code true} when value is bound in the current row, {@code false} otherwise
80: * @throws IllegalStateException If called on a closed result set
81: * @throws OntoDriverException When unable to resolve binding status
82: */
83: boolean isBound(String variableName) throws OntoDriverException;
84:
85: /**
86: * Move the cursor to the first row.
87: *
88: * @throws IllegalStateException If called on a closed result set
89: * @throws OntoDriverException If some other error occurs
90: */
91: void first() throws OntoDriverException;
92:
93: /**
94: * Retrieves value from column at the specified index and returns it as a {@code boolean}.
95: *
96: * @param columnIndex Column index, the first column has index 0
97: * @return {@code boolean} value
98: * @throws IllegalStateException If called on a closed result set
99: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
100: * {@code boolean} or there occurs some other error
101: */
102: boolean getBoolean(int columnIndex) throws OntoDriverException;
103:
104: /**
105: * Retrieves value from column with the specified label and returns it as a {@code boolean}.
106: *
107: * @param columnLabel Label of the column
108: * @return {@code boolean} value
109: * @throws IllegalStateException If called on a closed result set
110: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
111: * boolean} or there occurs some other error
112: */
113: boolean getBoolean(String columnLabel) throws OntoDriverException;
114:
115: /**
116: * Retrieves value from column at the specified index and returns it as {@code byte}.
117: *
118: * @param columnIndex Column index, the first column has index 0
119: * @return {@code byte} value
120: * @throws IllegalStateException If called on a closed result set
121: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
122: * {@code byte} or there occurs some other error
123: */
124: byte getByte(int columnIndex) throws OntoDriverException;
125:
126: /**
127: * Retrieves value from column with the specified label and returns it as {@code byte}.
128: *
129: * @param columnLabel Label of the column
130: * @return {@code byte} value
131: * @throws IllegalStateException If called on a closed result set
132: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
133: * byte} or there occurs some other error
134: */
135: byte getByte(String columnLabel) throws OntoDriverException;
136:
137: /**
138: * Retrieves value from column at the specified index and returns it as {@code double}.
139: *
140: * @param columnIndex Column index, the first column has index 0
141: * @return {@code double} value
142: * @throws IllegalStateException If called on a closed result set
143: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
144: * {@code double} or there occurs some other error
145: */
146: double getDouble(int columnIndex) throws OntoDriverException;
147:
148: /**
149: * Retrieves value from column with the specified label and returns it as {@code double}.
150: *
151: * @param columnLabel Label of the column
152: * @return {@code double} value
153: * @throws IllegalStateException If called on a closed result set
154: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
155: * double} or there occurs some other error
156: */
157: double getDouble(String columnLabel) throws OntoDriverException;
158:
159: /**
160: * Retrieves value from column at the specified index and returns it as {@code float}.
161: *
162: * @param columnIndex Column index, the first column has index 0
163: * @return {@code float} value
164: * @throws IllegalStateException If called on a closed result set
165: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
166: * {@code float} or there occurs some other error
167: */
168: float getFloat(int columnIndex) throws OntoDriverException;
169:
170: /**
171: * Retrieves value from column with the specified label and returns it as {@code float}.
172: *
173: * @param columnLabel Label of the column
174: * @return {@code float} value
175: * @throws IllegalStateException If called on a closed result set
176: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
177: * float} or there occurs some other error
178: */
179: float getFloat(String columnLabel) throws OntoDriverException;
180:
181: /**
182: * Retrieves value from column at the specified index and returns it as {@code int}.
183: *
184: * @param columnIndex Column index, the first column has index 0
185: * @return {@code int} value
186: * @throws IllegalStateException If called on a closed result set
187: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
188: * {@code int} or there occurs some other error
189: */
190: int getInt(int columnIndex) throws OntoDriverException;
191:
192: /**
193: * Retrieves value from column with the specified label and returns it as {@code int}.
194: *
195: * @param columnLabel Label of the column
196: * @return {@code int} value
197: * @throws IllegalStateException If called on a closed result set
198: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
199: * int} or there occurs some other error
200: */
201: int getInt(String columnLabel) throws OntoDriverException;
202:
203: /**
204: * Retrieves value from column at the specified index and returns it as {@code long}.
205: *
206: * @param columnIndex Column index, the first column has index 0
207: * @return {@code long} value
208: * @throws IllegalStateException If called on a closed result set
209: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
210: * {@code long} or there occurs some other error
211: */
212: long getLong(int columnIndex) throws OntoDriverException;
213:
214: /**
215: * Retrieves value from column with the specified label and returns it as {@code long}.
216: *
217: * @param columnLabel Label of the column
218: * @return {@code long} value
219: * @throws IllegalStateException If called on a closed result set
220: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
221: * long} or there occurs some other error
222: */
223: long getLong(String columnLabel) throws OntoDriverException;
224:
225: /**
226: * Retrieves value from column at the specified index and returns it as {@code Object}.
227: *
228: * @param columnIndex Column index, the first column has index 0
229: * @return column value cast to {@code Object}
230: * @throws IllegalStateException If called on a closed result set
231: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index or there occurs some other
232: * error
233: */
234: Object getObject(int columnIndex) throws OntoDriverException;
235:
236: /**
237: * Retrieves value from column with the specified label and returns it as {@code Object}.
238: *
239: * @param columnLabel Label of the column
240: * @return column value cast to {@code Object}
241: * @throws IllegalStateException If called on a closed result set
242: * @throws OntoDriverException If there is no column with the specified label or there occurs some other error
243: */
244: Object getObject(String columnLabel) throws OntoDriverException;
245:
246: /**
247: * Retrieves value from column at the specified index and returns it as an instance of the specified class.
248: * <p>
249: * The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
250: * calling a constructor of the specified type.
251: *
252: * @param columnIndex Column index, the first column has index 0
253: * @param cls Requested class type
254: * @param <T> Return type
255: * @return Value of the column
256: * @throws IllegalStateException If called on a closed result set
257: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
258: * the specified type or there occurs some other error
259: */
260: <T> T getObject(int columnIndex, Class<T> cls) throws OntoDriverException;
261:
262: /**
263: * Retrieves value from column with the specified label and returns it as an instance of the specified class.
264: * <p>
265: * The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
266: * calling a constructor of the specified type.
267: *
268: * @param columnLabel Label of the column
269: * @param cls Requested class type
270: * @param <T> Return type
271: * @return Value of the column.
272: * @throws IllegalStateException If called on a closed result set
273: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to the
274: * specified type or there occurs some other error
275: */
276: <T> T getObject(String columnLabel, Class<T> cls) throws OntoDriverException;
277:
278: /**
279: * Retrieves index of the current row.
280: * <p>
281: * The first row has index 0.
282: *
283: * @return the current row index, -1 if there is no current row
284: * @throws IllegalStateException If called on a closed result set
285: * @throws OntoDriverException If some other error occurs
286: */
287: int getRowIndex() throws OntoDriverException;
288:
289: /**
290: * Retrieves value of column at the specified index and returns it as {@code short}.
291: *
292: * @param columnIndex Column index, the first column has index 0
293: * @return {@code short} value
294: * @throws IllegalStateException If called on a closed result set
295: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
296: * {@code short} or there occurs some other error
297: */
298: short getShort(int columnIndex) throws OntoDriverException;
299:
300: /**
301: * Retrieves value of column with the specified label and returns it as {@code short}.
302: *
303: * @param columnLabel Label of the column
304: * @return {@code short} value
305: * @throws IllegalStateException If called on a closed result set
306: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
307: * short} or there occurs some other error
308: */
309: short getShort(String columnLabel) throws OntoDriverException;
310:
311: /**
312: * Retrieves the {@code Statement} that produced this {@code ResultSet} object. If this result set was generated
313: * some other way, this method will return {@code null}.
314: *
315: * @return The {@code Statement} that produced this {@code ResultSet} or null
316: * @throws IllegalStateException If called on a closed result set
317: * @throws OntoDriverException If some other error occurs
318: */
319: Statement getStatement() throws OntoDriverException;
320:
321: /**
322: * Retrieves value of column at the specified index and returns it as {@code String}.
323: *
324: * @param columnIndex Column index, the first column has index 0
325: * @return {@code String} value
326: * @throws IllegalStateException If called on a closed result set
327: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
328: * {@code String} or there occurs some other error
329: */
330: String getString(int columnIndex) throws OntoDriverException;
331:
332: /**
333: * Retrieves value of column with the specified label and returns it as {@code String}.
334: *
335: * @param columnLabel Label of the column
336: * @return {@code String} value
337: * @throws IllegalStateException If called on a closed result set
338: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
339: * String} or there occurs some other error
340: */
341: String getString(String columnLabel) throws OntoDriverException;
342:
343: /**
344: * Returns true if the cursor is at the first row of this result set.
345: *
346: * @return True if the cursor is at the first row, false otherwise
347: * @throws IllegalStateException If called on a closed result set
348: * @throws OntoDriverException If some other error occurs
349: */
350: boolean isFirst() throws OntoDriverException;
351:
352: /**
353: * Returns true if the cursor does not point at the last row in this result set.
354: *
355: * @return True if there is at least one next row
356: * @throws IllegalStateException If called on a closed result set
357: * @throws OntoDriverException If some other error occurs
358: */
359: boolean hasNext() throws OntoDriverException;
360:
361: /**
362: * Move the cursor to the last row in this results set.
363: * <p>
364: * Note that since the result set may be asynchronously updated, the last row does not have to always be the same.
365: *
366: * @throws IllegalStateException If called on a closed result set
367: * @throws OntoDriverException If some other error occurs
368: */
369: void last() throws OntoDriverException;
370:
371: /**
372: * Move the cursor one row forward.
373: *
374: * @throws NoSuchElementException If there are no more elements
375: * @throws IllegalStateException If called on a closed result set
376: * @throws OntoDriverException If some other error occurs
377: */
378: void next() throws OntoDriverException;
379:
380: /**
381: * Move the cursor one row backwards.
382: *
383: * @throws IllegalStateException If called on a closed result set or the cursor is at the first row
384: * @throws OntoDriverException If some other error occurs
385: */
386: void previous() throws OntoDriverException;
387:
388: /**
389: * Move the cursor a relative number of rows, either positive or negative.
390: *
391: * @param rows The number of rows to move the cursor of
392: * @throws IllegalStateException If called on a closed result set
393: * @throws OntoDriverException If the {@code rows} number is not valid or some other error occurs
394: */
395: void relative(int rows) throws OntoDriverException;
396:
397: /**
398: * Move the cursor to the specified row index.
399: * <p>
400: * The first row has index 0.
401: *
402: * @param rowIndex Index to move the cursor to
403: * @throws IllegalStateException If called on a closed result set
404: * @throws OntoDriverException If the index is not valid row index or some other error occurs
405: */
406: void setRowIndex(int rowIndex) throws OntoDriverException;
407:
408: /**
409: * Closes this result set releasing any sub-resources it holds.
410: * <p>
411: * After closing the result set is not usable any more and calling methods on it (except {@code close} and {@code
412: * isOpen}) will result in {@code OntoDriverException}.
413: * <p>
414: * Calling {@code close} on already closed resource does nothing.
415: * <p>
416: * Calling this method also results in immediate disconnection of all registered observers and cancellation of any
417: * running reasoning associated with this result set.
418: *
419: * @throws OntoDriverException If an ontology access error occurs.
420: */
421: @Override
422: void close() throws OntoDriverException;
423:
424: /**
425: * Retrieves status of this result set.
426: *
427: * @return {@code true} if the resource is open, {@code false} otherwise
428: */
429: boolean isOpen();
430:
431: /**
432: * Creates a {@link Iterator} over this result set.
433: * <p>
434: * Note that the iterator does not close this result set after finishing its iteration. The result has to be closed
435: * by the caller.
436: *
437: * @return Iterator over this result set
438: */
439: @Override
440: default Iterator<ResultRow> iterator() {
441:• if (!isOpen()) {
442: throw new IllegalStateException("The result set is closed.");
443: }
444: return new ResultSetIterator(this);
445: }
446:
447: /**
448: * Creates a {@link Spliterator} over this result set.
449: * <p>
450: * Note that the spliterator does not close this result set after finishing its iteration. The result has to be
451: * closed by the caller.
452: *
453: * @return Spliterator over this result set
454: */
455: @Override
456: default Spliterator<ResultRow> spliterator() {
457: if (!isOpen()) {
458: throw new IllegalStateException("The result set is closed.");
459: }
460: return new ResultSetSpliterator(this);
461: }
462:
463: /**
464: * Creates a sequential {@link Stream} over this result set.
465: * <p>
466: * The default implementation creates a stream using the default {@link #spliterator()}.
467: * <p>
468: * Note that the stream does not close this result set after finishing its iteration. The result set has to be
469: * closed by the caller.
470: *
471: * @return A {@code Stream} over this result set.
472: */
473: default Stream<ResultRow> stream() {
474: return StreamSupport.stream(spliterator(), false);
475: }
476: }