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. </p>
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: * @author kidney
28: */
29: public interface ResultSet extends AutoCloseable {
30:
31: /**
32: * Retrieves index of a column with the specified label.
33: *
34: * @param columnLabel Label of the column
35: * @return index of the column or -1 if there is no such column
36: * @throws IllegalStateException If called on a closed result set
37: */
38: public int findColumn(String columnLabel);
39:
40: /**
41: * Gets the count of available columns. </p>
42: * <p>
43: * This number corresponds to the number of result variables bound in the query.
44: *
45: * @return Number of columns in the result set
46: * @throws IllegalStateException If called on a closed result set
47: */
48: public int getColumnCount();
49:
50: /**
51: * Move the cursor to the first row.
52: *
53: * @throws IllegalStateException If called on a closed result set
54: * @throws OntoDriverException If some other error occurs
55: */
56: public void first() throws OntoDriverException;
57:
58: /**
59: * Retrieves value from column at the specified index and returns it as a {@code boolean}.
60: *
61: * @param columnIndex Column index, the first column has index 0
62: * @return {@code boolean} value
63: * @throws IllegalStateException If called on a closed result set
64: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
65: * {@code boolean} or there occurs some other error
66: */
67: public boolean getBoolean(int columnIndex) throws OntoDriverException;
68:
69: /**
70: * Retrieves value from column with the specified label and returns it as a {@code boolean}.
71: *
72: * @param columnLabel Label of the column
73: * @return {@code boolean} value
74: * @throws IllegalStateException If called on a closed result set
75: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
76: * boolean} or there occurs some other error
77: */
78: public boolean getBoolean(String columnLabel) throws OntoDriverException;
79:
80: /**
81: * Retrieves value from column at the specified index and returns it as {@code byte}.
82: *
83: * @param columnIndex Column index, the first column has index 0
84: * @return {@code byte} value
85: * @throws IllegalStateException If called on a closed result set
86: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
87: * {@code byte} or there occurs some other error
88: */
89: public byte getByte(int columnIndex) throws OntoDriverException;
90:
91: /**
92: * Retrieves value from column with the specified label and returns it as {@code byte}.
93: *
94: * @param columnLabel Label of the column
95: * @return {@code byte} value
96: * @throws IllegalStateException If called on a closed result set
97: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
98: * byte} or there occurs some other error
99: */
100: public byte getByte(String columnLabel) throws OntoDriverException;
101:
102: /**
103: * Retrieves value from column at the specified index and returns it as {@code double}.
104: *
105: * @param columnIndex Column index, the first column has index 0
106: * @return {@code double} value
107: * @throws IllegalStateException If called on a closed result set
108: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
109: * {@code double} or there occurs some other error
110: */
111: public double getDouble(int columnIndex) throws OntoDriverException;
112:
113: /**
114: * Retrieves value from column with the specified label and returns it as {@code double}.
115: *
116: * @param columnLabel Label of the column
117: * @return {@code double} value
118: * @throws IllegalStateException If called on a closed result set
119: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
120: * double} or there occurs some other error
121: */
122: public double getDouble(String columnLabel) throws OntoDriverException;
123:
124: /**
125: * Retrieves value from column at the specified index and returns it as {@code float}.
126: *
127: * @param columnIndex Column index, the first column has index 0
128: * @return {@code float} value
129: * @throws IllegalStateException If called on a closed result set
130: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
131: * {@code float} or there occurs some other error
132: */
133: public float getFloat(int columnIndex) throws OntoDriverException;
134:
135: /**
136: * Retrieves value from column with the specified label and returns it as {@code float}.
137: *
138: * @param columnLabel Label of the column
139: * @return {@code float} value
140: * @throws IllegalStateException If called on a closed result set
141: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
142: * float} or there occurs some other error
143: */
144: public float getFloat(String columnLabel) throws OntoDriverException;
145:
146: /**
147: * Retrieves value from column at the specified index and returns it as {@code int}.
148: *
149: * @param columnIndex Column index, the first column has index 0
150: * @return {@code int} value
151: * @throws IllegalStateException If called on a closed result set
152: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
153: * {@code int} or there occurs some other error
154: */
155: public int getInt(int columnIndex) throws OntoDriverException;
156:
157: /**
158: * Retrieves value from column with the specified label and returns it as {@code int}.
159: *
160: * @param columnLabel Label of the column
161: * @return {@code int} value
162: * @throws IllegalStateException If called on a closed result set
163: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
164: * int} or there occurs some other error
165: */
166: public int getInt(String columnLabel) throws OntoDriverException;
167:
168: /**
169: * Retrieves value from column at the specified index and returns it as {@code long}.
170: *
171: * @param columnIndex Column index, the first column has index 0
172: * @return {@code long} value
173: * @throws IllegalStateException If called on a closed result set
174: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
175: * {@code long} or there occurs some other error
176: */
177: public long getLong(int columnIndex) throws OntoDriverException;
178:
179: /**
180: * Retrieves value from column with the specified label and returns it as {@code long}.
181: *
182: * @param columnLabel Label of the column
183: * @return {@code long} value
184: * @throws IllegalStateException If called on a closed result set
185: * @throws OntoDriverException If there is no column with the specified label, the value cannot be cast to {@code
186: * long} or there occurs some other error
187: */
188: public long getLong(String columnLabel) throws OntoDriverException;
189:
190: /**
191: * Retrieves value from column at the specified index and returns it as {@code Object}.
192: *
193: * @param columnIndex Column index, the first column has index 0
194: * @return column value cast to {@code Object}
195: * @throws IllegalStateException If called on a closed result set
196: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index or there occurs some other
197: * error
198: */
199: public Object getObject(int columnIndex) throws OntoDriverException;
200:
201: /**
202: * Retrieves value from column with the specified label and returns it as {@code Object}.
203: *
204: * @param columnLabel Label of the column
205: * @return column value cast to {@code Object}
206: * @throws IllegalStateException If called on a closed result set
207: * @throws OntoDriverException If there is no column with the specified label or there occurs some other error
208: */
209: public Object getObject(String columnLabel) throws OntoDriverException;
210:
211: /**
212: * Retrieves value from column at the specified index and returns it as an instance of the specified class. </p>
213: * <p>
214: * The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
215: * calling a constructor of the specified type.
216: *
217: * @param columnIndex Column index, the first column has index 0
218: * @param cls Requested class type
219: * @return Value of the column
220: * @throws IllegalStateException If called on a closed result set
221: * @throws OntoDriverException If the {@code columnIndex} is not a valid column index, the value cannot be cast to
222: * the specified type or there occurs some other error
223: */
224: public <T> T getObject(int columnIndex, Class<T> cls) throws OntoDriverException;
225:
226: /**
227: * Retrieves value from column with the specified label and returns it as an instance of the specified class. </p>
228: * <p>
229: * The mechanism of transforming the value to the specified class is not specified, it can be merely type casting or
230: * calling a constructor of the specified type.
231: *
232: * @param columnLabel Label of the column
233: * @param cls Requested class 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: public <T> T getObject(String columnLabel, Class<T> cls) throws OntoDriverException;
240:
241: /**
242: * Retrieves index of the current row. </p>
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: public 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: public 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: public 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: public 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: public 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: public 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: public 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: public boolean hasNext() throws OntoDriverException;
323:
324: /**
325: * Move the cursor to the last row in this results set. </p>
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: public 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: public 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: public void previous() throws OntoDriverException;
350:
351: /**
352: * Registers the specified {@code Observer} at this result set. </p>
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: public 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: public void relative(int rows) throws OntoDriverException;
370:
371: /**
372: * Move the cursor to the specified row index. </p>
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: public void setRowIndex(int rowIndex) throws OntoDriverException;
381:
382: /**
383: * Closes this result set releasing any sub-resources it holds. </p>
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}. </p>
387: * <p>
388: * Calling {@code close} on already closed resource does nothing. </p>
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: public void close() throws OntoDriverException;
397:
398: /**
399: * Retrieves status of this result set. </p>
400: *
401: * @return {@code true} if the resource is open, {@code false} otherwise
402: */
403: public boolean isOpen();
404: }