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