import java.util.*;

/** MultiMap is an interface designed for Objects that associate
 * multiple values with a single key.
 *
 * <pre>
 * @specfield bindings : set[(Object, Collection)] //the connections stored by this map
 * @derivedfield keys : set[Objects] //the keys in this MultiMap
 * @derivedfield values : set[Objects] //the values
 * @endspec
 * </pre>
 *
 * Although similar in nature to the Map interface, MultiMap
 * cannot extend Map because its very nature breaks the requirements
 * specified by Map.
 **/
public interface MultiMap {

    /** Returns true iff this mapping maps key to value
     *
     * @returns true iff getAll(key).contains(value)
     **/
    public boolean contains(Object key, Object value);

    /** Returns an unmodifiable Collection snapshot of all mappings from key
     *
     * @returns an unmodifiable Collection snapshot of all mappings from key
     **/
    public Collection getAll(Object key);

    /** Adds an association from key to each value contained by values
     *
     * @requires values != null
     * @effects for all v in values,
     *           put(key, v)
     **/
    public void putAll(Object key, Collection values);

    /** Removes a binding from key to value.
     *
     * @returns true iff key was associated with value
     **/
    public boolean remove(Object key, Object value);
}