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    }