< prev index next >

src/java.base/share/classes/java/util/Map.java

Print this page
rev 17661 : 8177290: add copy factory methods for unmodifiable List, Set, Map
8184690: add Collectors for collecting into unmodifiable List, Set, and Map
Reviewed-by: XXX


  93  * only if this map contains a mapping for a key {@code k} such that
  94  * {@code (key==null ? k==null : key.equals(k))}." This specification should
  95  * <i>not</i> be construed to imply that invoking {@code Map.containsKey}
  96  * with a non-null argument {@code key} will cause {@code key.equals(k)} to
  97  * be invoked for any key {@code k}.  Implementations are free to
  98  * implement optimizations whereby the {@code equals} invocation is avoided,
  99  * for example, by first comparing the hash codes of the two keys.  (The
 100  * {@link Object#hashCode()} specification guarantees that two objects with
 101  * unequal hash codes cannot be equal.)  More generally, implementations of
 102  * the various Collections Framework interfaces are free to take advantage of
 103  * the specified behavior of underlying {@link Object} methods wherever the
 104  * implementor deems it appropriate.
 105  *
 106  * <p>Some map operations which perform recursive traversal of the map may fail
 107  * with an exception for self-referential instances where the map directly or
 108  * indirectly contains itself. This includes the {@code clone()},
 109  * {@code equals()}, {@code hashCode()} and {@code toString()} methods.
 110  * Implementations may optionally handle the self-referential scenario, however
 111  * most current implementations do not do so.
 112  *
 113  * <h2><a id="immutable">Immutable Map Static Factory Methods</a></h2>
 114  * <p>The {@link Map#of() Map.of()} and
 115  * {@link Map#ofEntries(Map.Entry...) Map.ofEntries()}
 116  * static factory methods provide a convenient way to create immutable maps.

 117  * The {@code Map}
 118  * instances created by these methods have the following characteristics:
 119  *
 120  * <ul>
 121  * <li>They are <em>structurally immutable</em>. Keys and values cannot be added,
 122  * removed, or updated. Calling any mutator method will always cause
 123  * {@code UnsupportedOperationException} to be thrown.
 124  * However, if the contained keys or values are themselves mutable, this may cause the
 125  * Map to behave inconsistently or its contents to appear to change.
 126  * <li>They disallow {@code null} keys and values. Attempts to create them with
 127  * {@code null} keys or values result in {@code NullPointerException}.
 128  * <li>They are serializable if all keys and values are serializable.
 129  * <li>They reject duplicate keys at creation time. Duplicate keys
 130  * passed to a static factory method result in {@code IllegalArgumentException}.
 131  * <li>The iteration order of mappings is unspecified and is subject to change.
 132  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
 133  * Callers should make no assumptions about the identity of the returned instances.
 134  * Factories are free to create new instances or reuse existing ones. Therefore,
 135  * identity-sensitive operations on these instances (reference equality ({@code ==}),
 136  * identity hash code, and synchronization) are unreliable and should be avoided.
 137  * <li>They are serialized as specified on the
 138  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>
 139  * page.
 140  * </ul>
 141  *
 142  * <p>This interface is a member of the
 143  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">


1259      *         does not support null keys or the value or remappingFunction is
1260      *         null
1261      * @since 1.8
1262      */
1263     default V merge(K key, V value,
1264             BiFunction<? super V, ? super V, ? extends V> remappingFunction) {
1265         Objects.requireNonNull(remappingFunction);
1266         Objects.requireNonNull(value);
1267         V oldValue = get(key);
1268         V newValue = (oldValue == null) ? value :
1269                    remappingFunction.apply(oldValue, value);
1270         if (newValue == null) {
1271             remove(key);
1272         } else {
1273             put(key, newValue);
1274         }
1275         return newValue;
1276     }
1277 
1278     /**
1279      * Returns an immutable map containing zero mappings.
1280      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1281      *
1282      * @param <K> the {@code Map}'s key type
1283      * @param <V> the {@code Map}'s value type
1284      * @return an empty {@code Map}
1285      *
1286      * @since 9
1287      */
1288     static <K, V> Map<K, V> of() {
1289         return ImmutableCollections.Map0.instance();
1290     }
1291 
1292     /**
1293      * Returns an immutable map containing a single mapping.
1294      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1295      *
1296      * @param <K> the {@code Map}'s key type
1297      * @param <V> the {@code Map}'s value type
1298      * @param k1 the mapping's key
1299      * @param v1 the mapping's value
1300      * @return a {@code Map} containing the specified mapping
1301      * @throws NullPointerException if the key or the value is {@code null}
1302      *
1303      * @since 9
1304      */
1305     static <K, V> Map<K, V> of(K k1, V v1) {
1306         return new ImmutableCollections.Map1<>(k1, v1);
1307     }
1308 
1309     /**
1310      * Returns an immutable map containing two mappings.
1311      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1312      *
1313      * @param <K> the {@code Map}'s key type
1314      * @param <V> the {@code Map}'s value type
1315      * @param k1 the first mapping's key
1316      * @param v1 the first mapping's value
1317      * @param k2 the second mapping's key
1318      * @param v2 the second mapping's value
1319      * @return a {@code Map} containing the specified mappings
1320      * @throws IllegalArgumentException if the keys are duplicates
1321      * @throws NullPointerException if any key or value is {@code null}
1322      *
1323      * @since 9
1324      */
1325     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2) {
1326         return new ImmutableCollections.MapN<>(k1, v1, k2, v2);
1327     }
1328 
1329     /**
1330      * Returns an immutable map containing three mappings.
1331      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1332      *
1333      * @param <K> the {@code Map}'s key type
1334      * @param <V> the {@code Map}'s value type
1335      * @param k1 the first mapping's key
1336      * @param v1 the first mapping's value
1337      * @param k2 the second mapping's key
1338      * @param v2 the second mapping's value
1339      * @param k3 the third mapping's key
1340      * @param v3 the third mapping's value
1341      * @return a {@code Map} containing the specified mappings
1342      * @throws IllegalArgumentException if there are any duplicate keys
1343      * @throws NullPointerException if any key or value is {@code null}
1344      *
1345      * @since 9
1346      */
1347     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3) {
1348         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3);
1349     }
1350 
1351     /**
1352      * Returns an immutable map containing four mappings.
1353      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1354      *
1355      * @param <K> the {@code Map}'s key type
1356      * @param <V> the {@code Map}'s value type
1357      * @param k1 the first mapping's key
1358      * @param v1 the first mapping's value
1359      * @param k2 the second mapping's key
1360      * @param v2 the second mapping's value
1361      * @param k3 the third mapping's key
1362      * @param v3 the third mapping's value
1363      * @param k4 the fourth mapping's key
1364      * @param v4 the fourth mapping's value
1365      * @return a {@code Map} containing the specified mappings
1366      * @throws IllegalArgumentException if there are any duplicate keys
1367      * @throws NullPointerException if any key or value is {@code null}
1368      *
1369      * @since 9
1370      */
1371     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) {
1372         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4);
1373     }
1374 
1375     /**
1376      * Returns an immutable map containing five mappings.
1377      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1378      *
1379      * @param <K> the {@code Map}'s key type
1380      * @param <V> the {@code Map}'s value type
1381      * @param k1 the first mapping's key
1382      * @param v1 the first mapping's value
1383      * @param k2 the second mapping's key
1384      * @param v2 the second mapping's value
1385      * @param k3 the third mapping's key
1386      * @param v3 the third mapping's value
1387      * @param k4 the fourth mapping's key
1388      * @param v4 the fourth mapping's value
1389      * @param k5 the fifth mapping's key
1390      * @param v5 the fifth mapping's value
1391      * @return a {@code Map} containing the specified mappings
1392      * @throws IllegalArgumentException if there are any duplicate keys
1393      * @throws NullPointerException if any key or value is {@code null}
1394      *
1395      * @since 9
1396      */
1397     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5) {
1398         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5);
1399     }
1400 
1401     /**
1402      * Returns an immutable map containing six mappings.
1403      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1404      *
1405      * @param <K> the {@code Map}'s key type
1406      * @param <V> the {@code Map}'s value type
1407      * @param k1 the first mapping's key
1408      * @param v1 the first mapping's value
1409      * @param k2 the second mapping's key
1410      * @param v2 the second mapping's value
1411      * @param k3 the third mapping's key
1412      * @param v3 the third mapping's value
1413      * @param k4 the fourth mapping's key
1414      * @param v4 the fourth mapping's value
1415      * @param k5 the fifth mapping's key
1416      * @param v5 the fifth mapping's value
1417      * @param k6 the sixth mapping's key
1418      * @param v6 the sixth mapping's value
1419      * @return a {@code Map} containing the specified mappings
1420      * @throws IllegalArgumentException if there are any duplicate keys
1421      * @throws NullPointerException if any key or value is {@code null}
1422      *
1423      * @since 9
1424      */
1425     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1426                                K k6, V v6) {
1427         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1428                                                k6, v6);
1429     }
1430 
1431     /**
1432      * Returns an immutable map containing seven mappings.
1433      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1434      *
1435      * @param <K> the {@code Map}'s key type
1436      * @param <V> the {@code Map}'s value type
1437      * @param k1 the first mapping's key
1438      * @param v1 the first mapping's value
1439      * @param k2 the second mapping's key
1440      * @param v2 the second mapping's value
1441      * @param k3 the third mapping's key
1442      * @param v3 the third mapping's value
1443      * @param k4 the fourth mapping's key
1444      * @param v4 the fourth mapping's value
1445      * @param k5 the fifth mapping's key
1446      * @param v5 the fifth mapping's value
1447      * @param k6 the sixth mapping's key
1448      * @param v6 the sixth mapping's value
1449      * @param k7 the seventh mapping's key
1450      * @param v7 the seventh mapping's value
1451      * @return a {@code Map} containing the specified mappings
1452      * @throws IllegalArgumentException if there are any duplicate keys
1453      * @throws NullPointerException if any key or value is {@code null}
1454      *
1455      * @since 9
1456      */
1457     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1458                                K k6, V v6, K k7, V v7) {
1459         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1460                                                k6, v6, k7, v7);
1461     }
1462 
1463     /**
1464      * Returns an immutable map containing eight mappings.
1465      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1466      *
1467      * @param <K> the {@code Map}'s key type
1468      * @param <V> the {@code Map}'s value type
1469      * @param k1 the first mapping's key
1470      * @param v1 the first mapping's value
1471      * @param k2 the second mapping's key
1472      * @param v2 the second mapping's value
1473      * @param k3 the third mapping's key
1474      * @param v3 the third mapping's value
1475      * @param k4 the fourth mapping's key
1476      * @param v4 the fourth mapping's value
1477      * @param k5 the fifth mapping's key
1478      * @param v5 the fifth mapping's value
1479      * @param k6 the sixth mapping's key
1480      * @param v6 the sixth mapping's value
1481      * @param k7 the seventh mapping's key
1482      * @param v7 the seventh mapping's value
1483      * @param k8 the eighth mapping's key
1484      * @param v8 the eighth mapping's value
1485      * @return a {@code Map} containing the specified mappings
1486      * @throws IllegalArgumentException if there are any duplicate keys
1487      * @throws NullPointerException if any key or value is {@code null}
1488      *
1489      * @since 9
1490      */
1491     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1492                                K k6, V v6, K k7, V v7, K k8, V v8) {
1493         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1494                                                k6, v6, k7, v7, k8, v8);
1495     }
1496 
1497     /**
1498      * Returns an immutable map containing nine mappings.
1499      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1500      *
1501      * @param <K> the {@code Map}'s key type
1502      * @param <V> the {@code Map}'s value type
1503      * @param k1 the first mapping's key
1504      * @param v1 the first mapping's value
1505      * @param k2 the second mapping's key
1506      * @param v2 the second mapping's value
1507      * @param k3 the third mapping's key
1508      * @param v3 the third mapping's value
1509      * @param k4 the fourth mapping's key
1510      * @param v4 the fourth mapping's value
1511      * @param k5 the fifth mapping's key
1512      * @param v5 the fifth mapping's value
1513      * @param k6 the sixth mapping's key
1514      * @param v6 the sixth mapping's value
1515      * @param k7 the seventh mapping's key
1516      * @param v7 the seventh mapping's value
1517      * @param k8 the eighth mapping's key
1518      * @param v8 the eighth mapping's value
1519      * @param k9 the ninth mapping's key
1520      * @param v9 the ninth mapping's value
1521      * @return a {@code Map} containing the specified mappings
1522      * @throws IllegalArgumentException if there are any duplicate keys
1523      * @throws NullPointerException if any key or value is {@code null}
1524      *
1525      * @since 9
1526      */
1527     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1528                                K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9) {
1529         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1530                                                k6, v6, k7, v7, k8, v8, k9, v9);
1531     }
1532 
1533     /**
1534      * Returns an immutable map containing ten mappings.
1535      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1536      *
1537      * @param <K> the {@code Map}'s key type
1538      * @param <V> the {@code Map}'s value type
1539      * @param k1 the first mapping's key
1540      * @param v1 the first mapping's value
1541      * @param k2 the second mapping's key
1542      * @param v2 the second mapping's value
1543      * @param k3 the third mapping's key
1544      * @param v3 the third mapping's value
1545      * @param k4 the fourth mapping's key
1546      * @param v4 the fourth mapping's value
1547      * @param k5 the fifth mapping's key
1548      * @param v5 the fifth mapping's value
1549      * @param k6 the sixth mapping's key
1550      * @param v6 the sixth mapping's value
1551      * @param k7 the seventh mapping's key
1552      * @param v7 the seventh mapping's value
1553      * @param k8 the eighth mapping's key
1554      * @param v8 the eighth mapping's value
1555      * @param k9 the ninth mapping's key
1556      * @param v9 the ninth mapping's value
1557      * @param k10 the tenth mapping's key
1558      * @param v10 the tenth mapping's value
1559      * @return a {@code Map} containing the specified mappings
1560      * @throws IllegalArgumentException if there are any duplicate keys
1561      * @throws NullPointerException if any key or value is {@code null}
1562      *
1563      * @since 9
1564      */
1565     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1566                                K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10) {
1567         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1568                                                k6, v6, k7, v7, k8, v8, k9, v9, k10, v10);
1569     }
1570 
1571     /**
1572      * Returns an immutable map containing keys and values extracted from the given entries.
1573      * The entries themselves are not stored in the map.
1574      * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1575      *
1576      * @apiNote
1577      * It is convenient to create the map entries using the {@link Map#entry Map.entry()} method.
1578      * For example,
1579      *
1580      * <pre>{@code
1581      *     import static java.util.Map.entry;
1582      *
1583      *     Map<Integer,String> map = Map.ofEntries(
1584      *         entry(1, "a"),
1585      *         entry(2, "b"),
1586      *         entry(3, "c"),
1587      *         ...
1588      *         entry(26, "z"));
1589      * }</pre>
1590      *
1591      * @param <K> the {@code Map}'s key type
1592      * @param <V> the {@code Map}'s value type
1593      * @param entries {@code Map.Entry}s containing the keys and values from which the map is populated
1594      * @return a {@code Map} containing the specified mappings


1602     @SafeVarargs
1603     @SuppressWarnings("varargs")
1604     static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries) {
1605         if (entries.length == 0) { // implicit null check of entries
1606             return ImmutableCollections.Map0.instance();
1607         } else if (entries.length == 1) {
1608             return new ImmutableCollections.Map1<>(entries[0].getKey(),
1609                                                    entries[0].getValue());
1610         } else {
1611             Object[] kva = new Object[entries.length << 1];
1612             int a = 0;
1613             for (Entry<? extends K, ? extends V> entry : entries) {
1614                 kva[a++] = entry.getKey();
1615                 kva[a++] = entry.getValue();
1616             }
1617             return new ImmutableCollections.MapN<>(kva);
1618         }
1619     }
1620 
1621     /**
1622      * Returns an immutable {@link Entry} containing the given key and value.
1623      * These entries are suitable for populating {@code Map} instances using the
1624      * {@link Map#ofEntries Map.ofEntries()} method.
1625      * The {@code Entry} instances created by this method have the following characteristics:
1626      *
1627      * <ul>
1628      * <li>They disallow {@code null} keys and values. Attempts to create them using a {@code null}
1629      * key or value result in {@code NullPointerException}.
1630      * <li>They are immutable. Calls to {@link Entry#setValue Entry.setValue()}
1631      * on a returned {@code Entry} result in {@code UnsupportedOperationException}.
1632      * <li>They are not serializable.
1633      * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
1634      * Callers should make no assumptions about the identity of the returned instances.
1635      * This method is free to create new instances or reuse existing ones. Therefore,
1636      * identity-sensitive operations on these instances (reference equality ({@code ==}),
1637      * identity hash code, and synchronization) are unreliable and should be avoided.
1638      * </ul>
1639      *
1640      * @apiNote
1641      * For a serializable {@code Entry}, see {@link AbstractMap.SimpleEntry} or
1642      * {@link AbstractMap.SimpleImmutableEntry}.
1643      *
1644      * @param <K> the key's type
1645      * @param <V> the value's type
1646      * @param k the key
1647      * @param v the value
1648      * @return an {@code Entry} containing the specified key and value
1649      * @throws NullPointerException if the key or value is {@code null}
1650      *
1651      * @see Map#ofEntries Map.ofEntries()
1652      * @since 9
1653      */
1654     static <K, V> Entry<K, V> entry(K k, V v) {
1655         // KeyValueHolder checks for nulls
1656         return new KeyValueHolder<>(k, v);
1657     }




















