/*
 * IHoroscopeModel.java
 *
 * Created on August 7, 2003, 8:50 AM
 *
 * @author David Tran
 */

package mvc143;

/** 
 * The interface to a model of a horoscope finder.
 * The horoscope finder can determine a person's fortune/horoscope based on
 * signs chosen by the creator of the model.  Some examples of signs include:
 * <br><br>
 * 
 * Pisces from the Greek Zodiac 
 * Tiger from the Chinese Zodiac
 * Alligator from the Mayan Zodiac
 * Kanya from the Hindu Zodiac
 *
 * <br><br>
 *
 * or even signs made up by the modeler :).<br><br>  
 *
 * However there are some restrictions:
 * All signs must correlate to a range of dates in the gregorian calendar system.
 * <br><br>
 *
 * Implementors of the model should supply a constructor with no arguments.
 * After completion of the constructor, the model should be ready 
 * to give out fortunes/horoscopes.<br><br>
 *
 * The command "terminate" means that no more demands will be placed 
 * on the model, so it is free to cleanup or terminate.<br><br>
 *
 * 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.<br><br>
 *
 * NOTES:<br>
 * Study all of the various interfaces first to determine which tasks belong to 
 * each part of the MVC.<br>
 * For this portion of the project, you need only a basic understanding 
 * of the Date/Calendar classes.<br>
 */
public interface IHoroscopeModel {

    /**
     * Should have a constructor for the Model which takes no arguments.
     * (Unfortunately can't be specified in Java)
     */
     //public HoroscopeModel();    

    /** 
     * Retrieves a fortune/horoscope message "based" on the specified sign.
     * (Note the quotations around the word 'based' :) ).
     * Restriction: this method returns at least 10 different fortunes 
     * before repeating. (A queue could be a good implentation for this).
     * @return a fortune/horoscope
     */
    public IFortune getAnotherFortune(ISign someSign);

    /** 
     * Retrieves the last fortune/horoscope message (i.e. the
     * last fortune retrieved from this model).
     * @return a fortune/horoscope, or null if no fortunes have been given.
     */
    public IFortune getLastFortune();

    /** 
     * Retrieves a list of the ten last fortune/horoscope messages 
     * for the specified sign, in order from most recent to least recent.
     * (A stack with limited space could be a good implentation for this).
     * @return a list of the last ten fortunes/horoscopes.  If ten fortunes
     * have not yet been made for a particular sign, then the list that is
     * returned has a length equal to the number of fortunes made for that sign.
     */
    public IFortune[] getLastTenFortunes(ISign someSign);

    /** 
     * Sometimes a fortune can mean more backwards than forwards...
     * Retrieves a fortune with a reversed message and reversed rating 
     * of the current fortune.
     * (A stack could be a good implentation for this).
     * @return a reversed fortune of the current fortune, or null
     *  if no fortunes have yet been made.
     */
    public IFortune getReverseFortune(ISign someSign);

    /** 
     * Retrieves the current sign (i.e. the sign used to obtain
     * the most recent fortune).
     * @return the sign most recently used to obtain the message, 
     *  or null if no fortunes have been given.
     */
    public ISign getLastSign();
    
    /** 
     * Retrieves a list of all signs this model knows about.
     * @return a list of known signs
     */
    public ISign[] getSigns();

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

// end IHoroscopeModel
}