1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15;
17
18 import java.util.Collection;
19 import java.util.Map;
20
21 /***
22 * Defines a map that holds a collection of values against each key.
23 * <p/>
24 * A <code>MultiMap</code> is a Map with slightly different semantics. Putting a
25 * value into the map will add the value to a Collection at that key. Getting a
26 * value will return a Collection, holding all the values put to that key.
27 * <p/>
28 * For example:
29 * <pre>
30 * MultiMap<Object, String> mhm = new MultiHashMap<Object, String>();
31 * mhm.put(key, "A");
32 * mhm.put(key, "B");
33 * mhm.put(key, "C");
34 * String val = mhm.get(key);
35 * Collection<String> coll = mhm.getAll(key);</pre>
36 * <p/>
37 * <code>val</code> will be the string "C", and <code>coll</code> will be a
38 * string collection containing "A", "B", "C".
39 * <p/>
40 * NOTE: Some methods have been added to this interface solely for documentation
41 * purposes and do not change the interface as they were defined in the
42 * superinterface <code>Map</code> anyway.
43 *
44 * @author Christopher Berry
45 * @author James Strachan
46 * @author Stephen Colebourne
47 * @version $Revision: 1.4 $ $Date: 2004/10/17 01:02:42 $
48 * @since Commons Collections 2.0
49 */
50 public interface MultiMap <K, V> extends Map<K, V>
51 {
52
53 /***
54 * Removes the all values associated with the specified key.
55 * <p/>
56 * Implementations typically must <code>null</code> from a subsequant call
57 * to <code>get(Object)</code>.
58 *
59 * @param key the key to remove a value from
60 *
61 * @return the value removed, which is the most recent value that is mapped
62 * to the specified key, or <code>null</code> if no value is
63 * currently mapped to the specified key.
64 *
65 * @throws UnsupportedOperationException if the map is unmodifiable
66 * @throws ClassCastException if the key is of an inappropriate
67 * type for this map.
68 * @throws NullPointerException if the key is <tt>null</tt> and
69 * this map does not permit
70 * <tt>null</tt> keys.
71 * @see #removeAll(Object) Used to retrieve all values mapped to a
72 * specified key.
73 */
74 V remove(Object key);
75
76 /***
77 * Removes the value associated with the specified key that was most
78 * recently added to the map.
79 * <p/>
80 * The most recently asscciated value mapped to the specified key is removed
81 * from the collection . Other values attached to that key are unaffected.
82 * <p/>
83 * If the last value for a key is removed, a subsequant call to
84 * <code>get(Object)</code> should return <code>null</code>.
85 *
86 * @param key the key to remove from
87 * @param item the item to remove
88 *
89 * @return the value removed (which was passed in), null if nothing removed
90 *
91 * @throws UnsupportedOperationException if the map is unmodifiable
92 * @throws ClassCastException if the key or value is of an
93 * invalid type
94 * @throws NullPointerException if the key or value is null and
95 * null is invalid
96 */
97 V remove(Object key, Object item);
98
99 /***
100 * Removes all values accosiated with a specified key.
101 *
102 * @param key the key whose values should be removed.
103 *
104 * @return the values that were removed, <code>null</code> if nothing
105 * removed
106 *
107 * @throws UnsupportedOperationException if the map is unmodifiable
108 * @throws ClassCastException if the key or value is of an
109 * invalid type
110 * @throws NullPointerException if the key or value is null and
111 * null is invalid
112 */
113 Collection<V> removeAll(Object key);
114
115
116 /***
117 * Gets the number of keys in this map. If the map contains more than
118 * <tt>Integer.MAX_VALUE</tt> keys, returns <tt>Integer.MAX_VALUE</tt>.
119 *
120 * @return the number of keys in this map
121 *
122 * @see #numValues()
123 */
124 int size();
125
126 /***
127 * Gets the number of values in this map. If the map contains more than
128 * <tt>Integer.MAX_VALUE</tt> values, returns <tt>Integer.MAX_VALUE</tt>.
129 *
130 * @return the total number of values in this map.
131 *
132 * @see #size()
133 */
134 int numValues();
135
136 /***
137 * Gets the value associated with the specified key that was most recently
138 * added to the map.
139 *
140 * @param key the key to retrieve
141 *
142 * @return the most recent value that was mapped to the specified key, or
143 * <code>null</code> if no value is currently mapped to the
144 * specified key. Note though that a key may also be legitimately
145 * mapped to <code>null</code>.
146 *
147 * @throws ClassCastException if the key is of an inappropriate type for
148 * this map.
149 * @throws NullPointerException if the key is <tt>null</tt> and this map
150 * does not permit <tt>null</tt> keys.
151 * @see #getAll(Object) Used to retrieve all values mapped to a specified
152 * key.
153 */
154 V get(Object key);
155
156 /***
157 * Returns all values associated with the specified key. Changes to the
158 * collection should be reflected in the multi map, and vice-versa.
159 *
160 * @param key the key to retrieve
161 *
162 * @return All values that are currently associated with the specified key.
163 *
164 * @throws ClassCastException if the key is of an inappropriate type for
165 * this map.
166 * @throws NullPointerException if the key is <tt>null</tt> and this map
167 * does not permit <tt>null</tt> keys.
168 * @see #get(Object) Used to retrieve the value most recently mapped to a
169 * specified key.
170 */
171 Collection<V> getAll(Object key);
172
173 /***
174 * Returns <tt>true</tt> if this map contains a mapping for the specified
175 * key.
176 * <p/>
177 * Note that unlike the superclass, this method should neither throw a
178 * <code>ClassCastException</code> nor a <code>NullPointerException</code>
179 * if the key is somehow unsuitable. Instead, it will simply return
180 * <code>false</code>.
181 *
182 * @param key key whose presence in this map is to be tested.
183 *
184 * @return <tt>true</tt> if this map contains a mapping for the specified
185 * key.
186 */
187 boolean containsKey(Object key);
188
189 /***
190 * Checks whether the map contains the value specified, mapped against any
191 * key.
192 * <p/>
193 * Note that unlike the superclass, this method should neither throw a
194 * <code>ClassCastException</code> nor a <code>NullPointerException</code>
195 * if the value is somehow unsuitable. Instead, it will simply return
196 * <code>false</code>.
197 *
198 * @param value the value to search for
199 *
200 * @return true if the map contains the value
201 *
202 * @see #containsValue(Object, Object)
203 */
204 boolean containsValue(Object value);
205
206 /***
207 * Checkes whether the map contains the specified key mapped to the
208 * specified value.
209 *
210 * @param key The key to search for.
211 * @param value The value to search for.
212 *
213 * @return true if the map contains the specified key mapped to the
214 * specified value.
215 *
216 * @see #containsValue(Object)
217 */
218 boolean containsValue(Object key, Object value);
219
220 /***
221 * Adds the value to the collection associated with the specified key.
222 * <p/>
223 * Unlike a normal <code>Map</code> the previous value is not replaced.
224 * Instead the new value is added to the collection stored against the key.
225 * The collection may be a <code>List</code>, <code>Set</code> or other
226 * collection dependent on implementation.
227 *
228 * @param key the key to store against
229 * @param value the value to add to the collection at the key
230 *
231 * @return typically the value added if the map changed and null if the map
232 * did not change
233 *
234 * @throws UnsupportedOperationException if the map is unmodifiable
235 * @throws NullPointerException if the key or value is null and
236 * null is invalid
237 * @throws IllegalArgumentException if the key or value is invalid for
238 * the map in any other way.
239 */
240 V put(K key, V value);
241
242 /***
243 * Gets a collection containing all the values in the map.
244 * <p/>
245 * Inplementations typically return a collection containing the combination
246 * of values from all keys. This cannot be mandated due to backwards
247 * compatability of this interface.
248 *
249 * @return a collection view of the values contained in this map
250 */
251 Collection<V> values();
252 }