--- old/src/java.base/share/classes/java/util/Map.java 2015-11-05 17:45:24.000000000 -0800 +++ new/src/java.base/share/classes/java/util/Map.java 2015-11-05 17:45:24.000000000 -0800 @@ -110,6 +110,23 @@ * Implementations may optionally handle the self-referential scenario, however * most current implementations do not do so. * + *

Immutable Map Factory Methods

+ *

The {@link Map#of() Map.of()} and + * {@link Map#ofEntries(Map.Entry...) Map.ofEntries()} + * factory methods provide a convenient way to create immutable maps. + * The {@code Map} + * instances created by these methods have the following characteristics: + * + *

+ * *

This interface is a member of the * * Java Collections Framework. @@ -1233,4 +1250,452 @@ } return newValue; } + + /** + * Creates an immutable map containing zero mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @return the newly created map + * + * @since 1.9 + */ + static Map of() { + return Collections.emptyMap(); + } + + /** + * Creates an immutable map containing a single mapping. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the mapping's key + * @param v1 the mapping's value + * @return the newly created map + * @throws NullPointerException if the key or the value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1) { + return Collections.singletonMap(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + } + + /** + * Creates an immutable map containing two mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @return the newly created map + * @throws IllegalArgumentException if the keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2) { + Map map = new HashMap<>(3); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + if (map.size() != 2) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing three mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3) { + Map map = new HashMap<>(5); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + if (map.size() != 3) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing four mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) { + Map map = new HashMap<>(6); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + if (map.size() != 4) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing five mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @param k5 the fifth mapping's key + * @param v5 the fifth mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5) { + Map map = new HashMap<>(7); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5)); + if (map.size() != 5) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing six mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @param k5 the fifth mapping's key + * @param v5 the fifth mapping's value + * @param k6 the sixth mapping's key + * @param v6 the sixth mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, + K k6, V v6) { + Map map = new HashMap<>(9); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5)); + map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6)); + if (map.size() != 6) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing seven mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @param k5 the fifth mapping's key + * @param v5 the fifth mapping's value + * @param k6 the sixth mapping's key + * @param v6 the sixth mapping's value + * @param k7 the seventh mapping's key + * @param v7 the seventh mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, + K k6, V v6, K k7, V v7) { + Map map = new HashMap<>(10); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5)); + map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6)); + map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7)); + if (map.size() != 7) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing eight mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @param k5 the fifth mapping's key + * @param v5 the fifth mapping's value + * @param k6 the sixth mapping's key + * @param v6 the sixth mapping's value + * @param k7 the seventh mapping's key + * @param v7 the seventh mapping's value + * @param k8 the eighth mapping's key + * @param v8 the eighth mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, + K k6, V v6, K k7, V v7, K k8, V v8) { + Map map = new HashMap<>(11); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5)); + map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6)); + map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7)); + map.put(Objects.requireNonNull(k8), Objects.requireNonNull(v8)); + if (map.size() != 8) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing nine mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @param k5 the fifth mapping's key + * @param v5 the fifth mapping's value + * @param k6 the sixth mapping's key + * @param v6 the sixth mapping's value + * @param k7 the seventh mapping's key + * @param v7 the seventh mapping's value + * @param k8 the eighth mapping's key + * @param v8 the eighth mapping's value + * @param k9 the ninth mapping's key + * @param v9 the ninth mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, + K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9) { + Map map = new HashMap<>(13); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5)); + map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6)); + map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7)); + map.put(Objects.requireNonNull(k8), Objects.requireNonNull(v8)); + map.put(Objects.requireNonNull(k9), Objects.requireNonNull(v9)); + if (map.size() != 9) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing ten mappings. + * See Immutable Map Factory Methods for details. + * + * @param the map's key type + * @param the map's value type + * @param k1 the first mapping's key + * @param v1 the first mapping's value + * @param k2 the second mapping's key + * @param v2 the second mapping's value + * @param k3 the third mapping's key + * @param v3 the third mapping's value + * @param k4 the fourth mapping's key + * @param v4 the fourth mapping's value + * @param k5 the fifth mapping's key + * @param v5 the fifth mapping's value + * @param k6 the sixth mapping's key + * @param v6 the sixth mapping's value + * @param k7 the seventh mapping's key + * @param v7 the seventh mapping's value + * @param k8 the eighth mapping's key + * @param v8 the eighth mapping's value + * @param k9 the ninth mapping's key + * @param v9 the ninth mapping's value + * @param k10 the tenth mapping's key + * @param v10 the tenth mapping's value + * @return the newly created map + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any key or value is null + * + * @since 1.9 + */ + static Map of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, + K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10) { + Map map = new HashMap<>(14); + map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1)); + map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2)); + map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3)); + map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4)); + map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5)); + map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6)); + map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7)); + map.put(Objects.requireNonNull(k8), Objects.requireNonNull(v8)); + map.put(Objects.requireNonNull(k9), Objects.requireNonNull(v9)); + map.put(Objects.requireNonNull(k10), Objects.requireNonNull(v10)); + if (map.size() != 10) { + throw new IllegalArgumentException("duplicate keys"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable map containing keys and values from the given entries. + * + * @apiNote + * It is convenient to create the map entries using the {@link Map#entry Map.entry()} method. + * For example, + * + *

{@code
+     *     import static java.util.Map.entry;
+     * 
+     *     Map map = Map.ofEntries(
+     *         entry(1, "a"),
+     *         entry(2, "b"),
+     *         entry(3, "c"),
+     *         ...
+     *         entry(26, "z"));
+     * }
+ * + * @param the map's key type + * @param the map's value type + * @param entries the keys and values with which the map is populated + * @return the newly created {@code Map} + * @throws IllegalArgumentException if any keys are duplicates + * @throws NullPointerException if any entry, key, or value is null + * + * @see Map#entry Map.entry() + * @since 1.9 + */ + @SafeVarargs + @SuppressWarnings("varargs") + static Map ofEntries(Entry... entries) { + Map map = new HashMap<>(entries.length * 4 / 3 + 1); + for (Entry e : entries) { + Objects.requireNonNull(e); + map.put(Objects.requireNonNull(e.getKey()), Objects.requireNonNull(e.getValue())); + } + if (map.size() != entries.length) { + throw new IllegalArgumentException("duplicate elements"); + } + return Collections.unmodifiableMap(map); + } + + /** + * Creates an immutable {@link Entry} containing the given key and value. + * These entries are suitable for populating {@code Map} instances using the + * {@link Map#ofEntries Map.ofEntries()} method. + * The key and the value must not be null. Calling {@link Entry#setValue Entry.setValue()} + * on the returned {@code Entry} results in an {@code UnsupportedOperationException} + * being thrown. The returned {@code Entry} is not guaranteed to be serializable. + * + *

The returned {@code Entry} is a value-based + * class; use of identity-sensitive operations (including reference equality + * ({@code ==}), identity hash code, or synchronization) on any returned values + * may have unpredictable results and should be avoided. + * + * @param the key's type + * @param the value's type + * @param k the key + * @param v the value + * @return the new {@code Entry} + * @throws NullPointerException if the key or value is null + * + * @see Map#ofEntries Map.ofEntries() + * @since 1.9 + */ + static Entry entry(K k, V v) { + // KeyValueHolder checks for nulls + return new KeyValueHolder<>(k, v); + } }