/**
 * Offers the user of a mail box several options, such as the width of the line
 * lets the user design a personal signature, stores some personal information 
 * about the user and contains an address book.
 * @author Khong Lovan
 * @author Elias Vafiadis
 * @author Anthony Nakaar
 * @author Wanlin Liu
 * version 1.0 of October, 1999
 */

public interface OptionsInterface {
    
   
    //+------------+---------------------------------------------------------
    //| Extractors |
    //+------------+
    
    /**
     * Purpose: Get an option whose value is a number.  For now, use integers as
     * our numbers.
     * Parameter option name
     * Pre:  The option is initialized.
     * Post: The option is unchanged.
     * Return: The value of the given option.
     * @exception OptionException
     * If that option is undefined.
     */
   public int getNumericOption(String optionName) 
     throws OptionException;

    /**
     * Purpose: Get an option whose value is a String. 
     * Parameter option name
     * Pre:  The option is initialized.
     * Post: The option is unchanged.
     * Return: The value of the given option.
     * @exception OptionException
     * If that option is undefined.
     */
   public String getStringOption(String optionName) 
     throws OptionException;

    
    /**
     * Get an option whose value is some other object.
     * @exception OptionException
     *   If that option is undefined.
     */
    public Object getOption(String optionName)
        throws OptionException;

     
    /**
     * Purpose: Get a flag: something that can either be on (true) or
     * off (false).
     * Parameter: the name of the flag.
     * Pre: The flag has been initialized.
     * Post: The flag has not been changed.
     * Return: the value of the flag, e.g. on or off.
     * @exception OptionException
     * if that option is undefined.
     */
    public boolean getFlag(String flagName)
        throws OptionException;    
    
   
    //+-----------+--------------------------------------------------------
    //| Modifiers |
    //+-----------+

     /**
     * Purpose: Set an option whose value is a string.  return the old value.
     * Parameter: option name and the new value.
     * Pre: the option is initialized.
     * Post: The option takes on the new value, no other option value is changed.
     * Return: The old value of the given option.
     * @exception OptionException
     * If that option is undefined
     */
    public void setStringOption(String optionName, String newVal)
        throws OptionException;
    /**
     * Purpose: Set an option whose value is a number.
     * For now, we assume that all values are of integer type.
     * Parameter: option name and the new value.
     * Pre: the option is initialized.
     * Post: The option takes on the new value, no other option value is changed.
     * Return: nothing
     * @exception OptionException
     * If that option is undefined
     */   
     public void setNumericOption(String optionName, int newValue)
         throws OptionException;
   
    /**
     * Purpose: Set a flag, i.e. turn it on or off.
     * Parameter: the name of the flag and the new value.
     * Pre: The flag has been initialized.
     * Post: The flag has been changed.
     * Return: nothing.
     * @exception OptionException
     * if that option is undefined.
     */
    
    public void setFlag(String flagName, boolean flagValue)
        throws OptionException;
   
   
 
    /**
     * Purpose: Set an option whose value is an object.
     * Parameter: option name and the new value.
     * Pre: the option is initialized.
     * Post: The option takes on the new value, nothing else is changed.
     * Return: The old value of the given option.
     * @exception OptionException
     * if the option is undefined.
     */
    public void setOption(String optionName, String optionType, Object newVal)
        throws OptionException;

    
    //+--------------+--------------------------------------------------
    //| Capabilities |
    //+--------------+
    
    /** 
     * Purpose: convert the contents of the object to a displayable string.
     * Paramter: none.
     * Pre: all the fields of the objects are initialized.
     * Post: no value is changed.
     * Return: a string containing all values of fields of this object.
     * Throws no exceptions.
     */
    public String toString();
    
}