1 /* 2 * Copyright (C) 2007 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.GwtCompatible; 20 21 import java.util.Collection; 22 import java.util.Map; 23 import java.util.Set; 24 25 import javax.annotation.Nullable; 26 27 /** 28 * A collection similar to a {@code Map}, but which may associate multiple 29 * values with a single key. If you call {@link #put} twice, with the same key 30 * but different values, the multimap contains mappings from the key to both 31 * values. 32 * 33 * <p>The methods {@link #get}, {@link #keySet}, {@link #keys}, {@link #values}, 34 * {@link #entries}, and {@link #asMap} return collections that are views of the 35 * multimap. If the multimap is modifiable, updating it can change the contents 36 * of those collections, and updating the collections will change the multimap. 37 * In contrast, {@link #replaceValues} and {@link #removeAll} return collections 38 * that are independent of subsequent multimap changes. 39 * 40 * <p>Depending on the implementation, a multimap may or may not allow duplicate 41 * key-value pairs. In other words, the multimap contents after adding the same 42 * key and value twice varies between implementations. In multimaps allowing 43 * duplicates, the multimap will contain two mappings, and {@code get} will 44 * return a collection that includes the value twice. In multimaps not 45 * supporting duplicates, the multimap will contain a single mapping from the 46 * key to the value, and {@code get} will return a collection that includes the 47 * value once. 48 * 49 * <p>All methods that alter the multimap are optional, and the views returned 50 * by the multimap may or may not be modifiable. When modification isn't 51 * supported, those methods will throw an {@link UnsupportedOperationException}. 52 * 53 * @author Jared Levy 54 * @param <K> the type of keys maintained by this multimap 55 * @param <V> the type of mapped values 56 * @since 2010.01.04 <b>stable</b> (imported from Google Collections Library) 57 */ 58 @GwtCompatible 59 public interface Multimap<K, V> { 60 // Query Operations 61 62 /** Returns the number of key-value pairs in the multimap. */ 63 int size(); 64 65 /** Returns {@code true} if the multimap contains no key-value pairs. */ 66 boolean isEmpty(); 67 68 /** 69 * Returns {@code true} if the multimap contains any values for the specified 70 * key. 71 * 72 * @param key key to search for in multimap 73 */ 74 boolean containsKey(@Nullable Object key); 75 76 /** 77 * Returns {@code true} if the multimap contains the specified value for any 78 * key. 79 * 80 * @param value value to search for in multimap 81 */ 82 boolean containsValue(@Nullable Object value); 83 84 /** 85 * Returns {@code true} if the multimap contains the specified key-value pair. 86 * 87 * @param key key to search for in multimap 88 * @param value value to search for in multimap 89 */ 90 boolean containsEntry(@Nullable Object key, @Nullable Object value); 91 92 // Modification Operations 93 94 /** 95 * Stores a key-value pair in the multimap. 96 * 97 * <p>Some multimap implementations allow duplicate key-value pairs, in which 98 * case {@code put} always adds a new key-value pair and increases the 99 * multimap size by 1. Other implementations prohibit duplicates, and storing 100 * a key-value pair that's already in the multimap has no effect. 101 * 102 * @param key key to store in the multimap 103 * @param value value to store in the multimap 104 * @return {@code true} if the method increased the size of the multimap, or 105 * {@code false} if the multimap already contained the key-value pair and 106 * doesn't allow duplicates 107 */ 108 boolean put(@Nullable K key, @Nullable V value); 109 110 /** 111 * Removes a key-value pair from the multimap. 112 * 113 * @param key key of entry to remove from the multimap 114 * @param value value of entry to remove the multimap 115 * @return {@code true} if the multimap changed 116 */ 117 boolean remove(@Nullable Object key, @Nullable Object value); 118 119 // Bulk Operations 120 121 /** 122 * Stores a collection of values with the same key. 123 * 124 * @param key key to store in the multimap 125 * @param values values to store in the multimap 126 * @return {@code true} if the multimap changed 127 */ 128 boolean putAll(@Nullable K key, Iterable<? extends V> values); 129 130 /** 131 * Copies all of another multimap's key-value pairs into this multimap. The 132 * order in which the mappings are added is determined by 133 * {@code multimap.entries()}. 134 * 135 * @param multimap mappings to store in this multimap 136 * @return {@code true} if the multimap changed 137 */ 138 boolean putAll(Multimap<? extends K, ? extends V> multimap); 139 140 /** 141 * Stores a collection of values with the same key, replacing any existing 142 * values for that key. 143 * 144 * @param key key to store in the multimap 145 * @param values values to store in the multimap 146 * @return the collection of replaced values, or an empty collection if no 147 * values were previously associated with the key. The collection 148 * <i>may</i> be modifiable, but updating it will have no effect on the 149 * multimap. 150 */ 151 Collection<V> replaceValues(@Nullable K key, Iterable<? extends V> values); 152 153 /** 154 * Removes all values associated with a given key. 155 * 156 * @param key key of entries to remove from the multimap 157 * @return the collection of removed values, or an empty collection if no 158 * values were associated with the provided key. The collection 159 * <i>may</i> be modifiable, but updating it will have no effect on the 160 * multimap. 161 */ 162 Collection<V> removeAll(@Nullable Object key); 163 164 /** 165 * Removes all key-value pairs from the multimap. 166 */ 167 void clear(); 168 169 // Views 170 171 /** 172 * Returns a collection view of all values associated with a key. If no 173 * mappings in the multimap have the provided key, an empty collection is 174 * returned. 175 * 176 * <p>Changes to the returned collection will update the underlying multimap, 177 * and vice versa. 178 * 179 * @param key key to search for in multimap 180 * @return the collection of values that the key maps to 181 */ 182 Collection<V> get(@Nullable K key); 183 184 /** 185 * Returns the set of all keys, each appearing once in the returned set. 186 * Changes to the returned set will update the underlying multimap, and vice 187 * versa. 188 * 189 * @return the collection of distinct keys 190 */ 191 Set<K> keySet(); 192 193 /** 194 * Returns a collection, which may contain duplicates, of all keys. The number 195 * of times of key appears in the returned multiset equals the number of 196 * mappings the key has in the multimap. Changes to the returned multiset will 197 * update the underlying multimap, and vice versa. 198 * 199 * @return a multiset with keys corresponding to the distinct keys of the 200 * multimap and frequencies corresponding to the number of values that 201 * each key maps to 202 */ 203 Multiset<K> keys(); 204 205 /** 206 * Returns a collection of all values in the multimap. Changes to the returned 207 * collection will update the underlying multimap, and vice versa. 208 * 209 * @return collection of values, which may include the same value multiple 210 * times if it occurs in multiple mappings 211 */ 212 Collection<V> values(); 213 214 /** 215 * Returns a collection of all key-value pairs. Changes to the returned 216 * collection will update the underlying multimap, and vice versa. The entries 217 * collection does not support the {@code add} or {@code addAll} operations. 218 * 219 * @return collection of map entries consisting of key-value pairs 220 */ 221 Collection<Map.Entry<K, V>> entries(); 222 223 /** 224 * Returns a map view that associates each key with the corresponding values 225 * in the multimap. Changes to the returned map, such as element removal, 226 * will update the underlying multimap. The map does not support 227 * {@code setValue()} on its entries, {@code put}, or {@code putAll}. 228 * 229 * <p>The collections returned by {@code asMap().get(Object)} have the same 230 * behavior as those returned by {@link #get}. 231 * 232 * @return a map view from a key to its collection of values 233 */ 234 Map<K, Collection<V>> asMap(); 235 236 // Comparison and hashing 237 238 /** 239 * Compares the specified object with this multimap for equality. Two 240 * multimaps are equal when their map views, as returned by {@link #asMap}, 241 * are also equal. 242 * 243 * <p>In general, two multimaps with identical key-value mappings may or may 244 * not be equal, depending on the implementation. For example, two 245 * {@link SetMultimap} instances with the same key-value mappings are equal, 246 * but equality of two {@link ListMultimap} instances depends on the ordering 247 * of the values for each key. 248 * 249 * <p>A non-empty {@link SetMultimap} cannot be equal to a non-empty 250 * {@link ListMultimap}, since their {@link #asMap} views contain unequal 251 * collections as values. However, any two empty multimaps are equal, because 252 * they both have empty {@link #asMap} views. 253 */ 254 boolean equals(@Nullable Object obj); 255 256 /** 257 * Returns the hash code for this multimap. 258 * 259 * <p>The hash code of a multimap is defined as the hash code of the map view, 260 * as returned by {@link Multimap#asMap}. 261 */ 262 int hashCode(); 263 } 264
