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 }