001 /*
002 * Copyright (C) 2008 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 static com.google.common.base.Preconditions.checkNotNull;
020 import static com.google.common.collect.Iterables.getOnlyElement;
021
022 import com.google.common.annotations.GwtCompatible;
023
024 import java.io.Serializable;
025 import java.util.ArrayList;
026 import java.util.Collections;
027 import java.util.HashMap;
028 import java.util.List;
029 import java.util.Map;
030
031 import javax.annotation.Nullable;
032
033 /**
034 * An immutable, hash-based {@link Map} with reliable user-specified iteration
035 * order. Does not permit null keys or values.
036 *
037 * <p>Unlike {@link Collections#unmodifiableMap}, which is a <i>view</i> of a
038 * separate map which can still change, an instance of {@code ImmutableMap}
039 * contains its own data and will <i>never</i> change. {@code ImmutableMap} is
040 * convenient for {@code public static final} maps ("constant maps") and also
041 * lets you easily make a "defensive copy" of a map provided to your class by a
042 * caller.
043 *
044 * <p><i>Performance notes:</i> unlike {@link HashMap}, {@code ImmutableMap} is
045 * not optimized for element types that have slow {@link Object#equals} or
046 * {@link Object#hashCode} implementations. You can get better performance by
047 * having your element type cache its own hash codes, and by making use of the
048 * cached values to short-circuit a slow {@code equals} algorithm.
049 *
050 * <p>See the Guava User Guide article on <a href=
051 * "http://code.google.com/p/guava-libraries/wiki/ImmutableCollectionsExplained">
052 * immutable collections</a>.
053 *
054 * @author Jesse Wilson
055 * @author Kevin Bourrillion
056 * @since 2.0 (imported from Google Collections Library)
057 */
058 @GwtCompatible(serializable = true, emulated = true)
059 @SuppressWarnings("serial") // we're overriding default serialization
060 public abstract class ImmutableMap<K, V> implements Map<K, V>, Serializable {
061 /**
062 * Returns the empty map. This map behaves and performs comparably to
063 * {@link Collections#emptyMap}, and is preferable mainly for consistency
064 * and maintainability of your code.
065 */
066 // Casting to any type is safe because the set will never hold any elements.
067 @SuppressWarnings("unchecked")
068 public static <K, V> ImmutableMap<K, V> of() {
069 return (ImmutableMap<K, V>) EmptyImmutableMap.INSTANCE;
070 }
071
072 /**
073 * Returns an immutable map containing a single entry. This map behaves and
074 * performs comparably to {@link Collections#singletonMap} but will not accept
075 * a null key or value. It is preferable mainly for consistency and
076 * maintainability of your code.
077 */
078 public static <K, V> ImmutableMap<K, V> of(K k1, V v1) {
079 return new SingletonImmutableMap<K, V>(
080 checkNotNull(k1), checkNotNull(v1));
081 }
082
083 /**
084 * Returns an immutable map containing the given entries, in order.
085 *
086 * @throws IllegalArgumentException if duplicate keys are provided
087 */
088 public static <K, V> ImmutableMap<K, V> of(K k1, V v1, K k2, V v2) {
089 return new RegularImmutableMap<K, V>(entryOf(k1, v1), entryOf(k2, v2));
090 }
091
092 /**
093 * Returns an immutable map containing the given entries, in order.
094 *
095 * @throws IllegalArgumentException if duplicate keys are provided
096 */
097 public static <K, V> ImmutableMap<K, V> of(
098 K k1, V v1, K k2, V v2, K k3, V v3) {
099 return new RegularImmutableMap<K, V>(
100 entryOf(k1, v1), entryOf(k2, v2), entryOf(k3, v3));
101 }
102
103 /**
104 * Returns an immutable map containing the given entries, in order.
105 *
106 * @throws IllegalArgumentException if duplicate keys are provided
107 */
108 public static <K, V> ImmutableMap<K, V> of(
109 K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) {
110 return new RegularImmutableMap<K, V>(
111 entryOf(k1, v1), entryOf(k2, v2), entryOf(k3, v3), entryOf(k4, v4));
112 }
113
114 /**
115 * Returns an immutable map containing the given entries, in order.
116 *
117 * @throws IllegalArgumentException if duplicate keys are provided
118 */
119 public static <K, V> ImmutableMap<K, V> of(
120 K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5) {
121 return new RegularImmutableMap<K, V>(entryOf(k1, v1),
122 entryOf(k2, v2), entryOf(k3, v3), entryOf(k4, v4), entryOf(k5, v5));
123 }
124
125 // looking for of() with > 5 entries? Use the builder instead.
126
127 /**
128 * Returns a new builder. The generated builder is equivalent to the builder
129 * created by the {@link Builder} constructor.
130 */
131 public static <K, V> Builder<K, V> builder() {
132 return new Builder<K, V>();
133 }
134
135 /**
136 * Verifies that {@code key} and {@code value} are non-null, and returns a new
137 * immutable entry with those values.
138 *
139 * <p>A call to {@link Map.Entry#setValue} on the returned entry will always
140 * throw {@link UnsupportedOperationException}.
141 */
142 static <K, V> Entry<K, V> entryOf(K key, V value) {
143 checkNotNull(key, "null key in entry: null=%s", value);
144 checkNotNull(value, "null value in entry: %s=null", key);
145 return Maps.immutableEntry(key, value);
146 }
147
148 /**
149 * A builder for creating immutable map instances, especially {@code public
150 * static final} maps ("constant maps"). Example: <pre> {@code
151 *
152 * static final ImmutableMap<String, Integer> WORD_TO_INT =
153 * new ImmutableMap.Builder<String, Integer>()
154 * .put("one", 1)
155 * .put("two", 2)
156 * .put("three", 3)
157 * .build();}</pre>
158 *
159 * For <i>small</i> immutable maps, the {@code ImmutableMap.of()} methods are
160 * even more convenient.
161 *
162 * <p>Builder instances can be reused - it is safe to call {@link #build}
163 * multiple times to build multiple maps in series. Each map is a superset of
164 * the maps created before it.
165 *
166 * @since 2.0 (imported from Google Collections Library)
167 */
168 public static class Builder<K, V> {
169 final ArrayList<Entry<K, V>> entries = Lists.newArrayList();
170
171 /**
172 * Creates a new builder. The returned builder is equivalent to the builder
173 * generated by {@link ImmutableMap#builder}.
174 */
175 public Builder() {}
176
177 /**
178 * Associates {@code key} with {@code value} in the built map. Duplicate
179 * keys are not allowed, and will cause {@link #build} to fail.
180 */
181 public Builder<K, V> put(K key, V value) {
182 entries.add(entryOf(key, value));
183 return this;
184 }
185
186 /**
187 * Adds the given {@code entry} to the map, making it immutable if
188 * necessary. Duplicate keys are not allowed, and will cause {@link #build}
189 * to fail.
190 *
191 * @since 11.0
192 */
193 public Builder<K, V> put(Entry<? extends K, ? extends V> entry) {
194 K key = entry.getKey();
195 V value = entry.getValue();
196 if (entry instanceof ImmutableEntry) {
197 checkNotNull(key);
198 checkNotNull(value);
199 @SuppressWarnings("unchecked") // all supported methods are covariant
200 Entry<K, V> immutableEntry = (Entry<K, V>) entry;
201 entries.add(immutableEntry);
202 } else {
203 // Directly calling entryOf(entry.getKey(), entry.getValue()) can cause
204 // compilation error in Eclipse.
205 entries.add(entryOf(key, value));
206 }
207 return this;
208 }
209
210 /**
211 * Associates all of the given map's keys and values in the built map.
212 * Duplicate keys are not allowed, and will cause {@link #build} to fail.
213 *
214 * @throws NullPointerException if any key or value in {@code map} is null
215 */
216 public Builder<K, V> putAll(Map<? extends K, ? extends V> map) {
217 entries.ensureCapacity(entries.size() + map.size());
218 for (Entry<? extends K, ? extends V> entry : map.entrySet()) {
219 put(entry.getKey(), entry.getValue());
220 }
221 return this;
222 }
223
224 /*
225 * TODO(kevinb): Should build() and the ImmutableBiMap & ImmutableSortedMap
226 * versions throw an IllegalStateException instead?
227 */
228
229 /**
230 * Returns a newly-created immutable map.
231 *
232 * @throws IllegalArgumentException if duplicate keys were added
233 */
234 public ImmutableMap<K, V> build() {
235 return fromEntryList(entries);
236 }
237
238 private static <K, V> ImmutableMap<K, V> fromEntryList(
239 List<Entry<K, V>> entries) {
240 int size = entries.size();
241 switch (size) {
242 case 0:
243 return of();
244 case 1:
245 return new SingletonImmutableMap<K, V>(getOnlyElement(entries));
246 default:
247 Entry<?, ?>[] entryArray
248 = entries.toArray(new Entry<?, ?>[entries.size()]);
249 return new RegularImmutableMap<K, V>(entryArray);
250 }
251 }
252 }
253
254 /**
255 * Returns an immutable map containing the same entries as {@code map}. If
256 * {@code map} somehow contains entries with duplicate keys (for example, if
257 * it is a {@code SortedMap} whose comparator is not <i>consistent with
258 * equals</i>), the results of this method are undefined.
259 *
260 * <p>Despite the method name, this method attempts to avoid actually copying
261 * the data when it is safe to do so. The exact circumstances under which a
262 * copy will or will not be performed are undocumented and subject to change.
263 *
264 * @throws NullPointerException if any key or value in {@code map} is null
265 */
266 public static <K, V> ImmutableMap<K, V> copyOf(
267 Map<? extends K, ? extends V> map) {
268 if ((map instanceof ImmutableMap) && !(map instanceof ImmutableSortedMap)) {
269 // TODO(user): Make ImmutableMap.copyOf(immutableBiMap) call copyOf()
270 // on the ImmutableMap delegate(), rather than the bimap itself
271
272 @SuppressWarnings("unchecked") // safe since map is not writable
273 ImmutableMap<K, V> kvMap = (ImmutableMap<K, V>) map;
274 if (!kvMap.isPartialView()) {
275 return kvMap;
276 }
277 }
278
279 @SuppressWarnings("unchecked") // we won't write to this array
280 Entry<K, V>[] entries = map.entrySet().toArray(new Entry[0]);
281 switch (entries.length) {
282 case 0:
283 return of();
284 case 1:
285 return new SingletonImmutableMap<K, V>(entryOf(
286 entries[0].getKey(), entries[0].getValue()));
287 default:
288 for (int i = 0; i < entries.length; i++) {
289 K k = entries[i].getKey();
290 V v = entries[i].getValue();
291 entries[i] = entryOf(k, v);
292 }
293 return new RegularImmutableMap<K, V>(entries);
294 }
295 }
296
297 ImmutableMap() {}
298
299 /**
300 * Guaranteed to throw an exception and leave the map unmodified.
301 *
302 * @throws UnsupportedOperationException always
303 */
304 @Override
305 public final V put(K k, V v) {
306 throw new UnsupportedOperationException();
307 }
308
309 /**
310 * Guaranteed to throw an exception and leave the map unmodified.
311 *
312 * @throws UnsupportedOperationException always
313 */
314 @Override
315 public final V remove(Object o) {
316 throw new UnsupportedOperationException();
317 }
318
319 /**
320 * Guaranteed to throw an exception and leave the map unmodified.
321 *
322 * @throws UnsupportedOperationException always
323 */
324 @Override
325 public final void putAll(Map<? extends K, ? extends V> map) {
326 throw new UnsupportedOperationException();
327 }
328
329 /**
330 * Guaranteed to throw an exception and leave the map unmodified.
331 *
332 * @throws UnsupportedOperationException always
333 */
334 @Override
335 public final void clear() {
336 throw new UnsupportedOperationException();
337 }
338
339 @Override
340 public boolean isEmpty() {
341 return size() == 0;
342 }
343
344 @Override
345 public boolean containsKey(@Nullable Object key) {
346 return get(key) != null;
347 }
348
349 @Override
350 public boolean containsValue(@Nullable Object value) {
351 return value != null && Maps.containsValueImpl(this, value);
352 }
353
354 // Overriding to mark it Nullable
355 @Override
356 public abstract V get(@Nullable Object key);
357
358 private transient ImmutableSet<Entry<K, V>> entrySet;
359
360 /**
361 * Returns an immutable set of the mappings in this map. The entries are in
362 * the same order as the parameters used to build this map.
363 */
364 @Override
365 public ImmutableSet<Entry<K, V>> entrySet() {
366 ImmutableSet<Entry<K, V>> result = entrySet;
367 return (result == null) ? entrySet = createEntrySet() : result;
368 }
369
370 abstract ImmutableSet<Entry<K, V>> createEntrySet();
371
372 private transient ImmutableSet<K> keySet;
373
374 /**
375 * Returns an immutable set of the keys in this map. These keys are in
376 * the same order as the parameters used to build this map.
377 */
378 @Override
379 public ImmutableSet<K> keySet() {
380 ImmutableSet<K> result = keySet;
381 return (result == null) ? keySet = createKeySet() : result;
382 }
383
384 ImmutableSet<K> createKeySet() {
385 return new ImmutableMapKeySet<K, V>(entrySet()) {
386 @Override ImmutableMap<K, V> map() {
387 return ImmutableMap.this;
388 }
389 };
390 }
391
392 private transient ImmutableCollection<V> values;
393
394 /**
395 * Returns an immutable collection of the values in this map. The values are
396 * in the same order as the parameters used to build this map.
397 */
398 @Override
399 public ImmutableCollection<V> values() {
400 ImmutableCollection<V> result = values;
401 return (result == null) ? values = createValues() : result;
402 }
403
404 ImmutableCollection<V> createValues() {
405 return new ImmutableMapValues<K, V>() {
406 @Override ImmutableMap<K, V> map() {
407 return ImmutableMap.this;
408 }
409 };
410 }
411
412 @Override public boolean equals(@Nullable Object object) {
413 return Maps.equalsImpl(this, object);
414 }
415
416 abstract boolean isPartialView();
417
418 @Override public int hashCode() {
419 // not caching hash code since it could change if map values are mutable
420 // in a way that modifies their hash codes
421 return entrySet().hashCode();
422 }
423
424 @Override public String toString() {
425 return Maps.toStringImpl(this);
426 }
427
428 /**
429 * Serialized type for all ImmutableMap instances. It captures the logical
430 * contents and they are reconstructed using public factory methods. This
431 * ensures that the implementation types remain as implementation details.
432 */
433 static class SerializedForm implements Serializable {
434 private final Object[] keys;
435 private final Object[] values;
436 SerializedForm(ImmutableMap<?, ?> map) {
437 keys = new Object[map.size()];
438 values = new Object[map.size()];
439 int i = 0;
440 for (Entry<?, ?> entry : map.entrySet()) {
441 keys[i] = entry.getKey();
442 values[i] = entry.getValue();
443 i++;
444 }
445 }
446 Object readResolve() {
447 Builder<Object, Object> builder = new Builder<Object, Object>();
448 return createMap(builder);
449 }
450 Object createMap(Builder<Object, Object> builder) {
451 for (int i = 0; i < keys.length; i++) {
452 builder.put(keys[i], values[i]);
453 }
454 return builder.build();
455 }
456 private static final long serialVersionUID = 0;
457 }
458
459 Object writeReplace() {
460 return new SerializedForm(this);
461 }
462 }