package ModSQL;

/* $Id: DatabaseManager.java,v 1.8 2004/01/03 18:09:18 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 database managers.
 *
 * <p>To create a new type of database, you need to implement both this
 * interface and the DatabaseTable interface.  The primary role of the
 * DatabaseManager is to create DatabaseTable objects when given a table
 * name.
 *
 * @see DatabaseTable
 * @author chris.studholme@utoronto.ca
 */
public interface DatabaseManager {

  /**
   * Get the driver's major version number. Initially this should be 1.
   *
   * @return major version number
   */
  public int getMajorVersion();
  
  /**
   * Get the driver's minor version number. Initially this should be 0.
   *
   * @return minor version number
   */
  public int getMinorVersion();

  /**
   * Checks whether this database has the specified table.
   *
   * @param tablename name of the table
   * @return true if the table exists in this database and can be opened,
   * false otherwise
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean hasTable(String tablename) 
    throws DatabaseException;

  /**
   * Opens the database table with the specified name for read only
   * access.
   *
   * @param tablename name of the table to open
   * @return a DatabaseTable object representing the table, or null
   * if the table does not exist in this database
   * @throws DatabaseException if a database-access error occurs
   */
  public DatabaseTable openTable(String tablename)
    throws DatabaseException;

  /**
   * Opens the database table with the specified name with read only
   * or read write access.
   *
   * @param tablename name of the table to open
   * @param readonly true to open table read only
   * @return a DatabaseTable object representing the table, or null
   * if the table does not exist in this database
   * @throws DatabaseException if a database-access error occurs
   */
  public DatabaseTable openTable(String tablename, boolean readonly) 
    throws DatabaseException;

  /**
   * Create a new table.  If a table with the given name exists in the
   * database, this method should always throw an exception.  If the database
   * is not capable of supporting user created tables, this method should
   * return null.
   *
   * @param tablename name of the table to create
   * @param temporary table is temporary
   * @return the newly created table opened for read write access,
   * or null if the database doesn't support creating tables
   * @throws DatabaseException if a database-access error occurs
   */
  public DatabaseTable createTable(String tablename, boolean temporary)
    throws DatabaseException;
  
  /**
   * Create an index of the specified column in the specified table
   * (if capable).
   *
   * @param tablename name of the table to index
   * @param columnname name of the column to index
   * @return true if index was created, false if database is not
   * capable of creating indicies
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean createIndex(String tablename, String columnname)
    throws DatabaseException;
  
  /**
   * Drop a table.  This method should throw an exception if the table does
   * not exist.
   *
   * @param tablename name of the table to drop
   * @throws DatabaseException if a database-access error occurs
   */
  public void dropTable(String tablename)
    throws DatabaseException;
  
  /**
   * Drop an index.  This method should throw an exception if the table does
   * not exist, but should return false if the column has not been indexed.
   *
   * @param tablename name of the table with index
   * @param columnname name of the column with index
   * @return true if the index existed and has been dropped, 
   * false if it didn't exist
   * @throws DatabaseException if a database-access error occurs
   */
  public boolean dropIndex(String tablename, String columnname)
    throws DatabaseException;


  /**
   * <p>Get a database specific function for use in SQL.  This function may
   * be used in any SQL query (not just queries involving this database's
   * tables).  Note that when looking up function names, ModSQL will always
   * check for database specific functions before using built-in functions,
   * so this method may be used to override the built-in SQL functions.
   *
   * <p>This method should return null if a function by the specified name
   * is not found.
   *
   * @param name name of function to lookup (always lowercase)
   * @return new function object (or null if function not found)
   * @throws DatabaseException if a database-access error occurs
   */
  public Function getFunction(String name) 
    throws DatabaseException;
};