001: package org.mandarax.kernel;
002:
003: /**
004: * Copyright (C) 1999-2004 <A href="http://www-ist.massey.ac.nz/JBDietrich" target="_top">Jens Dietrich</a>
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation; either
009: * version 2 of the License, or (at your option) any later version.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: *
016: * You should have received a copy of the GNU Lesser General Public
017: * License along with this library; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
019: */
020:
021: import java.io.Serializable;
022: import java.util.List;
023: import java.util.Map;
024:
025: /**
026: * Represents the result set of a query. A result set is very similar to an SQL result set:
027: * it provides a cursor for the results, and values from the current cursor position can be fetched.
028: * @see java.sql.ResultSet
029: * @author <A href="http://www-ist.massey.ac.nz/JBDietrich" target="_top">Jens Dietrich</A>
030: * @version 3.4 <7 March 05>
031: * @since 1.7
032: */
033: public interface ResultSet extends Serializable {
034: /**
035: * Moves the cursor to the first row in this ResultSet object.
036: * @return true if the cursor is on a valid row; false if there are no rows in the result set
037: * @exception an inference exception
038: */
039: public boolean first() throws InferenceException;
040:
041: /**
042: * Moves the cursor to the last row in this ResultSet object.
043: * @return true if the cursor is on a valid row; false if there are no rows in the result set
044: * @exception an inference exception
045: */
046: public boolean last() throws InferenceException;
047:
048: /**
049: * Retrieves the current result number. The first row is number 1, the second number 2, and so on.
050: * @return a number
051: * @exception an inference exception
052: */
053: public int getResultNumber() throws InferenceException;
054:
055: /**
056: * Moves the cursor down one row from its current position. A ResultSet cursor is initially positioned
057: * before the first row; the first call to the method next makes the first row the current row;
058: * the second call makes the second row the current row, and so on.
059: * @return true if the new current row is valid; false if there are no more rows
060: * @exception an inference exception
061: */
062: public boolean next() throws InferenceException;
063:
064: /**
065: * Moves the cursor to the previous row in this ResultSet object.
066: * @return true if the cursor is on a valid row; false if it is off the result set
067: * @exception an inference exception
068: */
069: public boolean previous() throws InferenceException;
070:
071: /**
072: * Releases this ResultSet resources.
073: * E.g., database resources associated with SQLClauseSets can be released here.
074: * @exception an inference exception
075: */
076: public void close() throws InferenceException;
077:
078: /**
079: * Get the derivation of the current result.
080: * Throw an exception if the cursor is not positioned at a result.
081: * @return the proof (derivation)
082: * @exception an inference exception
083: */
084: public Derivation getProof() throws InferenceException;
085:
086: /**
087: * Get the object that replaces the variable with the given name and type.
088: * Throw an exception if the cursor is not positioned at a result.
089: * @return the object that replaced the variable
090: * @param type the type of the variable
091: * @param name the name of the variable
092: * @exception an inference exception
093: */
094: public Object getResult(Class type, String name)
095: throws InferenceException;
096:
097: /**
098: * Get the object that replaces the variable.
099: * Throw an exception if the cursor is not positioned at a result.
100: * @return the object that replaced the variable
101: * @param term the variable term that is (perhaps) replaced
102: * @exception an inference exception
103: */
104: public Object getResult(VariableTerm term)
105: throws InferenceException;
106:
107: /**
108: * Get a list of all variable terms in the query.
109: * @return a list of variable terms
110: * @exception an inference exception
111: */
112: public List getQueryVariables() throws InferenceException;
113:
114: /**
115: * Get the current position of the cursor
116: * Should return -1 if next has never been called
117: * @return an integer
118: */
119: public int getCursorPosition() throws InferenceException;
120:
121: /**
122: * Indicates whether the cursor is at the first position.
123: * @return a boolean
124: */
125: public boolean isFirst() throws InferenceException;
126:
127: /**
128: * Indicates whether the cursor is at the last position.
129: * @return a boolean
130: */
131: public boolean isLast() throws InferenceException;
132:
133: /**
134: * Moves the cursor a relative number of results, either positive or negative.
135: * @param offset the number of results
136: * @return true if the cursor is on the result set; false otherwise.
137: */
138: public boolean relative(int offset) throws InferenceException;
139:
140: /**
141: * Moves the cursor to the given result number.
142: * @param resultNo the number of results.
143: * @return true if the cursor is on the result set; false otherwise
144: */
145: public boolean absolute(int resultNo) throws InferenceException;
146:
147: /**
148: * Moves the cursor to the front of this ResultSet object, just before the first row.
149: * This method has no effect if the result set contains no rows.
150: */
151: public void beforeFirst() throws InferenceException;
152:
153: /**
154: * Moves the cursor to the end of this ResultSet object, just after the last row.
155: * This method has no effect if the result set contains no rows.
156: */
157: public void afterLast() throws InferenceException;
158:
159: /**
160: * Retrieves whether the cursor is before the first row in this ResultSet object.
161: * @return true if the cursor is before the first row; false if the cursor is at any other position or the result set contains no rows
162: */
163: public boolean isBeforeFirst() throws InferenceException;
164:
165: /**
166: * Retrieves whether the cursor is after the last result in this ResultSet object.
167: * @return true if the cursor is after the last result; false if the cursor is at any other position or the result set contains no results
168: */
169: public boolean isAfterLast() throws InferenceException;
170:
171: /**
172: * Get the replacements as map (term -> term associations).
173: * @return a map
174: */
175: public Map getResults() throws InferenceException;
176: }
|