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 */
017package org.apache.commons.collections4;
018
019import java.util.Collection;
020
021/**
022 * Defines a map that holds a collection of values against each key.
023 * <p>
024 * A <code>MultiMap</code> is a Map with slightly different semantics.
025 * Putting a value into the map will add the value to a Collection at that key.
026 * Getting a value will return a Collection, holding all the values put to that key.
027 * <p>
028 * For example:
029 * <pre>
030 * MultiMap mhm = new MultiValueMap();
031 * mhm.put(key, "A");
032 * mhm.put(key, "B");
033 * mhm.put(key, "C");
034 * Collection coll = (Collection) mhm.get(key);</pre>
035 * <p>
036 * <code>coll</code> will be a collection containing "A", "B", "C".
037 * <p>
038 * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
039 * These were added solely for documentation purposes and do not change the interface
040 * as they were defined in the superinterface <code>Map</code> anyway.
041 *
042 * @since 2.0
043 * @version $Id: MultiMap.html 972421 2015-11-14 20:00:04Z tn $
044 */
045public interface MultiMap<K, V> extends IterableMap<K, Object> {
046
047    /**
048     * Removes a specific value from map.
049     * <p>
050     * The item is removed from the collection mapped to the specified key.
051     * Other values attached to that key are unaffected.
052     * <p>
053     * If the last value for a key is removed, implementations typically
054     * return <code>null</code> from a subsequent <code>get(Object)</code>, however
055     * they may choose to return an empty collection.
056     *
057     * @param key  the key to remove from
058     * @param item  the item to remove
059     * @return {@code true} if the mapping was removed, {@code false} otherwise
060     * @throws UnsupportedOperationException if the map is unmodifiable
061     * @throws ClassCastException if the key or value is of an invalid type
062     * @throws NullPointerException if the key or value is null and null is invalid
063     * @since 4.0 (signature in previous releases: V remove(K, V))
064     */
065    boolean removeMapping(K key, V item);
066
067    //-----------------------------------------------------------------------
068    /**
069     * Gets the number of keys in this map.
070     * <p>
071     * Implementations typically return only the count of keys in the map
072     * This cannot be mandated due to backwards compatibility of this interface.
073     *
074     * @return the number of key-collection mappings in this map
075     */
076    int size();
077
078    /**
079     * Gets the collection of values associated with the specified key.
080     * <p>
081     * The returned value will implement <code>Collection</code>. Implementations
082     * are free to declare that they return <code>Collection</code> subclasses
083     * such as <code>List</code> or <code>Set</code>.
084     * <p>
085     * Implementations typically return <code>null</code> if no values have
086     * been mapped to the key, however the implementation may choose to
087     * return an empty collection.
088     * <p>
089     * Implementations may choose to return a clone of the internal collection.
090     *
091     * @param key  the key to retrieve
092     * @return the <code>Collection</code> of values, implementations should
093     *  return <code>null</code> for no mapping, but may return an empty collection
094     * @throws ClassCastException if the key is of an invalid type
095     * @throws NullPointerException if the key is null and null keys are invalid
096     */
097    Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get
098
099    /**
100     * Checks whether the map contains the value specified.
101     * <p>
102     * Implementations typically check all collections against all keys for the value.
103     * This cannot be mandated due to backwards compatibility of this interface.
104     *
105     * @param value  the value to search for
106     * @return true if the map contains the value
107     * @throws ClassCastException if the value is of an invalid type
108     * @throws NullPointerException if the value is null and null value are invalid
109     */
110    boolean containsValue(Object value);
111
112    /**
113     * Adds the value to the collection associated with the specified key.
114     * <p>
115     * Unlike a normal <code>Map</code> the previous value is not replaced.
116     * Instead the new value is added to the collection stored against the key.
117     * The collection may be a <code>List</code>, <code>Set</code> or other
118     * collection dependent on implementation.
119     *
120     * @param key  the key to store against
121     * @param value  the value to add to the collection at the key
122     * @return typically the value added if the map changed and null if the map did not change
123     * @throws UnsupportedOperationException if the map is unmodifiable
124     * @throws ClassCastException if the key or value is of an invalid type
125     * @throws NullPointerException if the key or value is null and null is invalid
126     * @throws IllegalArgumentException if the key or value is invalid
127     */
128    Object put(K key, Object value);
129
130    /**
131     * Removes all values associated with the specified key.
132     * <p>
133     * Implementations typically return <code>null</code> from a subsequent
134     * <code>get(Object)</code>, however they may choose to return an empty collection.
135     *
136     * @param key  the key to remove values from
137     * @return the <code>Collection</code> of values removed, implementations should
138     *  return <code>null</code> for no mapping found, but may return an empty collection
139     * @throws UnsupportedOperationException if the map is unmodifiable
140     * @throws ClassCastException if the key is of an invalid type
141     * @throws NullPointerException if the key is null and null keys are invalid
142     */
143    Object remove(Object key); // Cannot use remove(K key) as that does not properly implement Map#remove
144
145    /**
146     * Gets a collection containing all the values in the map.
147     * <p>
148     * Implementations typically return a collection containing the combination
149     * of values from all keys.
150     * This cannot be mandated due to backwards compatibility of this interface.
151     *
152     * @return a collection view of the values contained in this map
153     */
154    Collection<Object> values();
155
156}