package rpi.goldsd.container;

/**
 * The <tt>AssociativeContainer</tt> interface defines the methods
 * required to implement a mapping or hashtable-like container object.
 * One of the most important aspects of this interface is the
 * use of a <tt>Comparable</tt> object as the <tt>key</tt> argument
 * to the <tt>add()</tt>, <tt>map()</tt>, and <tt>remove()</tt>
 * methods.  This key will likely be a unique key; however, this
 * restriction is neither imposed nor enforced by this interface.
 * <p>
 * Note that the <tt>add()</tt> method is
 * defined to potentially throw a <tt>DuplicateElementException</tt>
 * exception if the key is implemented as a unique key and this
 * unique constraint is violated during run-time.
 *
 * @see Comparable
 * @see DuplicateElementException
 * @see Table
 * @version 1.1.2, 4/16/98
 * @author David Goldschmidt
 */
public interface AssociativeContainer
{
  /**
   * Adds a new associative entry to this associative container.
   * Note that the single argument consists of both the key and
   * the actual data to be stored in this associative container.
   * @param keyAndData the key used to identify the data, as well
   *                   as the actual data to be stored.
   * @exception DuplicateElementException if a unique key is used
   *            and the key used already exists in this container.
   */
  public void add( Comparable keyAndData )
    throws DuplicateElementException;


  /**
   * Adds a new associative entry to this associative container.
   * @param key the key used to identify the associated data.
   * @param data the actual data to be stored.
   * @exception DuplicateElementException if a unique key is used
   *            and the key used already exists in this container.
   */
  public void add( Comparable key, Object data )
    throws DuplicateElementException;


  /** Removes all elements from this associative container. */
  public void clear();


  /**
   * Returns <tt>true</tt> if the given key maps to an element in
   * this associative container.
   * @param key the key used to identify an element in this
   *            associative container.
   * @return <tt>true</tt> if the given key maps to an element in
   *         this associative container; <tt>false</tt> otherwise.
   */
  public boolean contains( Comparable key );


  /**
   * Provides an enumeration of the data stored in this container.
   * @return an enumeration of the elements stored in this container.
   */
  public java.util.Enumeration elements();


  /**
   * Returns the number of elements in this container.
   * @return the number of elements in this container.
   */
  public int getSize();


  /**
   * Returns <tt>true</tt> if this container contains no elements.
   * @return <tt>true</tt> if this container contains no elements;
   *         <tt>false</tt> otherwise.
   */
  public boolean isEmpty();


  /**
   * Provides an enumeration of the keys stored in this container.
   * @return an enumeration of the keys stored in this container.
   */
  public java.util.Enumeration keys();


  /**
   * Provides a mechanism for mapping a given key to its corresponding data.
   * @param key the key used to identify and locate the associated data.
   * @return the data stored in the container indexed by the given key;
   *         or <tt>null</tt> if the key does not map to a data object
   *         in this container.
   */
  public Object map( Comparable key );


  /**
   * Removes a data element from this container identified by the given key.
   * @param key the key used to identify and locate the associated data.
   * @return the object that is removed from the container; or <tt>null</tt>
   *         if the key does not map to a data object in this container.
   */
  public Object remove( Comparable key );
}