Package: ResultSet

ResultSet

Coverage

1: /**
2: * Copyright (C) 2016 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:
19: import java.util.NoSuchElementException;
20: import java.util.Observer;
21:
22: /**
23: * Represents a set of results of a SPARQL query.
24: * <p>
25: * This interface declares methods for getting values from a set of results of a SPARQL query issued to an ontology.
26: */
27: public interface ResultSet extends AutoCloseable {
28:
29: /**
30: * Retrieves index of a column with the specified label.
31: *
32: * @param columnLabel Label of the column
33: * @return index of the column or -1 if there is no such column
34: * @throws IllegalStateException If called on a closed result set
35: */
36: int findColumn(String columnLabel);
37:
38: /**
39: * Gets the count of available columns.
40: * <p>
41: * This number corresponds to the number of result variables bound in the query.
42: *
43: * @return Number of columns in the result set
44: * @throws IllegalStateException If called on a closed result set
45: */
46: int getColumnCount();
47:
48: /**
49: * Move the cursor to the first row.
50: *
51: * @throws IllegalStateException If called on a closed result set
52: * @throws OntoDriverException If some other error occurs
53: */
54: void first() throws OntoDriverException;
55:
56: /**
57: * Retrieves value from column at the specified index and returns it as a {@code boolean}.
58: *
59: * @param columnIndex Column index, the first column has index 0
60: * @return {@code boolean} value
61: * @throws IllegalStateException If called on a closed result set
62: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
63: * {@code boolean} or there occurs some other error
64: */
65: boolean getBoolean(int columnIndex) throws OntoDriverException;
66:
67: /**
68: * Retrieves value from column with the specified label and returns it as a {@code boolean}.
69: *
70: * @param columnLabel Label of the column
71: * @return {@code boolean} value
72: * @throws IllegalStateException If called on a closed result set
73: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
74: * boolean} or there occurs some other error
75: */
76: boolean getBoolean(String columnLabel) throws OntoDriverException;
77:
78: /**
79: * Retrieves value from column at the specified index and returns it as {@code byte}.
80: *
81: * @param columnIndex Column index, the first column has index 0
82: * @return {@code byte} value
83: * @throws IllegalStateException If called on a closed result set
84: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
85: * {@code byte} or there occurs some other error
86: */
87: byte getByte(int columnIndex) throws OntoDriverException;
88:
89: /**
90: * Retrieves value from column with the specified label and returns it as {@code byte}.
91: *
92: * @param columnLabel Label of the column
93: * @return {@code byte} value
94: * @throws IllegalStateException If called on a closed result set
95: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
96: * byte} or there occurs some other error
97: */
98: byte getByte(String columnLabel) throws OntoDriverException;
99:
100: /**
101: * Retrieves value from column at the specified index and returns it as {@code double}.
102: *
103: * @param columnIndex Column index, the first column has index 0
104: * @return {@code double} value
105: * @throws IllegalStateException If called on a closed result set
106: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
107: * {@code double} or there occurs some other error
108: */
109: double getDouble(int columnIndex) throws OntoDriverException;
110:
111: /**
112: * Retrieves value from column with the specified label and returns it as {@code double}.
113: *
114: * @param columnLabel Label of the column
115: * @return {@code double} value
116: * @throws IllegalStateException If called on a closed result set
117: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
118: * double} or there occurs some other error
119: */
120: double getDouble(String columnLabel) throws OntoDriverException;
121:
122: /**
123: * Retrieves value from column at the specified index and returns it as {@code float}.
124: *
125: * @param columnIndex Column index, the first column has index 0
126: * @return {@code float} value
127: * @throws IllegalStateException If called on a closed result set
128: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
129: * {@code float} or there occurs some other error
130: */
131: float getFloat(int columnIndex) throws OntoDriverException;
132:
133: /**
134: * Retrieves value from column with the specified label and returns it as {@code float}.
135: *
136: * @param columnLabel Label of the column
137: * @return {@code float} value
138: * @throws IllegalStateException If called on a closed result set
139: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
140: * float} or there occurs some other error
141: */
142: float getFloat(String columnLabel) throws OntoDriverException;
143:
144: /**
145: * Retrieves value from column at the specified index and returns it as {@code int}.
146: *
147: * @param columnIndex Column index, the first column has index 0
148: * @return {@code int} value
149: * @throws IllegalStateException If called on a closed result set
150: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
151: * {@code int} or there occurs some other error
152: */
153: int getInt(int columnIndex) throws OntoDriverException;
154:
155: /**
156: * Retrieves value from column with the specified label and returns it as {@code int}.
157: *
158: * @param columnLabel Label of the column
159: * @return {@code int} value
160: * @throws IllegalStateException If called on a closed result set
161: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
162: * int} or there occurs some other error
163: */
164: int getInt(String columnLabel) throws OntoDriverException;
165:
166: /**
167: * Retrieves value from column at the specified index and returns it as {@code long}.
168: *
169: * @param columnIndex Column index, the first column has index 0
170: * @return {@code long} value
171: * @throws IllegalStateException If called on a closed result set
172: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
173: * {@code long} or there occurs some other error
174: */
175: long getLong(int columnIndex) throws OntoDriverException;
176:
177: /**
178: * Retrieves value from column with the specified label and returns it as {@code long}.
179: *
180: * @param columnLabel Label of the column
181: * @return {@code long} value
182: * @throws IllegalStateException If called on a closed result set
183: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
184: * long} or there occurs some other error
185: */
186: long getLong(String columnLabel) throws OntoDriverException;
187:
188: /**
189: * Retrieves value from column at the specified index and returns it as {@code Object}.
190: *
191: * @param columnIndex Column index, the first column has index 0
192: * @return column value cast to {@code Object}
193: * @throws IllegalStateException If called on a closed result set
194: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index or there occurs some other
195: * error
196: */
197: Object getObject(int columnIndex) throws OntoDriverException;
198:
199: /**
200: * Retrieves value from column with the specified label and returns it as {@code Object}.
201: *
202: * @param columnLabel Label of the column
203: * @return column value cast to {@code Object}
204: * @throws IllegalStateException If called on a closed result set
205: * @throws OntoDriverException If there is no column with the specified label or there occurs some other error
206: */
207: Object getObject(String columnLabel) throws OntoDriverException;
208:
209: /**
210: * Retrieves value from column at the specified index and returns it as an instance of the specified class.
211: * <p>
212: * The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
213: * calling a constructor of the specified type.
214: *
215: * @param columnIndex Column index, the first column has index 0
216: * @param cls Requested class type
217: * @param <T> Return type
218: * @return Value of the column
219: * @throws IllegalStateException If called on a closed result set
220: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
221: * the specified type or there occurs some other error
222: */
223: <T> T getObject(int columnIndex, Class<T> cls) throws OntoDriverException;
224:
225: /**
226: * Retrieves value from column with the specified label and returns it as an instance of the specified class.
227: * <p>
228: * The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
229: * calling a constructor of the specified type.
230: *
231: * @param columnLabel Label of the column
232: * @param cls Requested class type
233: * @param <T> Return type
234: * @return Value of the column.
235: * @throws IllegalStateException If called on a closed result set
236: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to the
237: * specified type or there occurs some other error
238: */
239: <T> T getObject(String columnLabel, Class<T> cls) throws OntoDriverException;
240:
241: /**
242: * Retrieves index of the current row.
243: * <p>
244: * The first row has index 0.
245: *
246: * @return the current row index, -1 if there is no current row
247: * @throws IllegalStateException If called on a closed result set
248: * @throws OntoDriverException If some other error occurs
249: */
250: int getRowIndex() throws OntoDriverException;
251:
252: /**
253: * Retrieves value of column at the specified index and returns it as {@code short}.
254: *
255: * @param columnIndex Column index, the first column has index 0
256: * @return {@code short} value
257: * @throws IllegalStateException If called on a closed result set
258: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
259: * {@code short} or there occurs some other error
260: */
261: short getShort(int columnIndex) throws OntoDriverException;
262:
263: /**
264: * Retrieves value of column with the specified label and returns it as {@code short}.
265: *
266: * @param columnLabel Label of the column
267: * @return {@code short} value
268: * @throws IllegalStateException If called on a closed result set
269: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
270: * short} or there occurs some other error
271: */
272: short getShort(String columnLabel) throws OntoDriverException;
273:
274: /**
275: * Retrieves the {@code Statement} that produced this {@code ResultSet} object. If this result set was generated
276: * some other way, this method will return {@code null}.
277: *
278: * @return The {@code Statement} that produced this {@code ResultSet} or null
279: * @throws IllegalStateException If called on a closed result set
280: * @throws OntoDriverException If some other error occurs
281: */
282: Statement getStatement() throws OntoDriverException;
283:
284: /**
285: * Retrieves value of column at the specified index and returns it as {@code String}.
286: *
287: * @param columnIndex Column index, the first column has index 0
288: * @return {@code String} value
289: * @throws IllegalStateException If called on a closed result set
290: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
291: * {@code String} or there occurs some other error
292: */
293: String getString(int columnIndex) throws OntoDriverException;
294:
295: /**
296: * Retrieves value of column with the specified label and returns it as {@code String}.
297: *
298: * @param columnLabel Label of the column
299: * @return {@code String} value
300: * @throws IllegalStateException If called on a closed result set
301: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
302: * String} or there occurs some other error
303: */
304: String getString(String columnLabel) throws OntoDriverException;
305:
306: /**
307: * Returns true if the cursor is at the first row of this result set.
308: *
309: * @return True if the cursor is at the first row, false otherwise
310: * @throws IllegalStateException If called on a closed result set
311: * @throws OntoDriverException If some other error occurs
312: */
313: boolean isFirst() throws OntoDriverException;
314:
315: /**
316: * Returns true if the cursor does not point at the last row in this result set.
317: *
318: * @return True if there is at least one next row
319: * @throws IllegalStateException If called on a closed result set
320: * @throws OntoDriverException If some other error occurs
321: */
322: boolean hasNext() throws OntoDriverException;
323:
324: /**
325: * Move the cursor to the last row in this results set.
326: * <p>
327: * Note that since the result set may be asynchronously updated, the last row does not have to always be the same.
328: *
329: * @throws IllegalStateException If called on a closed result set
330: * @throws OntoDriverException If some other error occurs
331: */
332: void last() throws OntoDriverException;
333:
334: /**
335: * Move the cursor one row forward.
336: *
337: * @throws NoSuchElementException If there are no more elements
338: * @throws IllegalStateException If called on a closed result set
339: * @throws OntoDriverException If some other error occurs
340: */
341: void next() throws OntoDriverException;
342:
343: /**
344: * Move the cursor one row backwards.
345: *
346: * @throws IllegalStateException If called on a closed result set or the cursor is at the first row
347: * @throws OntoDriverException If some other error occurs
348: */
349: void previous() throws OntoDriverException;
350:
351: /**
352: * Registers the specified {@code Observer} at this result set.
353: * <p>
354: * The observer is notified whenever new results of ontology reasoning are available.
355: *
356: * @param observer The observer to register
357: * @throws IllegalStateException If called on a closed result set
358: * @throws OntoDriverException If or some other error occurs
359: */
360: void registerObserver(Observer observer) throws OntoDriverException;
361:
362: /**
363: * Move the cursor a relative number of rows, either positive or negative.
364: *
365: * @param rows The number of rows to move the cursor of
366: * @throws IllegalStateException If called on a closed result set
367: * @throws OntoDriverException If the {@code rows} number is not valid or some other error occurs
368: */
369: void relative(int rows) throws OntoDriverException;
370:
371: /**
372: * Move the cursor to the specified row index.
373: * <p>
374: * The first row has index 0.
375: *
376: * @param rowIndex Index to move the cursor to
377: * @throws IllegalStateException If called on a closed result set
378: * @throws OntoDriverException If the index is not valid row index or some other error occurs
379: */
380: void setRowIndex(int rowIndex) throws OntoDriverException;
381:
382: /**
383: * Closes this result set releasing any sub-resources it holds.
384: * <p>
385: * After closing the result set is not usable any more and calling methods on it (except {@code close} and {@code
386: * isOpen}) will result in {@code OntoDriverException}.
387: * <p>
388: * Calling {@code close} on already closed resource does nothing.
389: * <p>
390: * Calling this method also results in immediate disconnection of all registered observers and cancellation of any
391: * running reasoning associated with this result set.
392: *
393: * @throws OntoDriverException If an ontology access error occurs.
394: */
395: @Override
396: void close() throws OntoDriverException;
397:
398: /**
399: * Retrieves status of this result set.
400: *
401: * @return {@code true} if the resource is open, {@code false} otherwise
402: */
403: boolean isOpen();
404: }