1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4;
18
19 import java.util.Collection;
20
21 /**
22 * Defines a map that holds a collection of values against each key.
23 * <p>
24 * A {@code MultiMap} is a Map with slightly different semantics.
25 * Putting a value into the map will add the value to a Collection at that key.
26 * Getting a value will return a Collection, holding all the values put to that key.
27 * </p>
28 * <p>
29 * For example:
30 * </p>
31 * <pre>
32 * MultiMap mhm = new MultiValueMap();
33 * mhm.put(key, "A");
34 * mhm.put(key, "B");
35 * mhm.put(key, "C");
36 * Collection coll = (Collection) mhm.get(key);</pre>
37 * <p>
38 * {@code coll} will be a collection containing "A", "B", "C".
39 * </p>
40 * <p>
41 * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
42 * These were added solely for documentation purposes and do not change the interface
43 * as they were defined in the superinterface {@code Map} anyway.
44 * </p>
45 *
46 * @param <K> the type of the keys in this map
47 * @param <V> the type of the values in this map
48 * @since 2.0
49 * @deprecated since 4.1, use {@link MultiValuedMap} instead
50 */
51 @Deprecated
52 public interface MultiMap<K, V> extends IterableMap<K, Object> {
53
54 /**
55 * Checks whether the map contains the value specified.
56 * <p>
57 * Implementations typically check all collections against all keys for the value.
58 * This cannot be mandated due to backwards compatibility of this interface.
59 * </p>
60 *
61 * @param value the value to search for
62 * @return true if the map contains the value
63 * @throws ClassCastException if the value is of an invalid type
64 * @throws NullPointerException if the value is null and null value are invalid
65 */
66 @Override
67 boolean containsValue(Object value);
68
69 /**
70 * Gets the collection of values associated with the specified key.
71 * <p>
72 * The returned value will implement {@code Collection}. Implementations
73 * are free to declare that they return {@code Collection} subclasses
74 * such as {@code List} or {@code Set}.
75 * </p>
76 * <p>
77 * Implementations typically return {@code null} if no values have
78 * been mapped to the key, however the implementation may choose to
79 * return an empty collection.
80 * </p>
81 * <p>
82 * Implementations may choose to return a clone of the internal collection.
83 * </p>
84 *
85 * @param key the key to retrieve
86 * @return the {@code Collection} of values, implementations should
87 * return {@code null} for no mapping, but may return an empty collection
88 * @throws ClassCastException if the key is of an invalid type
89 * @throws NullPointerException if the key is null and null keys are invalid
90 */
91 @Override
92 Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get
93
94 /**
95 * Adds the value to the collection associated with the specified key.
96 * <p>
97 * Unlike a normal {@code Map} the previous value is not replaced.
98 * Instead, the new value is added to the collection stored against the key.
99 * The collection may be a {@code List}, {@code Set} or other
100 * collection dependent on implementation.
101 * </p>
102 *
103 * @param key the key to store against
104 * @param value the value to add to the collection at the key
105 * @return typically the value added if the map changed and null if the map did not change
106 * @throws UnsupportedOperationException if the map is unmodifiable
107 * @throws ClassCastException if the key or value is of an invalid type
108 * @throws NullPointerException if the key or value is null and null is invalid
109 * @throws IllegalArgumentException if the key or value is invalid
110 */
111 @Override
112 Object put(K key, Object value);
113
114 /**
115 * Removes all values associated with the specified key.
116 * <p>
117 * Implementations typically return {@code null} from a subsequent
118 * {@code get(Object)}, however they may choose to return an empty collection.
119 * </p>
120 *
121 * @param key the key to remove values from
122 * @return the {@code Collection} of values removed, implementations should
123 * return {@code null} for no mapping found, but may return an empty collection
124 * @throws UnsupportedOperationException if the map is unmodifiable
125 * @throws ClassCastException if the key is of an invalid type
126 * @throws NullPointerException if the key is null and null keys are invalid
127 */
128 @Override
129 Object remove(Object key); // Cannot use remove(K key) as that does not properly implement Map#remove
130
131 /**
132 * Removes a specific value from map.
133 * <p>
134 * The item is removed from the collection mapped to the specified key.
135 * Other values attached to that key are unaffected.
136 * </p>
137 * <p>
138 * If the last value for a key is removed, implementations typically
139 * return {@code null} from a subsequent {@code get(Object)}, however
140 * they may choose to return an empty collection.
141 * </p>
142 *
143 * @param key the key to remove from
144 * @param item the item to remove
145 * @return {@code true} if the mapping was removed, {@code false} otherwise
146 * @throws UnsupportedOperationException if the map is unmodifiable
147 * @throws ClassCastException if the key or value is of an invalid type
148 * @throws NullPointerException if the key or value is null and null is invalid
149 * @since 4.0 (signature in previous releases: V remove(K, V))
150 */
151 boolean removeMapping(K key, V item);
152
153 /**
154 * Gets the number of keys in this map.
155 * <p>
156 * Implementations typically return only the count of keys in the map
157 * This cannot be mandated due to backwards compatibility of this interface.
158 * </p>
159 *
160 * @return the number of key-collection mappings in this map
161 */
162 @Override
163 int size();
164
165 /**
166 * Gets a collection containing all the values in the map.
167 * <p>
168 * Implementations typically return a collection containing the combination
169 * of values from all keys.
170 * This cannot be mandated due to backwards compatibility of this interface.
171 * </p>
172 *
173 * @return a collection view of the values contained in this map
174 */
175 @Override
176 Collection<Object> values();
177
178 }