package ModSQL;
import java.sql.*;

/* $Id: RowConstructor.java,v 1.5 2003/05/29 04:28:21 cvs Exp $
 *
 * Copyright (c) 2003 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.
 */

/**
 * A row constructor (in SQL speak) is a single row of one or more columns.
 * This interface extends Function by adding methods to access specific
 * columns.  The corresponding methods in the Function interface that do
 * not have the column parameter should work as specified in the case of
 * a single column, but should throw an exception in the case of two or
 * more columns.
 *
 * @author chris.studholme@utoronto.ca
 */
public interface RowConstructor extends Function {
  

  /****************  result meta-data  ****************/

  /**
   * <p>Returns the number of columns the row has.  The row will always have
   * at least one column.  
   *
   * <p>This method can only be used after optimize() has been called.
   *
   * @return number of columns in row list
   * @throws SQLException if a database-access error occurs
   */
  public int getColumnCount() throws SQLException;

  /**
   * <p>Return the SQL type of the value in the specified column.
   *
   * <p>Function.getSQLType() should work as specified if this row has only
   * one column, but must throw an exception in the case of two or more 
   * columns.
   *
   * <p>This method can only be used after optimize() has been called.
   *
   * @param column column number (starting from zero)
   * @return SQL type of data to be returned
   * @throws SQLException if an error occurs
   * @throws IndexOutOfBoundsException if the column if out of range
   */
  public int getSQLType(int column) throws SQLException;

  /**
   * <p>Return the maximum number of characters String values in the specified
   * column will have.  If the column is not of String type or if the maximum
   * length is not known, -1 should be returned.
   *
   * <p>Function.getMaxResultSize() should work as specified if this row has
   * only one column, but must throw an exception in the case of two or more 
   * columns.
   *
   * <p>This method can only be used after optimize() has been called.
   *
   * @param column column number (starting from zero)
   * @return maximum size of String returned or -1 if unknown
   * @throws SQLException if an error occurs
   * @throws IndexOutOfBoundsException if the column if out of range
   */
  public int getMaxResultSize(int column) throws SQLException;


  /****************  evaluation methods  ****************/

  /**
   * <p>Evaluate each column of the row and return the results as an array
   * of length equal to the value returned by numColumns().  If the row
   * is the result of a subquery with no rows, the result will be an
   * array of NULL values.
   *
   * <p>The evaluate() methods in Function should work as specified if this
   * row has only one column, but must throw an exception in the case of two
   * or more columns.
   *
   * <p>This method can only be used after optimize() has been called.
   *
   * @param aggregate final evaluation of aggregates
   * @return array of objects
   * @throws SQLException if an error occurs
   * @throws EndOfTable if a database was advanced beyond the end of the table
  */
  public Object[] evaluateRow(boolean aggregate) 
    throws SQLException, EndOfTable;

};