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