1658 }


  93  * only if this map contains a mapping for a key {@code k} such that
  94  * {@code (key==null ? k==null : key.equals(k))}." This specification should
  95  * <i>not</i> be construed to imply that invoking {@code Map.containsKey}
  96  * with a non-null argument {@code key} will cause {@code key.equals(k)} to
  97  * be invoked for any key {@code k}.  Implementations are free to
  98  * implement optimizations whereby the {@code equals} invocation is avoided,
  99  * for example, by first comparing the hash codes of the two keys.  (The
 100  * {@link Object#hashCode()} specification guarantees that two objects with
 101  * unequal hash codes cannot be equal.)  More generally, implementations of
 102  * the various Collections Framework interfaces are free to take advantage of
 103  * the specified behavior of underlying {@link Object} methods wherever the
 104  * implementor deems it appropriate.
 105  *
 106  * <p>Some map operations which perform recursive traversal of the map may fail
 107  * with an exception for self-referential instances where the map directly or
 108  * indirectly contains itself. This includes the {@code clone()},
 109  * {@code equals()}, {@code hashCode()} and {@code toString()} methods.
 110  * Implementations may optionally handle the self-referential scenario, however
 111  * most current implementations do not do so.
 112  *
 113  * <h2><a id="immutable">Unmodifiable Maps</a></h2>
 114  * <p>The {@link Map#of() Map.of},
 115  * {@link Map#ofEntries(Map.Entry...) Map.ofEntries}, and
 116  * {@link Map#copyOf Map.copyOf}
 117  * static factory methods provide a convenient way to create unmodifiable maps.
 118  * The {@code Map}
 119  * instances created by these methods have the following characteristics:
 120  *
 121  * <ul>
 122  * <li>They are <a href="Collection.html#unmodifiable"><i>unmodifiable</i></a>. Keys and values
 123  * cannot be added, removed, or updated. Calling any mutator method on the Map
 124  * will always cause {@code UnsupportedOperationException} to be thrown.
 125  * However, if the contained keys or values are themselves mutable, this may cause the
 126  * Map to behave inconsistently or its contents to appear to change.
 127  * <li>They disallow {@code null} keys and values. Attempts to create them with
 128  * {@code null} keys or values result in {@code NullPointerException}.
 129  * <li>They are serializable if all keys and values are serializable.
 130  * <li>They reject duplicate keys at creation time. Duplicate keys
 131  * passed to a static factory method result in {@code IllegalArgumentException}.
 132  * <li>The iteration order of mappings is unspecified and is subject to change.
 133  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
 134  * Callers should make no assumptions about the identity of the returned instances.
 135  * Factories are free to create new instances or reuse existing ones. Therefore,
 136  * identity-sensitive operations on these instances (reference equality ({@code ==}),
 137  * identity hash code, and synchronization) are unreliable and should be avoided.
 138  * <li>They are serialized as specified on the
 139  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>
 140  * page.
 141  * </ul>
 142  *
 143  * <p>This interface is a member of the
 144  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">


1260      *         does not support null keys or the value or remappingFunction is
1261      *         null
1262      * @since 1.8
1263      */
1264     default V merge(K key, V value,
1265             BiFunction<? super V, ? super V, ? extends V> remappingFunction) {
1266         Objects.requireNonNull(remappingFunction);
1267         Objects.requireNonNull(value);
1268         V oldValue = get(key);
1269         V newValue = (oldValue == null) ? value :
1270                    remappingFunction.apply(oldValue, value);
1271         if (newValue == null) {
1272             remove(key);
1273         } else {
1274             put(key, newValue);
1275         }
1276         return newValue;
1277     }
1278 
1279     /**
1280      * Returns an unmodifiable map containing zero mappings.
1281      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1282      *
1283      * @param <K> the {@code Map}'s key type
1284      * @param <V> the {@code Map}'s value type
1285      * @return an empty {@code Map}
1286      *
1287      * @since 9
1288      */
1289     static <K, V> Map<K, V> of() {
1290         return ImmutableCollections.Map0.instance();
1291     }
1292 
1293     /**
1294      * Returns an unmodifiable map containing a single mapping.
1295      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1296      *
1297      * @param <K> the {@code Map}'s key type
1298      * @param <V> the {@code Map}'s value type
1299      * @param k1 the mapping's key
1300      * @param v1 the mapping's value
1301      * @return a {@code Map} containing the specified mapping
1302      * @throws NullPointerException if the key or the value is {@code null}
1303      *
1304      * @since 9
1305      */
1306     static <K, V> Map<K, V> of(K k1, V v1) {
1307         return new ImmutableCollections.Map1<>(k1, v1);
1308     }
1309 
1310     /**
1311      * Returns an unmodifiable map containing two mappings.
1312      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1313      *
1314      * @param <K> the {@code Map}'s key type
1315      * @param <V> the {@code Map}'s value type
1316      * @param k1 the first mapping's key
1317      * @param v1 the first mapping's value
1318      * @param k2 the second mapping's key
1319      * @param v2 the second mapping's value
1320      * @return a {@code Map} containing the specified mappings
1321      * @throws IllegalArgumentException if the keys are duplicates
1322      * @throws NullPointerException if any key or value is {@code null}
1323      *
1324      * @since 9
1325      */
1326     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2) {
1327         return new ImmutableCollections.MapN<>(k1, v1, k2, v2);
1328     }
1329 
1330     /**
1331      * Returns an unmodifiable map containing three mappings.
1332      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1333      *
1334      * @param <K> the {@code Map}'s key type
1335      * @param <V> the {@code Map}'s value type
1336      * @param k1 the first mapping's key
1337      * @param v1 the first mapping's value
1338      * @param k2 the second mapping's key
1339      * @param v2 the second mapping's value
1340      * @param k3 the third mapping's key
1341      * @param v3 the third mapping's value
1342      * @return a {@code Map} containing the specified mappings
1343      * @throws IllegalArgumentException if there are any duplicate keys
1344      * @throws NullPointerException if any key or value is {@code null}
1345      *
1346      * @since 9
1347      */
1348     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3) {
1349         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3);
1350     }
1351 
1352     /**
1353      * Returns an unmodifiable map containing four mappings.
1354      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1355      *
1356      * @param <K> the {@code Map}'s key type
1357      * @param <V> the {@code Map}'s value type
1358      * @param k1 the first mapping's key
1359      * @param v1 the first mapping's value
1360      * @param k2 the second mapping's key
1361      * @param v2 the second mapping's value
1362      * @param k3 the third mapping's key
1363      * @param v3 the third mapping's value
1364      * @param k4 the fourth mapping's key
1365      * @param v4 the fourth mapping's value
1366      * @return a {@code Map} containing the specified mappings
1367      * @throws IllegalArgumentException if there are any duplicate keys
1368      * @throws NullPointerException if any key or value is {@code null}
1369      *
1370      * @since 9
1371      */
1372     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) {
1373         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4);
1374     }
1375 
1376     /**
1377      * Returns an unmodifiable map containing five mappings.
1378      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1379      *
1380      * @param <K> the {@code Map}'s key type
1381      * @param <V> the {@code Map}'s value type
1382      * @param k1 the first mapping's key
1383      * @param v1 the first mapping's value
1384      * @param k2 the second mapping's key
1385      * @param v2 the second mapping's value
1386      * @param k3 the third mapping's key
1387      * @param v3 the third mapping's value
1388      * @param k4 the fourth mapping's key
1389      * @param v4 the fourth mapping's value
1390      * @param k5 the fifth mapping's key
1391      * @param v5 the fifth mapping's value
1392      * @return a {@code Map} containing the specified mappings
1393      * @throws IllegalArgumentException if there are any duplicate keys
1394      * @throws NullPointerException if any key or value is {@code null}
1395      *
1396      * @since 9
1397      */
1398     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5) {
1399         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5);
1400     }
1401 
1402     /**
1403      * Returns an unmodifiable map containing six mappings.
1404      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1405      *
1406      * @param <K> the {@code Map}'s key type
1407      * @param <V> the {@code Map}'s value type
1408      * @param k1 the first mapping's key
1409      * @param v1 the first mapping's value
1410      * @param k2 the second mapping's key
1411      * @param v2 the second mapping's value
1412      * @param k3 the third mapping's key
1413      * @param v3 the third mapping's value
1414      * @param k4 the fourth mapping's key
1415      * @param v4 the fourth mapping's value
1416      * @param k5 the fifth mapping's key
1417      * @param v5 the fifth mapping's value
1418      * @param k6 the sixth mapping's key
1419      * @param v6 the sixth mapping's value
1420      * @return a {@code Map} containing the specified mappings
1421      * @throws IllegalArgumentException if there are any duplicate keys
1422      * @throws NullPointerException if any key or value is {@code null}
1423      *
1424      * @since 9
1425      */
1426     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1427                                K k6, V v6) {
1428         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1429                                                k6, v6);
1430     }
1431 
1432     /**
1433      * Returns an unmodifiable map containing seven mappings.
1434      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1435      *
1436      * @param <K> the {@code Map}'s key type
1437      * @param <V> the {@code Map}'s value type
1438      * @param k1 the first mapping's key
1439      * @param v1 the first mapping's value
1440      * @param k2 the second mapping's key
1441      * @param v2 the second mapping's value
1442      * @param k3 the third mapping's key
1443      * @param v3 the third mapping's value
1444      * @param k4 the fourth mapping's key
1445      * @param v4 the fourth mapping's value
1446      * @param k5 the fifth mapping's key
1447      * @param v5 the fifth mapping's value
1448      * @param k6 the sixth mapping's key
1449      * @param v6 the sixth mapping's value
1450      * @param k7 the seventh mapping's key
1451      * @param v7 the seventh mapping's value
1452      * @return a {@code Map} containing the specified mappings
1453      * @throws IllegalArgumentException if there are any duplicate keys
1454      * @throws NullPointerException if any key or value is {@code null}
1455      *
1456      * @since 9
1457      */
1458     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1459                                K k6, V v6, K k7, V v7) {
1460         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1461                                                k6, v6, k7, v7);
1462     }
1463 
1464     /**
1465      * Returns an unmodifiable map containing eight mappings.
1466      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1467      *
1468      * @param <K> the {@code Map}'s key type
1469      * @param <V> the {@code Map}'s value type
1470      * @param k1 the first mapping's key
1471      * @param v1 the first mapping's value
1472      * @param k2 the second mapping's key
1473      * @param v2 the second mapping's value
1474      * @param k3 the third mapping's key
1475      * @param v3 the third mapping's value
1476      * @param k4 the fourth mapping's key
1477      * @param v4 the fourth mapping's value
1478      * @param k5 the fifth mapping's key
1479      * @param v5 the fifth mapping's value
1480      * @param k6 the sixth mapping's key
1481      * @param v6 the sixth mapping's value
1482      * @param k7 the seventh mapping's key
1483      * @param v7 the seventh mapping's value
1484      * @param k8 the eighth mapping's key
1485      * @param v8 the eighth mapping's value
1486      * @return a {@code Map} containing the specified mappings
1487      * @throws IllegalArgumentException if there are any duplicate keys
1488      * @throws NullPointerException if any key or value is {@code null}
1489      *
1490      * @since 9
1491      */
1492     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1493                                K k6, V v6, K k7, V v7, K k8, V v8) {
1494         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1495                                                k6, v6, k7, v7, k8, v8);
1496     }
1497 
1498     /**
1499      * Returns an unmodifiable map containing nine mappings.
1500      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1501      *
1502      * @param <K> the {@code Map}'s key type
1503      * @param <V> the {@code Map}'s value type
1504      * @param k1 the first mapping's key
1505      * @param v1 the first mapping's value
1506      * @param k2 the second mapping's key
1507      * @param v2 the second mapping's value
1508      * @param k3 the third mapping's key
1509      * @param v3 the third mapping's value
1510      * @param k4 the fourth mapping's key
1511      * @param v4 the fourth mapping's value
1512      * @param k5 the fifth mapping's key
1513      * @param v5 the fifth mapping's value
1514      * @param k6 the sixth mapping's key
1515      * @param v6 the sixth mapping's value
1516      * @param k7 the seventh mapping's key
1517      * @param v7 the seventh mapping's value
1518      * @param k8 the eighth mapping's key
1519      * @param v8 the eighth mapping's value
1520      * @param k9 the ninth mapping's key
1521      * @param v9 the ninth mapping's value
1522      * @return a {@code Map} containing the specified mappings
1523      * @throws IllegalArgumentException if there are any duplicate keys
1524      * @throws NullPointerException if any key or value is {@code null}
1525      *
1526      * @since 9
1527      */
1528     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1529                                K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9) {
1530         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1531                                                k6, v6, k7, v7, k8, v8, k9, v9);
1532     }
1533 
1534     /**
1535      * Returns an unmodifiable map containing ten mappings.
1536      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1537      *
1538      * @param <K> the {@code Map}'s key type
1539      * @param <V> the {@code Map}'s value type
1540      * @param k1 the first mapping's key
1541      * @param v1 the first mapping's value
1542      * @param k2 the second mapping's key
1543      * @param v2 the second mapping's value
1544      * @param k3 the third mapping's key
1545      * @param v3 the third mapping's value
1546      * @param k4 the fourth mapping's key
1547      * @param v4 the fourth mapping's value
1548      * @param k5 the fifth mapping's key
1549      * @param v5 the fifth mapping's value
1550      * @param k6 the sixth mapping's key
1551      * @param v6 the sixth mapping's value
1552      * @param k7 the seventh mapping's key
1553      * @param v7 the seventh mapping's value
1554      * @param k8 the eighth mapping's key
1555      * @param v8 the eighth mapping's value
1556      * @param k9 the ninth mapping's key
1557      * @param v9 the ninth mapping's value
1558      * @param k10 the tenth mapping's key
1559      * @param v10 the tenth mapping's value
1560      * @return a {@code Map} containing the specified mappings
1561      * @throws IllegalArgumentException if there are any duplicate keys
1562      * @throws NullPointerException if any key or value is {@code null}
1563      *
1564      * @since 9
1565      */
1566     static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5,
1567                                K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10) {
1568         return new ImmutableCollections.MapN<>(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5,
1569                                                k6, v6, k7, v7, k8, v8, k9, v9, k10, v10);
1570     }
1571 
1572     /**
1573      * Returns an unmodifiable map containing keys and values extracted from the given entries.
1574      * The entries themselves are not stored in the map.
1575      * See <a href="#unmodifiable">Unmodifiable Maps</a> for details.
1576      *
1577      * @apiNote
1578      * It is convenient to create the map entries using the {@link Map#entry Map.entry()} method.
1579      * For example,
1580      *
1581      * <pre>{@code
1582      *     import static java.util.Map.entry;
1583      *
1584      *     Map<Integer,String> map = Map.ofEntries(
1585      *         entry(1, "a"),
1586      *         entry(2, "b"),
1587      *         entry(3, "c"),
1588      *         ...
1589      *         entry(26, "z"));
1590      * }</pre>
1591      *
1592      * @param <K> the {@code Map}'s key type
1593      * @param <V> the {@code Map}'s value type
1594      * @param entries {@code Map.Entry}s containing the keys and values from which the map is populated
1595      * @return a {@code Map} containing the specified mappings


1603     @SafeVarargs
1604     @SuppressWarnings("varargs")
1605     static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries) {
1606         if (entries.length == 0) { // implicit null check of entries
1607             return ImmutableCollections.Map0.instance();
1608         } else if (entries.length == 1) {
1609             return new ImmutableCollections.Map1<>(entries[0].getKey(),
1610                                                    entries[0].getValue());
1611         } else {
1612             Object[] kva = new Object[entries.length << 1];
1613             int a = 0;
1614             for (Entry<? extends K, ? extends V> entry : entries) {
1615                 kva[a++] = entry.getKey();
1616                 kva[a++] = entry.getValue();
1617             }
1618             return new ImmutableCollections.MapN<>(kva);
1619         }
1620     }
1621 
1622     /**
1623      * Returns an unmodifiable {@link Entry} containing the given key and value.
1624      * These entries are suitable for populating {@code Map} instances using the
1625      * {@link Map#ofEntries Map.ofEntries()} method.
1626      * The {@code Entry} instances created by this method have the following characteristics:
1627      *
1628      * <ul>
1629      * <li>They disallow {@code null} keys and values. Attempts to create them using a {@code null}
1630      * key or value result in {@code NullPointerException}.
1631      * <li>They are unmodifiable. Calls to {@link Entry#setValue Entry.setValue()}
1632      * on a returned {@code Entry} result in {@code UnsupportedOperationException}.
1633      * <li>They are not serializable.
1634      * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
1635      * Callers should make no assumptions about the identity of the returned instances.
1636      * This method is free to create new instances or reuse existing ones. Therefore,
1637      * identity-sensitive operations on these instances (reference equality ({@code ==}),
1638      * identity hash code, and synchronization) are unreliable and should be avoided.
1639      * </ul>
1640      *
1641      * @apiNote
1642      * For a serializable {@code Entry}, see {@link AbstractMap.SimpleEntry} or
1643      * {@link AbstractMap.SimpleImmutableEntry}.
1644      *
1645      * @param <K> the key's type
1646      * @param <V> the value's type
1647      * @param k the key
1648      * @param v the value
1649      * @return an {@code Entry} containing the specified key and value
1650      * @throws NullPointerException if the key or value is {@code null}
1651      *
1652      * @see Map#ofEntries Map.ofEntries()
1653      * @since 9
1654      */
1655     static <K, V> Entry<K, V> entry(K k, V v) {
1656         // KeyValueHolder checks for nulls
1657         return new KeyValueHolder<>(k, v);
1658     }
1659 
1660     /**
1661      * Returns an unmodifiable Map containing the entries of the given Map.
1662      * See <a href="#unmodifiable">Unmodifiable Maps</a> for
1663      * information about the characteristics of the returned Map.
1664      *
1665      * @param <K> the {@code Map}'s key type
1666      * @param <V> the {@code Map}'s value type
1667      * @param map the map from which entries are drawn
1668      * @return the new {@code Map}
1669      * @since 10
1670      */
1671     @SuppressWarnings({"rawtypes","unchecked"})
1672     static <K, V> Map<K, V> copyOf(Map<? extends K, ? extends V> map) {
1673         if (map instanceof ImmutableCollections.AbstractImmutableMap) {
1674             return (Map<K,V>)map;
1675         } else {
1676             return (Map<K,V>)Map.ofEntries(map.entrySet().toArray(new Entry[0]));
1677         }
1678     }
1679 }
< prev index next >