/**
 * Generic dictionaries (array-like structures that can be 
 *   indexed by arbitrary types of values).
 *
 * @author CSC153 2003
 */
public interface Dictionary
{

  // +------------------+-------------------------------
  // | Design Decisions |
  // +------------------+

  /*
    What should get and remove do if the key is not there?
    (a) Throw an exception.
    (b) Return null.
    Decision: (a).
    Why?  In honor of our missing colleague.

    What should happen with add if the key is already there?
    (a) Replace the current value.
    (b) Throw an exception.
    (c) Associate a list of objects with the key.
    Theory: Give the programmer finer control.
    That means use (b).  If a programmer wants to replace,
    standard-gender-neutral-pronoun calls replace.  If a 
    programmer wants to add, standard-gender-neutral-pronoun
    calls add.
    
    If programmers want replace, they call replace.  If programmers
    want to add, they call add.
   */

  // +---------+----------------------------------------
  // | Methods |
  // +---------+


  // Get the "key" for this dictionary, so that we can
  // store this dictionary in other dictioanries.
  // NOT A BASIC OPERATION
  // public Object getKey();

  // Determine if the dictionary is empty.
  public boolean isEmpty();

  // Get something from the dictinoary.
  public Object get(Object key);

  /**
   * Remove something from the dictionary.
   *
   * @exception Exception
   *   If the dictionary contains no entry with that key.
   */
  public Object remove(Object key)
    throws Exception;

  /**
   * Add something to the dictionary
   *
   * @exception Exception
   *   If the key is already in the dictionary.
   */
  public void add(Object key, Object associatedValue)
    throws Exception;

  /**
   * Replace something in the dictionary.
   *
   * @exception
   *   If nothing with that key is in the dictionary.
   */
  public void replace(Object key, Object newValue)
    throws Exception;

  /**
   * Determine if a key is in the dictionary.
   */
  public boolean containsKey(Object key);
} // interface Dictionary