View Javadoc
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 }