/*
 * Created on Jan 27, 2005
 */
package mvc373Hw3B;

import java.util.List;

/** Interface for the model of a Towers of Hanoi game.
 * In addition to the methods listed here, concrete implementations
 * should have a public constructor with no arguments, e.g.
 * public TowerModel();
 */
public interface ITowerModel {
    
    /** Start or restart the game from an initial configuration:
     * A number of towers (>=1), with 
     * all of the discs are initially on tower 0.  The towers are thought
     * of as being numbered from 0.  The disks are thought of as having
     * sizes from 1 to discCount, and are considered to be arranged from
     * smallest (top) to largest (bottom) on the tower.
     * @param towerCount the number of towers; must be >= 1; normally this
     * value would be 3.
     * @param discCount the number of discs to start with; must be >= 1.
     * The disks are numbered 1 to discCount; the disk number is also its
     * "size" in the sense of the puzzle: a disk cannot be placed on top
     * of a smaller disk.
     * @return true if the game can be started; false otherwise.
     * @throws IllegalArgumentException if the number of towers is illegal.
     */
    boolean start(int towerCount, int discCount);
    
    /** Move a disc from one tower to another. It is understood that the
     * topmost disk is the one moved, and it is placed in the top-most
     * position of the new disk.
     * 
     * @param fromTower the tower from which the disk is to be moved.  
     * Must be a valid tower number.
     * @param toTower the tower to which the disk is to be moved.  Must be
     * a valid tower number.
     * @return true iff the move would result in a legal configuration;
     * in this case, the move has been carried out.  A false return indicates
     * that no move was made.  A "legal configuration" is one in which no
     * disk is on top of a smaller disk.
     * @throws IllegalArgumentException if either tower number is illegal,
     * or if the fromTower has no disks on it.
     */
    boolean move(int fromTower, int toTower);
    
    
    /** Move to the previous configuration.  
     * 
     * @return true if the backup was performed; false otherwise.  The only
     * legitimate reason for false is that the initial state had already
     * been reached.  You do not backup past a "start" state (in case more
     * than one start had been done.)
     */
    boolean backup();
    
    
    /** Tell how many towers there are.
     * 
     * @return the number of towers (>= 1).
     */
    int getTowerCount();
    
    /** Get a list of the disks on a tower, from top to bottom.
     * 
     * @param tower a valid tower (always >= 0)
     * @return a list representing the sizes of the disks on the tower,
     * from top (first in the list) to bottom (last in the list).
     * The list may be empty but not null;
     * the entries are non-null Integers > 0.
     */
    List getDiskList(int tower);
    
    /** Tell which tower a disc is on.
     * 
     * @param discNumber a valid disc number
     * @return the number (>=0) of the tower on which the disc currently resides.
     * @throws IllegalArgumentException if the discNumber is out of range.
     */
    int findDisk(int discNumber);
    
    /** Tells which disk was most recently moved.  This is NOT a backup.
     * 
     * @return the number of the disc which was most recently moved,
     * or -1 if there have not been any moves in the game.
     */
    int getLastMovedDisk();
    
    /** Tells which tower a disc was most recently moved from.  This is NOT
     * a backup.
     * 
     * @return the number of the tower from which a disc was most recently
     * moved, or -1 if there have not been any moves in the game.
     */
    int getLastSourceTower();
    
    /** Tells which tower a disc was most recently moved from.  This is NOT 
     * a backup.
     * 
     * @return the number of the tower to which a disc was most recently
     * moved, or -1 if there have not been any moves in the game.
     */
    int getLastGoalTower();
    
    /** Tells which disk in a certain position on a tower.  For example,
     * if tower 1 contains disks 3,5,6,7, and 10, then getNthDisc(1, 3) would
     * return 7.
     * 
     * @param tower a valid tower number (>=0)
     * @param discPosition the position of interest, numbered from 0
     * from the top of the tower.
     * @return the disc number at the given position (number with
     * 0 as the topmost disk), or -1 if tower has
     * fewer discs than the requested position.
     * @throws IllegalArgumentException if the tower number is invalid for
     * the game.
     */
    int getNthDisc(int tower, int discPosition);
    

}