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.collections;
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</code> 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 * For example:
29 * <pre>
30 * MultiMap mhm = new MultiValueMap();
31 * mhm.put(key, "A");
32 * mhm.put(key, "B");
33 * mhm.put(key, "C");
34 * Collection coll = (Collection) mhm.get(key);</pre>
35 * <p>
36 * <code>coll</code> will be a collection containing "A", "B", "C".
37 * <p>
38 * NOTE: Additional methods were added to this interface in Commons Collections 3.1.
39 * These were added solely for documentation purposes and do not change the interface
40 * as they were defined in the superinterface <code>Map</code> anyway.
41 *
42 * @since 2.0
43 * @version $Id: MultiMap.java 1451877 2013-03-02 11:56:07Z tn $
44 */
45 public interface MultiMap<K, V> extends IterableMap<K, Object> {
46
47 /**
48 * Removes a specific value from map.
49 * <p>
50 * The item is removed from the collection mapped to the specified key.
51 * Other values attached to that key are unaffected.
52 * <p>
53 * If the last value for a key is removed, implementations typically
54 * return <code>null</code> from a subsequant <code>get(Object)</code>, however
55 * they may choose to return an empty collection.
56 *
57 * @param key the key to remove from
58 * @param item the item to remove
59 * @return the value removed (which was passed in), null if nothing removed
60 * @throws UnsupportedOperationException if the map is unmodifiable
61 * @throws ClassCastException if the key or value is of an invalid type
62 * @throws NullPointerException if the key or value is null and null is invalid
63 */
64 public V remove(K key, V item);
65
66 //-----------------------------------------------------------------------
67 /**
68 * Gets the number of keys in this map.
69 * <p>
70 * Implementations typically return only the count of keys in the map
71 * This cannot be mandated due to backwards compatability of this interface.
72 *
73 * @return the number of key-collection mappings in this map
74 */
75 int size();
76
77 /**
78 * Gets the collection of values associated with the specified key.
79 * <p>
80 * The returned value will implement <code>Collection</code>. Implementations
81 * are free to declare that they return <code>Collection</code> subclasses
82 * such as <code>List</code> or <code>Set</code>.
83 * <p>
84 * Implementations typically return <code>null</code> if no values have
85 * been mapped to the key, however the implementation may choose to
86 * return an empty collection.
87 * <p>
88 * Implementations may choose to return a clone of the internal collection.
89 *
90 * @param key the key to retrieve
91 * @return the <code>Collection</code> of values, implementations should
92 * return <code>null</code> for no mapping, but may return an empty collection
93 * @throws ClassCastException if the key is of an invalid type
94 * @throws NullPointerException if the key is null and null keys are invalid
95 */
96 Object get(Object key); // Cannot use get(K key) as that does not properly implement Map#get
97
98 /**
99 * Checks whether the map contains the value specified.
100 * <p>
101 * Implementations typically check all collections against all keys for the value.
102 * This cannot be mandated due to backwards compatability of this interface.
103 *
104 * @param value the value to search for
105 * @return true if the map contains the value
106 * @throws ClassCastException if the value is of an invalid type
107 * @throws NullPointerException if the value is null and null value are invalid
108 */
109 boolean containsValue(Object value);
110
111 /**
112 * Adds the value to the collection associated with the specified key.
113 * <p>
114 * Unlike a normal <code>Map</code> the previous value is not replaced.
115 * Instead the new value is added to the collection stored against the key.
116 * The collection may be a <code>List</code>, <code>Set</code> or other
117 * collection dependent on implementation.
118 *
119 * @param key the key to store against
120 * @param value the value to add to the collection at the key
121 * @return typically the value added if the map changed and null if the map did not change
122 * @throws UnsupportedOperationException if the map is unmodifiable
123 * @throws ClassCastException if the key or value is of an invalid type
124 * @throws NullPointerException if the key or value is null and null is invalid
125 * @throws IllegalArgumentException if the key or value is invalid
126 */
127 Object put(K key, Object value);
128
129 /**
130 * Removes all values associated with the specified key.
131 * <p>
132 * Implementations typically return <code>null</code> from a subsequant
133 * <code>get(Object)</code>, however they may choose to return an empty collection.
134 *
135 * @param key the key to remove values from
136 * @return the <code>Collection</code> of values removed, implementations should
137 * return <code>null</code> for no mapping found, but may return an empty collection
138 * @throws UnsupportedOperationException if the map is unmodifiable
139 * @throws ClassCastException if the key is of an invalid type
140 * @throws NullPointerException if the key is null and null keys are invalid
141 */
142 Object remove(Object key); // Cannot use remove(K key) as that does not properly implement Map#remove
143
144 /**
145 * Gets a collection containing all the values in the map.
146 * <p>
147 * Inplementations typically return a collection containing the combination
148 * of values from all keys.
149 * This cannot be mandated due to backwards compatability of this interface.
150 *
151 * @return a collection view of the values contained in this map
152 */
153 Collection<Object> values();
154
155 }