-
Notifications
You must be signed in to change notification settings - Fork 14
/
ResultSet.java
481 lines (438 loc) · 20.7 KB
/
ResultSet.java
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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
/**
* Copyright (C) 2019 Czech Technical University in Prague
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU General Public License as published by the Free Software
* Foundation, either version 3 of the License, or (at your option) any
* later version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details. You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package cz.cvut.kbss.ontodriver;
import cz.cvut.kbss.ontodriver.exception.OntoDriverException;
import cz.cvut.kbss.ontodriver.iteration.ResultRow;
import cz.cvut.kbss.ontodriver.iteration.ResultSetIterator;
import cz.cvut.kbss.ontodriver.iteration.ResultSetSpliterator;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.Observer;
import java.util.Spliterator;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;
/**
* Represents a set of results of a SPARQL query.
* <p>
* This interface declares methods for getting values from a set of results of a SPARQL query issued to an ontology.
* <p>
* While this class is iterable, it is still necessary to close it either explicitly, or by declaring it within a try-with-resource block.
*/
public interface ResultSet extends AutoCloseable, Iterable<ResultRow> {
/**
* Retrieves index of a column with the specified label.
*
* @param columnLabel Label of the column
* @return index of the column or -1 if there is no such column
* @throws IllegalStateException If called on a closed result set
*/
int findColumn(String columnLabel);
/**
* Gets the count of available columns.
* <p>
* This number corresponds to the number of result variables bound in the query.
*
* @return Number of columns in the result set
* @throws IllegalStateException If called on a closed result set
*/
int getColumnCount();
/**
* Checks whether a value at the specified index is bound in the current result row.
* <p>
* Note that this method will return {@code false} also in case the index is out of range of the variables known to
* the result set as a whole.
*
* @param variableIndex Index of the variable
* @return {@code true} when value is bound in the current row, {@code false} otherwise
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException When unable to resolve binding status
*/
boolean isBound(int variableIndex) throws OntoDriverException;
/**
* Checks whether a value of the specified variable is bound in the current result row.
* <p>
* Note that this method will return {@code false} also in case the variable is not known to the result set at all.
*
* @param variableName Variable name
* @return {@code true} when value is bound in the current row, {@code false} otherwise
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException When unable to resolve binding status
*/
boolean isBound(String variableName) throws OntoDriverException;
/**
* Move the cursor to the first row.
*
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
void first() throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as a {@code boolean}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code boolean} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code boolean} or there occurs some other error
*/
boolean getBoolean(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as a {@code boolean}.
*
* @param columnLabel Label of the column
* @return {@code boolean} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* boolean} or there occurs some other error
*/
boolean getBoolean(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as {@code byte}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code byte} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code byte} or there occurs some other error
*/
byte getByte(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as {@code byte}.
*
* @param columnLabel Label of the column
* @return {@code byte} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* byte} or there occurs some other error
*/
byte getByte(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as {@code double}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code double} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code double} or there occurs some other error
*/
double getDouble(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as {@code double}.
*
* @param columnLabel Label of the column
* @return {@code double} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* double} or there occurs some other error
*/
double getDouble(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as {@code float}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code float} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code float} or there occurs some other error
*/
float getFloat(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as {@code float}.
*
* @param columnLabel Label of the column
* @return {@code float} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* float} or there occurs some other error
*/
float getFloat(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as {@code int}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code int} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code int} or there occurs some other error
*/
int getInt(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as {@code int}.
*
* @param columnLabel Label of the column
* @return {@code int} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* int} or there occurs some other error
*/
int getInt(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as {@code long}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code long} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code long} or there occurs some other error
*/
long getLong(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as {@code long}.
*
* @param columnLabel Label of the column
* @return {@code long} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* long} or there occurs some other error
*/
long getLong(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as {@code Object}.
*
* @param columnIndex Column index, the first column has index 0
* @return column value cast to {@code Object}
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index or there occurs some other
* error
*/
Object getObject(int columnIndex) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as {@code Object}.
*
* @param columnLabel Label of the column
* @return column value cast to {@code Object}
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label or there occurs some other error
*/
Object getObject(String columnLabel) throws OntoDriverException;
/**
* Retrieves value from column at the specified index and returns it as an instance of the specified class.
* <p>
* The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
* calling a constructor of the specified type.
*
* @param columnIndex Column index, the first column has index 0
* @param cls Requested class type
* @param <T> Return type
* @return Value of the column
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* the specified type or there occurs some other error
*/
<T> T getObject(int columnIndex, Class<T> cls) throws OntoDriverException;
/**
* Retrieves value from column with the specified label and returns it as an instance of the specified class.
* <p>
* The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
* calling a constructor of the specified type.
*
* @param columnLabel Label of the column
* @param cls Requested class type
* @param <T> Return type
* @return Value of the column.
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to the
* specified type or there occurs some other error
*/
<T> T getObject(String columnLabel, Class<T> cls) throws OntoDriverException;
/**
* Retrieves index of the current row.
* <p>
* The first row has index 0.
*
* @return the current row index, -1 if there is no current row
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
int getRowIndex() throws OntoDriverException;
/**
* Retrieves value of column at the specified index and returns it as {@code short}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code short} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code short} or there occurs some other error
*/
short getShort(int columnIndex) throws OntoDriverException;
/**
* Retrieves value of column with the specified label and returns it as {@code short}.
*
* @param columnLabel Label of the column
* @return {@code short} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* short} or there occurs some other error
*/
short getShort(String columnLabel) throws OntoDriverException;
/**
* Retrieves the {@code Statement} that produced this {@code ResultSet} object. If this result set was generated
* some other way, this method will return {@code null}.
*
* @return The {@code Statement} that produced this {@code ResultSet} or null
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
Statement getStatement() throws OntoDriverException;
/**
* Retrieves value of column at the specified index and returns it as {@code String}.
*
* @param columnIndex Column index, the first column has index 0
* @return {@code String} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
* {@code String} or there occurs some other error
*/
String getString(int columnIndex) throws OntoDriverException;
/**
* Retrieves value of column with the specified label and returns it as {@code String}.
*
* @param columnLabel Label of the column
* @return {@code String} value
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
* String} or there occurs some other error
*/
String getString(String columnLabel) throws OntoDriverException;
/**
* Returns true if the cursor is at the first row of this result set.
*
* @return True if the cursor is at the first row, false otherwise
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
boolean isFirst() throws OntoDriverException;
/**
* Returns true if the cursor does not point at the last row in this result set.
*
* @return True if there is at least one next row
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
boolean hasNext() throws OntoDriverException;
/**
* Move the cursor to the last row in this results set.
* <p>
* Note that since the result set may be asynchronously updated, the last row does not have to always be the same.
*
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
void last() throws OntoDriverException;
/**
* Move the cursor one row forward.
*
* @throws NoSuchElementException If there are no more elements
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If some other error occurs
*/
void next() throws OntoDriverException;
/**
* Move the cursor one row backwards.
*
* @throws IllegalStateException If called on a closed result set or the cursor is at the first row
* @throws OntoDriverException If some other error occurs
*/
void previous() throws OntoDriverException;
/**
* Registers the specified {@code Observer} at this result set.
* <p>
* The observer is notified whenever new results of ontology reasoning are available.
*
* @param observer The observer to register
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If or some other error occurs
*/
void registerObserver(Observer observer) throws OntoDriverException;
/**
* Move the cursor a relative number of rows, either positive or negative.
*
* @param rows The number of rows to move the cursor of
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the {@code rows} number is not valid or some other error occurs
*/
void relative(int rows) throws OntoDriverException;
/**
* Move the cursor to the specified row index.
* <p>
* The first row has index 0.
*
* @param rowIndex Index to move the cursor to
* @throws IllegalStateException If called on a closed result set
* @throws OntoDriverException If the index is not valid row index or some other error occurs
*/
void setRowIndex(int rowIndex) throws OntoDriverException;
/**
* Closes this result set releasing any sub-resources it holds.
* <p>
* After closing the result set is not usable any more and calling methods on it (except {@code close} and {@code
* isOpen}) will result in {@code OntoDriverException}.
* <p>
* Calling {@code close} on already closed resource does nothing.
* <p>
* Calling this method also results in immediate disconnection of all registered observers and cancellation of any
* running reasoning associated with this result set.
*
* @throws OntoDriverException If an ontology access error occurs.
*/
@Override
void close() throws OntoDriverException;
/**
* Retrieves status of this result set.
*
* @return {@code true} if the resource is open, {@code false} otherwise
*/
boolean isOpen();
/**
* Creates a {@link Iterator} over this result set.
* <p>
* Note that the iterator does not close this result set after finishing its iteration. The result has to be closed by the caller.
*
* @return Iterator over this result set
*/
@Override
default Iterator<ResultRow> iterator() {
if (!isOpen()) {
throw new IllegalStateException("The result set is closed.");
}
return new ResultSetIterator(this);
}
/**
* Creates a {@link Spliterator} over this result set.
* <p>
* Note that the spliterator does not close this result set after finishing its iteration. The result has to be closed by the caller.
*
* @return Spliterator over this result set
*/
@Override
default Spliterator<ResultRow> spliterator() {
if (!isOpen()) {
throw new IllegalStateException("The result set is closed.");
}
return new ResultSetSpliterator(this);
}
/**
* Creates a sequential {@link Stream} over this result set.
* <p>
* The default implementation creates a stream using the default {@link #spliterator()}.
* <p>
* Note that the stream does not close this result set after finishing its iteration. The result set has to be closed by the caller.
*
* @return A {@code Stream} over this result set.
*/
default Stream<ResultRow> stream() {
return StreamSupport.stream(spliterator(), false);
}
}