package ModSQL;

/* $Id: DatabaseTableBase.java,v 1.5 2004/01/04 01:41:25 cvs Exp $
 *
 * Copyright (c) 2004 Chris Studholme <chris.studholme@utoronto.ca>
 *
 * May be copied or modified under the terms of the GNU General Public
 * License.  See COPYING for more information.
 */

/**
 * <p>Base interface for DatabaseTable and DatabaseIndex.  This interface is
 * not intended to be implemented directly.
 *
 * @see DatabaseManager
 * @author chris.studholme@utoronto.ca
 */
public interface DatabaseTableBase {

  /**
   * <p>In some cases, it is desirable to immediately release a
   * DatabaseTable's database and other resources instead of waiting for
   * this to happen when it is automatically closed; the close
   * method provides this immediate release.
   *
   * <p><b>Note:</b> A DatabaseTable is automatically closed by the
   * Statement that generated it when that Statement is closed,
   * re-executed, or is used to retrieve the next result from a
   * sequence of multiple results. A DatabaseTable is also automatically
   * closed when it is garbage collected.  
   *
   * @throws DatabaseException if a database-access error occurs
   */
  public void close() throws DatabaseException;

  /** 
   * This method is expected to return the total number of rows in the
   * database.  This value is used by ModSQL for query optimization purposes.
   * If the count cannot be easily determined, the database should return -1
   * to indicate that the count is unknown.
   *
   * @return number of rows in table, or -1 for unknown
   * @throws DatabaseException if a database-access error occurs
   */
  public long getRowCount() throws DatabaseException;

  /**
   * A DatabaseTable is initially positioned before its first row; the
   * first call to next makes the first row the current row; the
   * second call makes the second row the current row, etc. 
   *
   * @return true if the new current row is valid; false if there
   * are no more rows 
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean next() throws DatabaseException;

  /**
   * Determine if the table cursor is positioned before the first row
   * in the table.
   *
   * @return true if before the first row, false otherwise
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean isBeforeFirst() throws DatabaseException;
  
  /**
   * Determine if the table cursor is positioned after the last row
   * in the table.
   *
   * @return true if after the last row, false otherwise
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean isAfterLast() throws DatabaseException;

  /**
   * Moves the table cursor to a position before the first row in
   * the table.  The next call to next() will set the cursor to the
   * first row in the table (assuming the table has at least one row).
   *
   * @throws DatabaseException if a database-access error occurs
   */
  public void beforeFirst() throws DatabaseException;
  
  /**
   * Moves the table cursor to a position after the last row in the
   * table.  All calls to next() will return false until beforeFirst()
   * is called to reset the table.
   *
   * @throws DatabaseException if a database-access error occurs
   */
  public void afterLast() throws DatabaseException;
  
  /**
   * Get database specific rowid value.  This value can be later used
   * with absolute() to seek to a specific row.
   *
   * @return object representing current row, or null if no current row
   * @throws DatabaseException if a database-access error occurs
   */
  public Object getRowId() throws DatabaseException;

  /**
   * <p>Get the value of a column in the current row as a Java object.
   *
   * <p>This method will return the value of the given column as a
   * Java object.  The type of the Java object will be the default
   * Java Object type corresponding to the column's SQL type,
   * following the mapping specified in the JDBC spec.
   *
   * <p>This method may also be used to read datatabase specific abstract
   * data types.
   *
   * @param column the first column is 1, the second is 2, ...
   * @return an Object holding the column value
   * @throws DatabaseException if a database-access error occurs
   */
  public Object getObject(int column) throws DatabaseException;

  /**
   * <p>Update a column with an Object value.
   *
   * <p>The updateObject() method is used to update column values in the
   * current row, or a newly inserted row.  
   *
   * @param column the first column is 1, the second is 2, ...
   * @param x the new column value
   * @throws DatabaseException if a database-access error occurs
   */
  public void updateObject(int column, Object x) throws DatabaseException;

  /**
   * ModSQL will always call this method after performing a series of
   * updateObject() calls on a particular row.  If this call is not received
   * before the row is changed or the table is closed, the changes made by
   * updateObject() should be discarded.  In the case where addRow() was called
   * before the updateObject() calls, the new row can be discarded as well.
   *
   * @throws DatabaseException if a database-access error occurs
   */
  public void commitUpdates() throws DatabaseException;

  /**
   * Delete the current row from the table and the underlying
   * database.  Cannot be called when on a newly inserted row.
   *
   * @throws DatabaseException if a database-access error occurs
   */
  public void deleteRow() throws DatabaseException;
  
};