package java.util;

import ej.annotation.Nullable;

/**
 * The <code>Dictionary</code> class is the abstract parent of any class, such as
 * <code>Hashtable</code>, which maps keys to values. Every key and every value is an object. In any
 * one <code>Dictionary</code> object, every key is associated with at most one value. Given a
 * <code>Dictionary</code> and a key, the associated element can be looked up. Any non-<code>null</code>
 * object can be used as a key and as a value.
 * <p>
 * As a rule, the <code>equals</code> method should be used by implementations of this class to
 * decide if two keys are the same.
 * <p>
 * <strong>NOTE: This class is obsolete. New implementations should implement the Map interface,
 * rather than extending this class.</strong>
 *
 * @param <K>
 *        the type of the keys maintained by this dictionary
 * @param <V>
 *        the type of the mapped values
 *
 * @see java.util.Map
 * @see java.lang.Object#equals(java.lang.Object)
 * @see java.lang.Object#hashCode()
 * @see java.util.Hashtable
 */
public abstract class Dictionary<K, V> {

    /**
     * Sole constructor. (For invocation by subclass constructors, typically implicit.)
     */
    public Dictionary() {
    }

    /**
     * Returns an enumeration of the values in this dictionary. The general contract for the
     * <code>elements</code> method is that an <code>Enumeration</code> is returned that will generate all the
     * elements contained in entries in this dictionary.
     *
     * @return an enumeration of the values in this dictionary.
     * @see java.util.Dictionary#keys()
     * @see java.util.Enumeration
     */
    public abstract Enumeration<V> elements();

    /**
     * Returns the value to which the key is mapped in this dictionary. The general contract for the
     * <code>isEmpty</code> method is that if this dictionary contains an entry for the specified key, the
     * associated value is returned; otherwise, <code>null</code> is returned.
     *
     * @return the value to which the key is mapped in this dictionary, or <code>null</code> if the key is
     *         not mapped to any value in this dictionary.
     * @param key
     *        a key in this dictionary.
     * @exception NullPointerException
     *            if the <code>key</code> is <code>null</code>.
     * @see java.util.Dictionary#put(java.lang.Object, java.lang.Object)
     */
    @Nullable
    public abstract V get(Object key);

    /**
     * Tests if this dictionary maps no keys to value. The general contract for the <code>isEmpty</code>
     * method is that the result is true if and only if this dictionary contains no entries.
     *
     * @return <code>true</code> if this dictionary maps no keys to values; <code>false</code>
     *         otherwise.
     */
    public abstract boolean isEmpty();

    /**
     * Returns an enumeration of the keys in this dictionary. The general contract for the keys method
     * is that an <code>Enumeration</code> object is returned that will generate all the keys for which this
     * dictionary contains entries.
     *
     * @return an enumeration of the keys in this dictionary.
     * @see java.util.Dictionary#elements()
     * @see java.util.Enumeration
     */
    public abstract Enumeration<K> keys();

    /**
     * Maps the specified <code>key</code> to the specified <code>value</code> in this dictionary.
     * Neither the key nor the value can be <code>null</code>.
     * <p>
     * If this dictionary already contains an entry for the specified <code>key</code>, the value already in
     * this dictionary for that <code>key</code> is returned, after modifying the entry to contain the new
     * element.
     * <p>
     * If this dictionary does not already have an entry for the specified <code>key</code>, an entry is
     * created for the specified <code>key</code> and <code>value</code>, and <code>null</code> is returned.
     * <p>
     * The <code>value</code> can be retrieved by calling the <code>get</code> method with a
     * <code>key</code> that is equal to the original <code>key</code>.
     *
     * @param key
     *        the hashtable key.
     * @param value
     *        the value.
     * @return the previous value to which the <code>key</code> was mapped in this dictionary, or
     *         <code>null</code> if the key did not have a previous mapping.
     * @exception NullPointerException
     *            if the <code>key</code> or <code>value</code> is <code>null</code>.
     * @see java.lang.Object#equals(java.lang.Object)
     * @see java.util.Dictionary#get(java.lang.Object)
     */
    @Nullable
    public abstract V put(K key, V value);

    /**
     * Removes the <code>key</code> (and its corresponding <code>value</code>) from this dictionary.
     * This method does nothing if the <code>key</code> is not in this dictionary.
     *
     * @param key
     *        the key that needs to be removed.
     * @return the value to which the <code>key</code> had been mapped in this dictionary, or
     *         <code>null</code> if the key did not have a mapping.
     * @exception NullPointerException
     *            if <code>key</code> is <code>null</code>.
     */
    @Nullable
    public abstract V remove(Object key);

    /**
     * Returns the number of entries (distinct keys) in this dictionary.
     *
     * @return the number of keys in this dictionary.
     */
    public abstract int size();
}