/*
 * IBuildingModel.java
 *
 * Created on December 3, 2002, 11:02 PM
 */


package BuildSim;


import java.util.List;


/** A model of a building, with elevators.  People come in and out, and take
 * the elevator to various floors.
 *
 * PersonIDs are integers >= 1.  Each person is uniquely identified by an ID.
 * IDs are not necessarily assigned sequentially.  ID's are assigned by the 
 * Controller, not the Model.  All people have equal capabilities, as far as
 * the Model and the View are concerned.
 *
 * ElevatorIDs are consecutive integers, starting from 1.  IDs are assigned to
 * elevators by the Model.  All elevators have equal capabilities, as far as the 
 * View and the Controller are concerned.
 *
 * Floor numbers are consecutive integers, starting from 1.  They have the usual
 * meaning of floor numbers in a building.  There are no "basements".  Floor 1 is
 * considered the ground floor; the building can be entered and exited only from
 * floor 1.
 *
 *Time is measured in "steps" since the creation of the Building at time 0.
      * Unless otherwise indicated, each method which changes the model state takes at lease one unit
      * of time. This is generally NOT indicated in the post conditions.  The model
 * is free to charge more than one step to a state change (but not less).  The model
 * will never subtract steps from the current time.

  Constructors: Concrete classes should provide a single constructor, as
 * follows:
 *      <init> (int numberOfFloors, int numberOfElevators);
 * Constructors should guarantee the following initial state:
 * no people in the building;  All elevators are on floor 1. 
 * The Model, View, and Controller may all assume that no personIDs have been
 * reserved in advance.
 *
 */
public interface IBuildingModel {
    
    /** A person enters the building.
     * Pre: the person is not already in the building.
     * Post: the person is in the building, on floor 1
     */
    public void enterBuilding(int personID);
    
    /** A person leaves the building
     * Pre: the person is in the building, on floor 1
     * Post: the person is not in the building
     */
    public void exitBuilding(int personID);
    
    /** Call an elevator, i.e., press the button to aks the elevator to come
     *  to that floor. 
     * Pre: there is such an elevator, and such a floor.
     * Post: the elevator will eventually come to that floor
     * *** MODIFIED 12/6: floor parameter added ****
     */
    public void callElevator(int elevatorID, int floor);  
    
    /** A person enters the elevator. 
     * Pre: the elevator is on the same floor as the person.
     * Post: the person is in the elevator (and no longer considered to be on
     * any floor).  
     */
    public void enterElevator(int personID, int elevatorID);
    
    /** Someone in the elevator pushes the button for a particular floor.
     * **** NEW METHOD **** added 12/6
     * Pre: the elevator exists and is not empty; the floor exists.
     * Post: the elevator will eventually stop at the requested floor.
     */
    public void requestFloor(int elevatorID, int floor);
    
    /** A person leaves the elevator
     * Pre: the person is in the elevator, and the elevator is stopped
     * at some floor.
     * Post: the person is on that floor (and not in the elevator).
     */
    public void exitElevator(int personID, int elevatorID);
    
    /** Answers, where is the elevator?
     * Pre: the elevator exists
     * Post: no state has changed 
     * @return a double indicating the floor that the elevator is on.  A non-integer
     * value indicates the elevator is between floors (in the natural interpretation).
     * CLARIFICATION 12/6: An integer value means the the elevator is actually
     * STOPPED at the floor, not just passing by.
     * The return value >= 1, and <= number of floors in the building
     */
    public double getElevatorLocation(int elevatorID); //MODIFIED 12/6
    
    /** Answers, where is the person?
     * Pre: the person exists
     * Post: no change in state
     * @return the floor where the person is located.  0 indicates the person
     * is known but is not in the building. 
       A positive integer indicates the FLOOR that a person is on.  A
     * negative integer indicates the number (negated) of the ELEVATOR the person
     * is on.
     */
     public double getPersonLocation(int personID);
     
     /** Tells whether the elevator has been requested to stop to at certain
      *  floor, but has not stopped at that floor since being requested.
      *  Such a request might have come from outside the elevator (callElevator)
      *  or from inside it (requestFloor).
      *  Pre: the elevator and floor are valid.
      *  Post: no change in status.
      *  @return -1 if the elevator has no current request for the floor.
      *  @return 0 if the status is not available.
      *  @return 1 if the elevator has a current request for the floor.
      *  OPTIONAL method: implementors may choose to return 0 for all queries, in 
      *  which case the method is effectively optional.  Otherwise, a value of 
      *  -1 or 1 should be returned, and 0 is never returned.
      *  *** NEW METHOD *** added 12/6/2002
      */
     public int getElevatorFloorStatus(int elevatorID, int floor);     
     
     /** Get a list of all the elevator IDs.
      */
     public List getElevatorList();
     
     /** Get a list of all the people on a given floor.
	@return a list of all people on the floor, if the floor exists.  
			Return null iff the floor does not exist.
      */
     public List getFloorInfo(int floor);
     
     /** Get a list of all the people in a given elevator.
      */
     public List getElevatorOccupants(int elevatorID); //MODIFIED 12/5
     
     /** Answers, what time is it?
      * 
      */
     public int getTime();
     
     /** Indicate that nothing has happened.  The Controller may use this to
      * signal to the model that some number of time steps have passed.
      * Pre: timeIntervals >=0
      * Post: if t is the time when the method is called, then t+timeIntervals
      * is the time when the method returns.
      */
     public void advanceClock(int timeIntervals);

// end IBModel
}