package ModSQL;

/* $Id: DatabaseIndex.java,v 1.4 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 table indices.
 *
 * <p>An implementation of DatabaseTable returns objects of this type
 * when requests are made to open an index on a specific column.  It is
 * possible for table classes to also implement DatabaseIndex and return
 * "this" when asked for a specific index.  ModSQL will never use more than
 * one index for a specific table at one time, nor will it access the table
 * through both an index and the table simultaneously.
 *
 * @see DatabaseTable
 * @author chris.studholme@utoronto.ca
 */
public interface DatabaseIndex extends DatabaseTableBase {

  /**
   * Returns the number of distinct values stored in the indexed column
   * in the underlying table.  This method may return an approximation.
   *
   * @return number of distinct values
   * @throws DatabaseException if a database-access error occurs
   */
  public long getDistinctCount() throws DatabaseException;

  /**
   * Returns the number of null values stored in the indexed column
   * in the underlying table.  This method may return an approximation.
   *
   * @return number of null values
   * @throws DatabaseException if a database-access error occurs
   */
  public long getNullCount() throws DatabaseException;

  /**
   * Finds the next row that has the specified data in the indexed
   * column.  Returns false if no such row could be found.  The
   * search always begins at the next row in the database and continues
   * to the last row in the database.
   *
   * @param data desired data
   * @return true if the new current row is valid; false otherwise
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean findNext(Object data) throws DatabaseException;
};