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 * https://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
18 package org.apache.commons.collections4;
19
20 import java.util.Collection;
21
22 /**
23 * Defines a map that holds a collection of values against each key.
24 * <p>
25 * 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
26 * will return a Collection, holding all the values put to that key.
27 * </p>
28 * <p>
29 * For example:
30 * </p>
31 *
32 * <pre>
33 * MultiMap mhm = new MultiValueMap();
34 * mhm.put(key, "A");
35 * mhm.put(key, "B");
36 * mhm.put(key, "C");
37 * Collection coll = (Collection) mhm.get(key);
38 * </pre>
39 * <p>
40 * {@code coll} will be a collection containing "A", "B", "C".
41 * </p>
42 * <p>
43 * 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
44 * interface as they were defined in the superinterface {@code Map} anyway.
45 * </p>
46 *
47 * @param <K> The type of the keys in this map.
48 * @param <V> The type of the values in this map.
49 * @since 2.0
50 * @deprecated Since 4.1, use {@link MultiValuedMap} instead
51 */
52 @Deprecated
53 public interface MultiMap<K, V> extends IterableMap<K, Object> {
54
55 /**
56 * Checks whether the map contains the value specified.
57 * <p>
58 * Implementations typically check all collections against all keys for the value. 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 are free to declare that they return {@code Collection} subclasses such as
73 * {@code List} or {@code Set}.
74 * </p>
75 * <p>
76 * Implementations typically return {@code null} if no values have been mapped to the key, however the implementation may choose to return an empty
77 * collection.
78 * </p>
79 * <p>
80 * Implementations may choose to return a clone of the internal collection.
81 * </p>
82 *
83 * @param key The key to retrieve.
84 * @return The {@code Collection} of values, implementations should return {@code null} for no mapping, but may return an empty collection.
85 * @throws ClassCastException if the key is of an invalid type.
86 * @throws NullPointerException if the key is null and null keys are invalid.
87 */
88 @Override
89 Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get
90
91 /**
92 * Adds the value to the collection associated with the specified key.
93 * <p>
94 * 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
95 * may be a {@code List}, {@code Set} or other collection dependent on implementation.
96 * </p>
97 *
98 * @param key The key to store against.
99 * @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 }