001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one or more
003     *  contributor license agreements.  See the NOTICE file distributed with
004     *  this work for additional information regarding copyright ownership.
005     *  The ASF licenses this file to You under the Apache License, Version 2.0
006     *  (the "License"); you may not use this file except in compliance with
007     *  the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    package org.apache.commons.collections;
018    
019    import java.util.Collection;
020    import java.util.Map;
021    
022    /** 
023     * Defines a map that holds a collection of values against each key.
024     * <p>
025     * A <code>MultiMap</code> is a Map with slightly different semantics.
026     * Putting a value into the map will add the value to a Collection at that key.
027     * Getting a value will return a Collection, holding all the values put to that key.
028     * <p>
029     * For example:
030     * <pre>
031     * MultiMap mhm = new MultiHashMap();
032     * mhm.put(key, "A");
033     * mhm.put(key, "B");
034     * mhm.put(key, "C");
035     * Collection coll = (Collection) mhm.get(key);</pre>
036     * <p>
037     * <code>coll</code> will be a collection containing "A", "B", "C".
038     * <p>
039     * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
040     * These were added solely for documentation purposes and do not change the interface
041     * as they were defined in the superinterface <code>Map</code> anyway.
042     *
043     * @since Commons Collections 2.0
044     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
045     * 
046     * @author Christopher Berry
047     * @author James Strachan
048     * @author Stephen Colebourne
049     */
050    public interface MultiMap extends Map {
051    
052        /**
053         * Removes a specific value from map.
054         * <p>
055         * The item is removed from the collection mapped to the specified key.
056         * Other values attached to that key are unaffected.
057         * <p>
058         * If the last value for a key is removed, implementations typically
059         * return <code>null</code> from a subsequant <code>get(Object)</code>, however
060         * they may choose to return an empty collection.
061         * 
062         * @param key  the key to remove from
063         * @param item  the item to remove
064         * @return the value removed (which was passed in), null if nothing removed
065         * @throws UnsupportedOperationException if the map is unmodifiable
066         * @throws ClassCastException if the key or value is of an invalid type
067         * @throws NullPointerException if the key or value is null and null is invalid
068         */
069        public Object remove(Object key, Object item);
070    
071        //-----------------------------------------------------------------------
072        /**
073         * Gets the number of keys in this map.
074         * <p>
075         * Implementations typically return only the count of keys in the map
076         * This cannot be mandated due to backwards compatability of this interface.
077         *
078         * @return the number of key-collection mappings in this map
079         */
080        int size();
081    
082        /**
083         * Gets the collection of values associated with the specified key.
084         * <p>
085         * The returned value will implement <code>Collection</code>. Implementations
086         * are free to declare that they return <code>Collection</code> subclasses
087         * such as <code>List</code> or <code>Set</code>.
088         * <p>
089         * Implementations typically return <code>null</code> if no values have
090         * been mapped to the key, however the implementation may choose to
091         * return an empty collection.
092         * <p>
093         * Implementations may choose to return a clone of the internal collection.
094         *
095         * @param key  the key to retrieve
096         * @return the <code>Collection</code> of values, implementations should
097         *  return <code>null</code> for no mapping, but may return an empty collection
098         * @throws ClassCastException if the key is of an invalid type
099         * @throws NullPointerException if the key is null and null keys are invalid
100         */
101        Object get(Object key);
102    
103        /**
104         * Checks whether the map contains the value specified.
105         * <p>
106         * Implementations typically check all collections against all keys for the value.
107         * This cannot be mandated due to backwards compatability of this interface.
108         *
109         * @param value  the value to search for
110         * @return true if the map contains the value
111         * @throws ClassCastException if the value is of an invalid type
112         * @throws NullPointerException if the value is null and null value are invalid
113         */
114        boolean containsValue(Object value);
115    
116        /**
117         * Adds the value to the collection associated with the specified key.
118         * <p>
119         * Unlike a normal <code>Map</code> the previous value is not replaced.
120         * Instead the new value is added to the collection stored against the key.
121         * The collection may be a <code>List</code>, <code>Set</code> or other
122         * collection dependent on implementation.
123         *
124         * @param key  the key to store against
125         * @param value  the value to add to the collection at the key
126         * @return typically the value added if the map changed and null if the map did not change
127         * @throws UnsupportedOperationException if the map is unmodifiable
128         * @throws ClassCastException if the key or value is of an invalid type
129         * @throws NullPointerException if the key or value is null and null is invalid
130         * @throws IllegalArgumentException if the key or value is invalid
131         */
132        Object put(Object key, Object value);
133    
134        /**
135         * Removes all values associated with the specified key.
136         * <p>
137         * Implementations typically return <code>null</code> from a subsequant
138         * <code>get(Object)</code>, however they may choose to return an empty collection.
139         *
140         * @param key  the key to remove values from
141         * @return the <code>Collection</code> of values removed, implementations should
142         *  return <code>null</code> for no mapping found, but may return an empty collection
143         * @throws UnsupportedOperationException if the map is unmodifiable
144         * @throws ClassCastException if the key is of an invalid type
145         * @throws NullPointerException if the key is null and null keys are invalid
146         */
147        Object remove(Object key);
148    
149        /**
150         * Gets a collection containing all the values in the map.
151         * <p>
152         * Inplementations typically return a collection containing the combination
153         * of values from all keys.
154         * This cannot be mandated due to backwards compatability of this interface.
155         *
156         * @return a collection view of the values contained in this map
157         */
158        Collection values();
159    
160    }