Quadcap Embeddable Database

com/quadcap/sql/Cursor.java

Go to the documentation of this file.

package com.quadcap.sql;

/* Copyright 1999 - 2003 Quadcap Software.  All rights reserved.
 *
 * This software is distributed under the Quadcap Free Software License.
 * This software may be used or modified for any purpose, personal or
 * commercial.  Open Source redistributions are permitted.  Commercial
 * redistribution of larger works derived from, or works which bundle
 * this software requires a "Commercial Redistribution License"; see
 * http://www.quadcap.com/purchase.
 *
 * Redistributions qualify as "Open Source" under  one of the following terms:
 *   
 *    Redistributions are made at no charge beyond the reasonable cost of
 *    materials and delivery.
 *
 *    Redistributions are accompanied by a copy of the Source Code or by an
 *    irrevocable offer to provide a copy of the Source Code for up to three
 *    years at the cost of materials and delivery.  Such redistributions
 *    must allow further use, modification, and redistribution of the Source
 *    Code under substantially the same terms as this license.
 *
 * Redistributions of source code must retain the copyright notices as they
 * appear in each source code file, these license terms, and the
 * disclaimer/limitation of liability set forth as paragraph 6 below.
 *
 * Redistributions in binary form must reproduce this Copyright Notice,
 * these license terms, and the disclaimer/limitation of liability set
 * forth as paragraph 6 below, in the documentation and/or other materials
 * provided with the distribution.
 *
 * The Software is provided on an "AS IS" basis.  No warranty is
 * provided that the Software is free of defects, or fit for a
 * particular purpose.  
 *
 * Limitation of Liability. Quadcap Software shall not be liable
 * for any damages suffered by the Licensee or any third party resulting
 * from use of the Software.
 */

import java.io.IOException;

import java.util.Vector;

import java.sql.SQLException;

/**
 * The base cursor interface.
 *
 * @author Stan Bailes
 */
public interface Cursor extends Tuple {
    // ---------------------- Row accessors
    /**
     * Return the cursor's current row
     */
    public Row getRow() throws SQLException;

    /**
     * Insert the specified row into the cursor's underlying table
     */
    public void insertRow(Row row) throws SQLException;

    /**
     * Replace the current cursor row with the specified row
     */
    public void updateRow(Row row) throws SQLException;

    /**
     * Delete the current cursor row
     */
    public void deleteRow() throws SQLException;

    /**
     * Some cursors have rows where the rows can be identified by row
     * id, and sometimes the cursors even know the row id for the
     * current row.   If you know, tell us here!  If you don't know,
     * just return 0.
     */     
    public long getRowId();


    // ---------------------- Movement
    /**
     * Position the cursor before the first row
     */
    public void beforeFirst() throws SQLException;

    /**
     * Position the cursor after the last row.
     */
    public void afterLast() throws SQLException;

    /**
     * Move to the specified absolute row.  The first row is '1'.
     * absolute(-1) moves to the last row.  absolute(0) throws an
     * exception.
     *
     * @param row if > 0 the (one-based) row number else negative
     *          offset from last row in cursor.
     * @return <b>true</b> if the specified row can be successfully
     * positioned.
     */
    public boolean absolute(int row) throws SQLException;

    /**
     * Advance the cursor and return true if we advanced to a valid row
     */
    public boolean next() throws SQLException;

    /**
     * Move the cursor back one row and return true if we moved back
     * to a valid row.
     */
    public boolean prev() throws SQLException;

    /**
     * Close the cursor and free up any resources (including closing
     * the cursor's transaction if that is feasible) used by the cursor.
     *
     * @exception SQLException may be thrown
     */
    public void close() throws SQLException;

    // ---------------------- Accessors

    /**
     * If the underlying implementation knows, or can compute cheaply,
     * the actual size of the ResultSet, it should return a non-negative
     * number here.  If the size is unknown and it would be expensive to
     * compute it (i.e., on the order of <code>while next()) size++</code>),
     * then the implementation should return -1
     */
    public long size() throws SQLException;

    /**
     * Return <b>true</b> if the specified column is writable.
     *
     * @param column the (one-based) column number
     * @exception SQLException may be thrown
     */
    public boolean isWritable(int column) throws SQLException;

    /**
     * Return the cursor in the enclosing context (this applies if we're
     * in a sub-query, for example)
     */
    public Cursor getOuterCursor();

    /**
     * Set the cursor context in which this subquery is executing
     *
     * @param outer the cursor from the outer context
     */
    public void setOuterCursor(Cursor outer);

    /**
     * Return the cursor's session
     */
    public Session getSession();

    /**
     * Some cursors are, or can be viewed as, tables.  If your cursor
     * is such a type, return your table here, otherwise simply return
     * null.
     */
    public Table getTable();

    /**
     * An attempt at an API to allow cursor reuse.
     */
    public void reset(Expression where, Cursor outer) throws SQLException;
}