import java.util.Iterator;

/**
   The Dictionary interface specifies a collection of items (an item
   is an element together with a key) which can be searched by key.
  
   @author      Franck van Breugel
   @version     1.3    March 28, 2001
*/
public interface Dictionary extends InspectableContainer 
{
    /** Object returned if findElement or remove is unsuccessful. */
    public Object NO_SUCH_KEY = new Object();

    /**
       Returns the collection of keys stored in this dictionary.

       @return The collection of keys stored in this dictionary.
    */
    public Iterator keys();

    /**
       Returns the element of an item in this dictionary with the
       specified key; returns NO_SUCH_KEY if this dictionary does not
       contain an item with the specified key.

       @param key The key to be searched for.
       @return The element of an item in this dictionary with the
       specified key; returns NO_SUCH_KEY if this dictionary does not
       contain an item with the specified key.
    */
    public Object findElement(Object key);

    /**
       Returns the collection of elements of item in this dictionary with the
       specified key.

       @param key The key to be searched for.
       @return The collection of elements of item in this dictionary with the
       specified key.
    */
    public Iterator findAllElements(Object key);

    /**
       Add item with the specified key and element to this dictionary.

       @param key The key of the item to be inserted.
       @param element The element of the item to be inserted.
    */
    public void insertItem(Object key, Object element);

    /**
       Removes an item from this dictionary with the specified key and
       returns its element; returns NO_SUCH_KEY if this dictionary does not
       contain an item with the specified key.

       @param key The key to be searched for.
       @return The element of the removed item if there exists an item
       with the specified key; NO_SUCH_KEY otherwise.
    */
    public Object removeElement(Object key);

    /**
       Removes all items from this dictionary with the specified key and
       returns the collection of corresponding elements.

       @param key The key to be searched for.
       @return The collection of elements with the specified key in this
       directory.
    */
    public Iterator removeAllElements(Object key);
}