import java.util.Iterator;

/** 
 * A Java interface for the Dictionary ADT.
 * 
 * @param <K> The key type.
 * @param <V> The value type.
 * 
 * @author Jadrian Miles
 */
public interface Dictionary<K,V> extends Iterable<Dictionary.Entry<K,V>> {
    
    /**
     * A simple interface for key-value pairs.
     * 
     * @param <K> The key type.
     * @param <V> The value type.
     */
    public interface Entry<K,V> {
        public K key();
        public V value();
    }
    
    /** Sets the value associated with a given key.
     * If the key didn't already exist in the dictionary, it gets added;
     * otherwise, the new value replaces the old one associated with this key.
     */
    public void add(K key, V value);
    
    /** Returns the value associated with a given key.
     * @throws MissingKeyException if the key was not in the dictionary.
     */
    public V getValue(K key);
    
    /** Removes a specific entry from this dictionary.
     * @throws MissingKeyException if the key was not in the dictionary.
     */
    public void remove(K key);
    
    /** Returns whether a specific key is in this dictionary. */
    public boolean contains(K key);
    
    /** Returns the size of this dictionary. */
    public int size();
    
    /** Returns true if this dictionary is empty. */
    public boolean isEmpty();
    
    /** Removes all entries from this dictionary. */
    public void clear();
    
    /** Returns an iterator over the key-value pairs in the dictionary.
     * This iterator is silently invalidated if the dictionary is modified
     * during the iterator's lifetime.  The only exception to this is the
     * iterator's own remove() method.
     */
    public Iterator<Entry<K,V>> iterator();
    
    /** An exception to indicate that a key is not stored in the dictionary. */
    public static class MissingKeyException extends RuntimeException {
        public MissingKeyException() {
            super();
        }
        public MissingKeyException(String message) {
            super(message);
        }
    }
}