/*
 * IBus.java
 *
 * Created on August 8, 2003, 11:36 PM
 *
 * @author Zuo Yan
 */

package mvc143;


/** The interface to a bus in the bus system model.
 * <p>
 * A bus object contains data about a particular bus in the bus system model.
 * A bus is created with a latitude and longitude postion from the model. Each
 * bus contains data about the people currently riding on the bus. In addition,
 * a bus contains informat about a route that it should follow.
 * <p>
 * Note that instantiation of a new bus should only be done in the model,
 * because each model can have a different internal representation.
 */
public interface IBus {

    /** Gets the model dependent object identifying this bus.
     * <br>
     * Note: it is not a requirement that ids have to be unique
     *
     * @return the object identifying this bus
     */
    Object getID();

    /** Indicates whether a bus is "equal" to this one
     *
     * @param other the bus to compare to
     * @return <code>true</code> if they are the same; <code>false</code> otherwise
     */
    boolean equals(IBus other);

    /** Gets the array of IPerson currently riding on this bus
     * <br>
     * Note: changes to the array are NOT reflected in the model,
     *       but changes to a person in the array are reflected
     *
     * @return the array of people on this bus
     */
    IPerson[] getPassengers();

    /** Gets the maximum capacity of this bus
     *
     * @return the maximum number of people that can ride on this bus
     */
    int getMaxPassengers();

    /** Sets the maximum of capacity this bus
     *
     * @param num the maximum number of people that can ride on this bus
     */
    void setMaxPassengers(int num);

    /** Adds a person to this bus
     *
     * @param p the person to add
     * @return <code>true</code> if the person was able to get on;
     *         <code>false</code> otherwise
     */
    boolean addPassenger(IPerson p);

    /** Removes a person on this bus
     *
     * @param p the person to remove
     * @return <code>true</code> if the person was found and removed;
     *         <code>false</code> otherwise
     */
    boolean removePassenger(IPerson p);

    /** Gets the next person to get off this bus
     *
     * @return the next person or <code>null</code> if there is no one on th bus
     */
    IPerson getNext();

    /** Removes the next person to get off this bus
     *
     * @return the person previously next to get off or
     *         <code>null</code> if there was no one waiting
     */
    IPerson removeNext();

    /** Sets the bus route that this bus should take
     *
     * @param route the array of bus stops that this bus should stop at
     */
    void setRoute(IBusStop[] route);

    /** Gets the bus route that this bus is currently taking
     * <br>
     *  Note: changes to the array are NOT reflected in the model,
     *        but changes to a bus stop in the array are reflected
     *
     * @return the array of bus stops that this bus is stopping at
     */
    IBusStop[] getRoute();

    /** Gets the previous bus stop that this bus stopped at
     *
     * @return the previous bus stop or <code>null</code> if there was none
     */
    IBusStop getPrevStop();

    /** Gets the next bus stop that this bus should stop at
     *
     * @return the next bus stop or <code>null</code> if there is no route
     */
    IBusStop getNextStop();

    /** Tells this bus that its next stop has been reached
     * <br>
     * This method only changes the state of this bus such that the old next
     * stop is now the previous stop and a new next stop is selected from the
     * route
     *
     */
    void advanceToNextStop();

    /** Gets the latitude coordinate of this bus
     *
     * @return the latitude position
     */
    double getLatitude();

    /** Gets the longitude coordinate of this bus
     *
     * @return the longitude position
     */
    double getLongitude();

    /** Sets the latitude coordinate of this bus
     *
     * @return the latitude position
     */
    void setLatitude(double latitude);

    /** Sets the longitude coordinate of this bus
     *
     * @return the longitude position
     */
    void setLongitude(double longitude);

}