001: package com.quadcap.sql;
002:
003: /* Copyright 1999 - 2003 Quadcap Software. All rights reserved.
004: *
005: * This software is distributed under the Quadcap Free Software License.
006: * This software may be used or modified for any purpose, personal or
007: * commercial. Open Source redistributions are permitted. Commercial
008: * redistribution of larger works derived from, or works which bundle
009: * this software requires a "Commercial Redistribution License"; see
010: * http://www.quadcap.com/purchase.
011: *
012: * Redistributions qualify as "Open Source" under one of the following terms:
013: *
014: * Redistributions are made at no charge beyond the reasonable cost of
015: * materials and delivery.
016: *
017: * Redistributions are accompanied by a copy of the Source Code or by an
018: * irrevocable offer to provide a copy of the Source Code for up to three
019: * years at the cost of materials and delivery. Such redistributions
020: * must allow further use, modification, and redistribution of the Source
021: * Code under substantially the same terms as this license.
022: *
023: * Redistributions of source code must retain the copyright notices as they
024: * appear in each source code file, these license terms, and the
025: * disclaimer/limitation of liability set forth as paragraph 6 below.
026: *
027: * Redistributions in binary form must reproduce this Copyright Notice,
028: * these license terms, and the disclaimer/limitation of liability set
029: * forth as paragraph 6 below, in the documentation and/or other materials
030: * provided with the distribution.
031: *
032: * The Software is provided on an "AS IS" basis. No warranty is
033: * provided that the Software is free of defects, or fit for a
034: * particular purpose.
035: *
036: * Limitation of Liability. Quadcap Software shall not be liable
037: * for any damages suffered by the Licensee or any third party resulting
038: * from use of the Software.
039: */
040:
041: import java.io.IOException;
042:
043: import java.util.Vector;
044:
045: import java.sql.SQLException;
046:
047: /**
048: * The base cursor interface.
049: *
050: * @author Stan Bailes
051: */
052: public interface Cursor extends Tuple {
053: // ---------------------- Row accessors
054: /**
055: * Return the cursor's current row
056: */
057: public Row getRow() throws SQLException;
058:
059: /**
060: * Insert the specified row into the cursor's underlying table
061: */
062: public void insertRow(Row row) throws SQLException;
063:
064: /**
065: * Replace the current cursor row with the specified row
066: */
067: public void updateRow(Row row) throws SQLException;
068:
069: /**
070: * Delete the current cursor row
071: */
072: public void deleteRow() throws SQLException;
073:
074: /**
075: * Some cursors have rows where the rows can be identified by row
076: * id, and sometimes the cursors even know the row id for the
077: * current row. If you know, tell us here! If you don't know,
078: * just return 0.
079: */
080: public long getRowId();
081:
082: // ---------------------- Movement
083: /**
084: * Position the cursor before the first row
085: */
086: public void beforeFirst() throws SQLException;
087:
088: /**
089: * Position the cursor after the last row.
090: */
091: public void afterLast() throws SQLException;
092:
093: /**
094: * Move to the specified absolute row. The first row is '1'.
095: * absolute(-1) moves to the last row. absolute(0) throws an
096: * exception.
097: *
098: * @param row if > 0 the (one-based) row number else negative
099: * offset from last row in cursor.
100: * @return <b>true</b> if the specified row can be successfully
101: * positioned.
102: */
103: public boolean absolute(int row) throws SQLException;
104:
105: /**
106: * Advance the cursor and return true if we advanced to a valid row
107: */
108: public boolean next() throws SQLException;
109:
110: /**
111: * Move the cursor back one row and return true if we moved back
112: * to a valid row.
113: */
114: public boolean prev() throws SQLException;
115:
116: /**
117: * Close the cursor and free up any resources (including closing
118: * the cursor's transaction if that is feasible) used by the cursor.
119: *
120: * @exception SQLException may be thrown
121: */
122: public void close() throws SQLException;
123:
124: // ---------------------- Accessors
125:
126: /**
127: * If the underlying implementation knows, or can compute cheaply,
128: * the actual size of the ResultSet, it should return a non-negative
129: * number here. If the size is unknown and it would be expensive to
130: * compute it (i.e., on the order of <code>while next()) size++</code>),
131: * then the implementation should return -1
132: */
133: public long size() throws SQLException;
134:
135: /**
136: * Return <b>true</b> if the specified column is writable.
137: *
138: * @param column the (one-based) column number
139: * @exception SQLException may be thrown
140: */
141: public boolean isWritable(int column) throws SQLException;
142:
143: /**
144: * Return the cursor in the enclosing context (this applies if we're
145: * in a sub-query, for example)
146: */
147: public Cursor getOuterCursor();
148:
149: /**
150: * Set the cursor context in which this subquery is executing
151: *
152: * @param outer the cursor from the outer context
153: */
154: public void setOuterCursor(Cursor outer);
155:
156: /**
157: * Return the cursor's session
158: */
159: public Session getSession();
160:
161: /**
162: * Some cursors are, or can be viewed as, tables. If your cursor
163: * is such a type, return your table here, otherwise simply return
164: * null.
165: */
166: public Table getTable();
167:
168: /**
169: * An attempt at an API to allow cursor reuse.
170: */
171: public void reset(Expression where, Cursor outer)
172: throws SQLException;
173: }
|