001 /*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.collect;
018
019 import com.google.common.annotations.GwtCompatible;
020
021 import java.util.Collection;
022 import java.util.Map;
023 import java.util.Set;
024
025 import javax.annotation.Nullable;
026
027 /**
028 * A collection similar to a {@code Map}, but which may associate multiple
029 * values with a single key. If you call {@link #put} twice, with the same key
030 * but different values, the multimap contains mappings from the key to both
031 * values.
032 *
033 * <p>The methods {@link #get}, {@link #keySet}, {@link #keys}, {@link #values},
034 * {@link #entries}, and {@link #asMap} return collections that are views of the
035 * multimap. If the multimap is modifiable, updating it can change the contents
036 * of those collections, and updating the collections will change the multimap.
037 * In contrast, {@link #replaceValues} and {@link #removeAll} return collections
038 * that are independent of subsequent multimap changes.
039 *
040 * <p>Depending on the implementation, a multimap may or may not allow duplicate
041 * key-value pairs. In other words, the multimap contents after adding the same
042 * key and value twice varies between implementations. In multimaps allowing
043 * duplicates, the multimap will contain two mappings, and {@code get} will
044 * return a collection that includes the value twice. In multimaps not
045 * supporting duplicates, the multimap will contain a single mapping from the
046 * key to the value, and {@code get} will return a collection that includes the
047 * value once.
048 *
049 * <p>All methods that alter the multimap are optional, and the views returned
050 * by the multimap may or may not be modifiable. When modification isn't
051 * supported, those methods will throw an {@link UnsupportedOperationException}.
052 *
053 * @author Jared Levy
054 * @param <K> the type of keys maintained by this multimap
055 * @param <V> the type of mapped values
056 * @since 2 (imported from Google Collections Library)
057 */
058 @GwtCompatible
059 public interface Multimap<K, V> {
060 // Query Operations
061
062 /** Returns the number of key-value pairs in the multimap. */
063 int size();
064
065 /** Returns {@code true} if the multimap contains no key-value pairs. */
066 boolean isEmpty();
067
068 /**
069 * Returns {@code true} if the multimap contains any values for the specified
070 * key.
071 *
072 * @param key key to search for in multimap
073 */
074 boolean containsKey(@Nullable Object key);
075
076 /**
077 * Returns {@code true} if the multimap contains the specified value for any
078 * key.
079 *
080 * @param value value to search for in multimap
081 */
082 boolean containsValue(@Nullable Object value);
083
084 /**
085 * Returns {@code true} if the multimap contains the specified key-value pair.
086 *
087 * @param key key to search for in multimap
088 * @param value value to search for in multimap
089 */
090 boolean containsEntry(@Nullable Object key, @Nullable Object value);
091
092 // Modification Operations
093
094 /**
095 * Stores a key-value pair in the multimap.
096 *
097 * <p>Some multimap implementations allow duplicate key-value pairs, in which
098 * case {@code put} always adds a new key-value pair and increases the
099 * 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, will
226 * update the underlying multimap. The map does not support {@code setValue()}
227 * on its entries, {@code put}, or {@code putAll}.
228 *
229 * <p>When passed a key that is present in the map, {@code
230 * asMap().get(Object)} has the same behavior as {@link #get}, returning a
231 * live collection. When passed a key that is not present, however, {@code
232 * asMap().get(Object)} returns {@code null} instead of an empty collection.
233 *
234 * @return a map view from a key to its collection of values
235 */
236 Map<K, Collection<V>> asMap();
237
238 // Comparison and hashing
239
240 /**
241 * Compares the specified object with this multimap for equality. Two
242 * multimaps are equal when their map views, as returned by {@link #asMap},
243 * are also equal.
244 *
245 * <p>In general, two multimaps with identical key-value mappings may or may
246 * not be equal, depending on the implementation. For example, two
247 * {@link SetMultimap} instances with the same key-value mappings are equal,
248 * but equality of two {@link ListMultimap} instances depends on the ordering
249 * of the values for each key.
250 *
251 * <p>A non-empty {@link SetMultimap} cannot be equal to a non-empty
252 * {@link ListMultimap}, since their {@link #asMap} views contain unequal
253 * collections as values. However, any two empty multimaps are equal, because
254 * they both have empty {@link #asMap} views.
255 */
256 @Override
257 boolean equals(@Nullable Object obj);
258
259 /**
260 * Returns the hash code for this multimap.
261 *
262 * <p>The hash code of a multimap is defined as the hash code of the map view,
263 * as returned by {@link Multimap#asMap}.
264 */
265 @Override
266 int hashCode();
267 }