package ModSQL;

/* $Id: DatabaseTable.java,v 1.8 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>Interface to be implemented by classes representing database tables.
 *
 * <p>To create a new type of database, you need to implement DatabaseTable
 * and DatabaseManager.  DatabaseManager creates DatabaseTable objects.
 *
 * @see DatabaseManager
 * @author chris.studholme@utoronto.ca
 */
public interface DatabaseTable extends DatabaseTableBase {

  /**
   * Returns an index on the specified column.
   *
   * @param column index of column to be indexed
   * @return new DatabaseIndex to use, or null if no index exists
   * @throws DatabaseException if a database-access error occurs
   */
  public DatabaseIndex openIndex(int column) 
    throws DatabaseException;

  /**
   * Determines if an index is available for the specified column.
   *
   * @param column index of column to be indexed
   * @return true if index is available, false otherwise
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean isIndexAvailable(int column)
    throws DatabaseException;

  /**
   * Is table read-only (ie. no update, insert or delete)?
   *
   * @return true if so
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean isReadOnly() 
    throws DatabaseException;

  /**
   * What's the table's name? 
   *
   * @return table name or "" if not applicable
   * @throws DatabaseException if a database-access error occurs
   */
  public String getTableName() 
    throws DatabaseException;

  /**
   * What's the number of columns in the DatabaseTable?
   *
   * @return the number
   * @throws DatabaseException if a database-access error occurs
   */
  public int getColumnCount() 
    throws DatabaseException;

  /**
   * Returns the size of the table in bytes.  This method may return an
   * approximation, or -1 is the size is not known.
   *
   * @return table size in bytes
   * @throws DatabaseException if a database-access error occurs
   */
  public long getTableSize() 
    throws DatabaseException;
   
  /**
   * <p>Calculates a unique signature for this table.  
   *
   * <p>The signature should depend on values of:<br><ul>
   *  <li>table size</li>
   *  <li>number of data files</li>
   *  <li>order of data files</li>
   *  <li>number of columns</li>
   *  <li>types and order of columns</li></ul>
   *
   * <p>Any change to the table that would invalidate an index should
   * also change the signature.  If this table will never be indexed,
   * this method may return 0.
   *
   * @return unique signature for table
   * @throws DatabaseException if a database-access error occurs
   */
  public long getTableSignature() 
    throws DatabaseException;


  /**
   * Map a DatabaseTable column name to a DatabaseTable column index.  Columns
   * should be sequentially numbered 1,2,3,etc.
   *
   * @param columnName the name of the column
   * @return the column index
   * @throws DatabaseException if a database-access error occurs
   */
  public int findColumn(String columnName) 
    throws DatabaseException;

  /**
   * What's the column's normal max width in chars?  If the column type is
   * not a string, or the maximum size is not known, this method may return
   * -1.
   *
   * @param column the first column is 1, the second is 2, ...
   * @return max width
   * @throws DatabaseException if a database-access error occurs
   */
  public int getColumnDisplaySize(int column) 
    throws DatabaseException;
  
  /**
   * What's the suggested column title for use in printouts and
   * displays?  In many cases this method should return the same value
   * as getColumnName() below.
   *
   * @param column the first column is 1, the second is 2, ...
   * @return true if so 
   * @throws DatabaseException if a database-access error occurs
   */
  public String getColumnLabel(int column) 
    throws DatabaseException;
  
  /**
   * What's a column's name?
   *
   * @param column the first column is 1, the second is 2, ...
   * @return column name
   * @throws DatabaseException if a database-access error occurs
   */
  public String getColumnName(int column) 
    throws DatabaseException;
  
  /**
   * What's a column's SQL type?
   *
   * @param column the first column is 1, the second is 2, ...
   * @return SQL type
   * @throws DatabaseException if a database-access error occurs
   * @see java.sql.Types
   */
  public int getColumnType(int column) 
    throws DatabaseException;
  
  /**
   * Add a new column to the table.
   *
   * @param name column name
   * @param type SQL type
   * @param maxlen length of data (varying columns only)
   * @throws DatabaseException if a database-access error occurs
   * @see java.sql.Types
   */
  public void addColumn(String name, int type, int maxlen) 
    throws DatabaseException;

  /**
   * Add a new row to the database.  This method creates a new row which
   * must have columns set using updateObject().
   *
   * @throws DatabaseException if a database-access error occurs
   */
  public void addRow() 
    throws DatabaseException;

  /**
   * Move to an absolute rowid in the table.
   *
   * @param rowid id of row to seek
   * @return true if row was found, false otherwise
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean absolute(Object rowid) 
    throws DatabaseException;
};