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