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

package mvc143;

import java.util.Collection;


/** The interface to a Bus System Model.
 * <p>
 * The bus system model keeps track of all the objects in the system. Objects
 * should only be created from the model and registered with the system by
 * calling the appropriate add method.
 * <p>
 * Implementors of the model should supply a constructor with no arguments.
 * After completion of the constructor, the model should be ready to accept
 * commands.
 * <p>
 * Implementors also need to write the model specifc classes that implements
 * the interfaces IPerson, IBus, and IBusStop. Those classes are part of the
 * model and should be included in the same file as the implementation of this
 * interface.
 * <p>
 * The command "terminate" means that no more demands will be placed on the
 * model, so it is free to cleanup or terminate.
 * <p>
 * In addition to any exceptions listed below, the methods may throw an
 * exception or otherwise signal an error if called when the model has already
 * been terminated.
 *
 */
public interface IBusSimModel {

    /** Creates a new IPerson object from this model
     *
     * @param start the starting bus stop of the new person
     * @param dest the destination bus stop of the new person
     * @return the new person object
     */
    public IPerson createPerson(IBusStop start, IBusStop dest);

    /** Creates a new IBusStop object from this model
     *
     * @param latitude the latitude position of the bus stop
     * @param longitude the longitude position of the bus stop
     * @return the new busstop object
     */
    public IBusStop createBusStop(double latitude, double longitude);

    /** Creates a new IBus object from this model
     *
     * @param latitude the starting latitude position of the bus
     * @param longitude the starting longitude position of the bus stop
     * @return the new bus object
     */
    public IBus createBus(double latitude, double longitude);

    /** Registers a bus stop with this system
     *
     * @param bs the bus stop to add to the system
     * @return <code>true</code> if the bus stop was successfully added;
     *         <code>false</code> otherwise
     */
    public boolean add(IBusStop bs);

    /** Registers a bus with this system
     *
     * @param b the bus to add to the system
     * @return <code>true</code> if the bus was successfully added;
     *         <code>false</code> otherwise
     */
    public boolean add(IBus b);

    /** Get the collection of IBus objects currently registered with the system
     * <br>
     * Note: changes to the collection are directly reflected in the model.
     *
     * @return the collection of registered busses
     */
    public Collection getBusses();

    /** Get the collection of IBusStop objects currently registered with the system
     * <br>
     * Note: changes to the collection is directly reflected in the model.
     *
     * @return the collection of registered bus stops
     */
    public Collection getStops();


    /** Signal that the model will not be called upon again.
     */
    public void terminate();

}