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
017package com.google.common.collect;
018
019import static com.google.common.base.Preconditions.checkNotNull;
020import static com.google.common.collect.Iterables.getOnlyElement;
021
022import com.google.common.annotations.GwtCompatible;
023
024import java.io.Serializable;
025import java.util.ArrayList;
026import java.util.Collections;
027import java.util.HashMap;
028import java.util.List;
029import java.util.Map;
030
031import 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
060public 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}