ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/Map.java
(Generate patch)

Comparing jsr166/src/main/java/util/Map.java (file contents):
Revision 1.2 by jsr166, Mon Dec 14 21:15:46 2015 UTC vs.
Revision 1.3 by jsr166, Wed Dec 16 03:15:28 2015 UTC

# Line 1 | Line 1
1   /*
2 < * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
2 > * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
3   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4   *
5   * This code is free software; you can redistribute it and/or modify it
# Line 110 | Line 110 | import java.io.Serializable;
110   * Implementations may optionally handle the self-referential scenario, however
111   * most current implementations do not do so.
112   *
113 + * <h2><a name="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. Attempts to do so result in {@code UnsupportedOperationException}.
123 + * However, if the contained keys or values are themselves mutable, this may cause the
124 + * Map to behave inconsistently or its contents to appear to change.
125 + * <li>They disallow {@code null} keys and values. Attempts to create them with
126 + * {@code null} keys or values result in {@code NullPointerException}.
127 + * <li>They are serializable if all keys and values are serializable.
128 + * <li>They reject duplicate keys at creation time. Duplicate keys
129 + * passed to a static factory method result in {@code IllegalArgumentException}.
130 + * <li>The iteration order of mappings is unspecified and is subject to change.
131 + * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
132 + * Callers should make no assumptions about the identity of the returned instances.
133 + * Factories are free to create new instances or reuse existing ones. Therefore,
134 + * identity-sensitive operations on these instances (reference equality ({@code ==}),
135 + * identity hash code, and synchronization) are unreliable and should be avoided.
136 + * </ul>
137 + *
138   * <p>This interface is a member of the
139   * <a href="{@docRoot}/../technotes/guides/collections/index.html">
140   * Java Collections Framework</a>.
# Line 126 | Line 151 | import java.io.Serializable;
151   * @see Set
152   * @since 1.2
153   */
154 < public interface Map<K,V> {
154 > public interface Map<K, V> {
155      // Query Operations
156  
157      /**
# Line 157 | Line 182 | public interface Map<K,V> {
182       *         key
183       * @throws ClassCastException if the key is of an inappropriate type for
184       *         this map
185 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
185 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
186       * @throws NullPointerException if the specified key is null and this map
187       *         does not permit null keys
188 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
188 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
189       */
190      boolean containsKey(Object key);
191  
# Line 177 | Line 202 | public interface Map<K,V> {
202       *         specified value
203       * @throws ClassCastException if the value is of an inappropriate type for
204       *         this map
205 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
205 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
206       * @throws NullPointerException if the specified value is null and this
207       *         map does not permit null values
208 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
208 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
209       */
210      boolean containsValue(Object value);
211  
# Line 205 | Line 230 | public interface Map<K,V> {
230       *         {@code null} if this map contains no mapping for the key
231       * @throws ClassCastException if the key is of an inappropriate type for
232       *         this map
233 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
233 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
234       * @throws NullPointerException if the specified key is null and this map
235       *         does not permit null keys
236 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
236 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
237       */
238      V get(Object key);
239  
# Line 265 | Line 290 | public interface Map<K,V> {
290       *         is not supported by this map
291       * @throws ClassCastException if the key is of an inappropriate type for
292       *         this map
293 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
293 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
294       * @throws NullPointerException if the specified key is null and this
295       *         map does not permit null keys
296 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
296 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
297       */
298      V remove(Object key);
299  
# Line 373 | Line 398 | public interface Map<K,V> {
398       * @see Map#entrySet()
399       * @since 1.2
400       */
401 <    interface Entry<K,V> {
401 >    interface Entry<K, V> {
402          /**
403           * Returns the key corresponding to this entry.
404           *
# Line 468 | Line 493 | public interface Map<K,V> {
493           * @see Comparable
494           * @since 1.8
495           */
496 <        public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K,V>> comparingByKey() {
496 >        public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K, V>> comparingByKey() {
497              return (Comparator<Map.Entry<K, V>> & Serializable)
498                  (c1, c2) -> c1.getKey().compareTo(c2.getKey());
499          }
# Line 485 | Line 510 | public interface Map<K,V> {
510           * @see Comparable
511           * @since 1.8
512           */
513 <        public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K,V>> comparingByValue() {
513 >        public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K, V>> comparingByValue() {
514              return (Comparator<Map.Entry<K, V>> & Serializable)
515                  (c1, c2) -> c1.getValue().compareTo(c2.getValue());
516          }
# Line 578 | Line 603 | public interface Map<K,V> {
603       * {@code defaultValue} if this map contains no mapping for the key
604       * @throws ClassCastException if the key is of an inappropriate type for
605       * this map
606 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
606 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
607       * @throws NullPointerException if the specified key is null and this map
608       * does not permit null keys
609 <     * (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
609 >     * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
610       * @since 1.8
611       */
612      default V getOrDefault(Object key, V defaultValue) {
# Line 660 | Line 685 | public interface Map<K,V> {
685       * values
686       * @throws ClassCastException if a replacement value is of an inappropriate
687       *         type for this map
688 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
688 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
689       * @throws NullPointerException if function or a replacement value is null,
690       *         and this map does not permit null keys or values
691 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
691 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
692       * @throws IllegalArgumentException if some property of a replacement value
693       *         prevents it from being stored in this map
694 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
694 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
695       * @throws ConcurrentModificationException if an entry is found to be
696       * removed during iteration
697       * @since 1.8
# Line 727 | Line 752 | public interface Map<K,V> {
752       *         if the implementation supports null values.)
753       * @throws UnsupportedOperationException if the {@code put} operation
754       *         is not supported by this map
755 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
755 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
756       * @throws ClassCastException if the key or value is of an inappropriate
757       *         type for this map
758 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
758 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
759       * @throws NullPointerException if the specified key or value is null,
760       *         and this map does not permit null keys or values
761 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
761 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
762       * @throws IllegalArgumentException if some property of the specified key
763       *         or value prevents it from being stored in this map
764 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
764 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
765       * @since 1.8
766       */
767      default V putIfAbsent(K key, V value) {
# Line 773 | Line 798 | public interface Map<K,V> {
798       * @return {@code true} if the value was removed
799       * @throws UnsupportedOperationException if the {@code remove} operation
800       *         is not supported by this map
801 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
801 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
802       * @throws ClassCastException if the key or value is of an inappropriate
803       *         type for this map
804 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
804 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
805       * @throws NullPointerException if the specified key or value is null,
806       *         and this map does not permit null keys or values
807 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
807 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
808       * @since 1.8
809       */
810      default boolean remove(Object key, Object value) {
# Line 822 | Line 847 | public interface Map<K,V> {
847       * @return {@code true} if the value was replaced
848       * @throws UnsupportedOperationException if the {@code put} operation
849       *         is not supported by this map
850 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
850 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
851       * @throws ClassCastException if the class of a specified key or value
852       *         prevents it from being stored in this map
853       * @throws NullPointerException if a specified key or newValue is null,
854       *         and this map does not permit null keys or values
855       * @throws NullPointerException if oldValue is null and this map does not
856       *         permit null values
857 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
857 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
858       * @throws IllegalArgumentException if some property of a specified key
859       *         or value prevents it from being stored in this map
860       * @since 1.8
# Line 872 | Line 897 | public interface Map<K,V> {
897       *         if the implementation supports null values.)
898       * @throws UnsupportedOperationException if the {@code put} operation
899       *         is not supported by this map
900 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
900 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
901       * @throws ClassCastException if the class of the specified key or value
902       *         prevents it from being stored in this map
903 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
903 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
904       * @throws NullPointerException if the specified key or value is null,
905       *         and this map does not permit null keys or values
906       * @throws IllegalArgumentException if some property of the specified key
# Line 955 | Line 980 | public interface Map<K,V> {
980       *         is null
981       * @throws UnsupportedOperationException if the {@code put} operation
982       *         is not supported by this map
983 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
983 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
984       * @throws ClassCastException if the class of the specified key or value
985       *         prevents it from being stored in this map
986 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
986 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
987       * @throws IllegalArgumentException if some property of the specified key
988       *         or value prevents it from being stored in this map
989 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
989 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
990       * @since 1.8
991       */
992      default V computeIfAbsent(K key,
# Line 1032 | Line 1057 | public interface Map<K,V> {
1057       *         remappingFunction is null
1058       * @throws UnsupportedOperationException if the {@code put} operation
1059       *         is not supported by this map
1060 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1060 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1061       * @throws ClassCastException if the class of the specified key or value
1062       *         prevents it from being stored in this map
1063 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1063 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1064       * @throws IllegalArgumentException if some property of the specified key
1065       *         or value prevents it from being stored in this map
1066 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1066 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1067       * @since 1.8
1068       */
1069      default V computeIfPresent(K key,
# Line 1084 | Line 1109 | public interface Map<K,V> {
1109       * <pre> {@code
1110       * V oldValue = map.get(key);
1111       * V newValue = remappingFunction.apply(key, oldValue);
1112 <     * if (oldValue != null ) {
1112 >     * if (oldValue != null) {
1113       *    if (newValue != null)
1114       *       map.put(key, newValue);
1115       *    else
# Line 1124 | Line 1149 | public interface Map<K,V> {
1149       *         remappingFunction is null
1150       * @throws UnsupportedOperationException if the {@code put} operation
1151       *         is not supported by this map
1152 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1152 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1153       * @throws ClassCastException if the class of the specified key or value
1154       *         prevents it from being stored in this map
1155 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1155 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1156       * @throws IllegalArgumentException if some property of the specified key
1157       *         or value prevents it from being stored in this map
1158 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1158 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1159       * @since 1.8
1160       */
1161      default V compute(K key,
# Line 1219 | Line 1244 | public interface Map<K,V> {
1244       *         value is associated with the key
1245       * @throws UnsupportedOperationException if the {@code put} operation
1246       *         is not supported by this map
1247 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1247 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1248       * @throws ClassCastException if the class of the specified key or value
1249       *         prevents it from being stored in this map
1250 <     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1250 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1251 >     * @throws IllegalArgumentException if some property of the specified key
1252 >     *         or value prevents it from being stored in this map
1253 >     *         (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
1254       * @throws NullPointerException if the specified key is null and this map
1255       *         does not support null keys or the value or remappingFunction is
1256       *         null
1229 –     * @throws IllegalArgumentException if some property of the specified key
1230 –     *         or value prevents it from being stored in this map
1231 –     *         (<a href="{@docRoot}/../api/java/util/Collection.html#optional-restrictions">optional</a>)
1257       * @since 1.8
1258       */
1259      default V merge(K key, V value,
# Line 1245 | Line 1270 | public interface Map<K,V> {
1270          }
1271          return newValue;
1272      }
1273 +
1274 +    /**
1275 +     * Returns an immutable map containing zero mappings.
1276 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1277 +     *
1278 +     * @param <K> the {@code Map}'s key type
1279 +     * @param <V> the {@code Map}'s value type
1280 +     * @return an empty {@code Map}
1281 +     *
1282 +     * @since 9
1283 +     */
1284 +    static <K, V> Map<K, V> of() {
1285 +        return Collections.emptyMap();
1286 +    }
1287 +
1288 +    /**
1289 +     * Returns an immutable map containing a single mapping.
1290 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1291 +     *
1292 +     * @param <K> the {@code Map}'s key type
1293 +     * @param <V> the {@code Map}'s value type
1294 +     * @param k1 the mapping's key
1295 +     * @param v1 the mapping's value
1296 +     * @return a {@code Map} containing the specified mapping
1297 +     * @throws NullPointerException if the key or the value is {@code null}
1298 +     *
1299 +     * @since 9
1300 +     */
1301 +    static <K, V> Map<K, V> of(K k1, V v1) {
1302 +        return Collections.singletonMap(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1303 +    }
1304 +
1305 +    /**
1306 +     * Returns an immutable map containing two mappings.
1307 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1308 +     *
1309 +     * @param <K> the {@code Map}'s key type
1310 +     * @param <V> the {@code Map}'s value type
1311 +     * @param k1 the first mapping's key
1312 +     * @param v1 the first mapping's value
1313 +     * @param k2 the second mapping's key
1314 +     * @param v2 the second mapping's value
1315 +     * @return a {@code Map} containing the specified mappings
1316 +     * @throws IllegalArgumentException if the keys are duplicates
1317 +     * @throws NullPointerException if any key or value is {@code null}
1318 +     *
1319 +     * @since 9
1320 +     */
1321 +    static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2) {
1322 +        Map<K, V> map = new HashMap<>(3); // specify number of buckets to avoid resizing
1323 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1324 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1325 +        if (map.size() != 2) {
1326 +            throw new IllegalArgumentException("duplicate keys");
1327 +        }
1328 +        return Collections.unmodifiableMap(map);
1329 +    }
1330 +
1331 +    /**
1332 +     * Returns an immutable map containing three mappings.
1333 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1334 +     *
1335 +     * @param <K> the {@code Map}'s key type
1336 +     * @param <V> the {@code Map}'s value type
1337 +     * @param k1 the first mapping's key
1338 +     * @param v1 the first mapping's value
1339 +     * @param k2 the second mapping's key
1340 +     * @param v2 the second mapping's value
1341 +     * @param k3 the third mapping's key
1342 +     * @param v3 the third mapping's value
1343 +     * @return a {@code Map} containing the specified mappings
1344 +     * @throws IllegalArgumentException if there are any duplicate keys
1345 +     * @throws NullPointerException if any key or value is {@code null}
1346 +     *
1347 +     * @since 9
1348 +     */
1349 +    static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3) {
1350 +        Map<K, V> map = new HashMap<>(5); // specify number of buckets to avoid resizing
1351 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1352 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1353 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1354 +        if (map.size() != 3) {
1355 +            throw new IllegalArgumentException("duplicate keys");
1356 +        }
1357 +        return Collections.unmodifiableMap(map);
1358 +    }
1359 +
1360 +    /**
1361 +     * Returns an immutable map containing four mappings.
1362 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1363 +     *
1364 +     * @param <K> the {@code Map}'s key type
1365 +     * @param <V> the {@code Map}'s value type
1366 +     * @param k1 the first mapping's key
1367 +     * @param v1 the first mapping's value
1368 +     * @param k2 the second mapping's key
1369 +     * @param v2 the second mapping's value
1370 +     * @param k3 the third mapping's key
1371 +     * @param v3 the third mapping's value
1372 +     * @param k4 the fourth mapping's key
1373 +     * @param v4 the fourth mapping's value
1374 +     * @return a {@code Map} containing the specified mappings
1375 +     * @throws IllegalArgumentException if there are any duplicate keys
1376 +     * @throws NullPointerException if any key or value is {@code null}
1377 +     *
1378 +     * @since 9
1379 +     */
1380 +    static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) {
1381 +        Map<K, V> map = new HashMap<>(6); // specify number of buckets to avoid resizing
1382 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1383 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1384 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1385 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1386 +        if (map.size() != 4) {
1387 +            throw new IllegalArgumentException("duplicate keys");
1388 +        }
1389 +        return Collections.unmodifiableMap(map);
1390 +    }
1391 +
1392 +    /**
1393 +     * Returns an immutable map containing five mappings.
1394 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1395 +     *
1396 +     * @param <K> the {@code Map}'s key type
1397 +     * @param <V> the {@code Map}'s value type
1398 +     * @param k1 the first mapping's key
1399 +     * @param v1 the first mapping's value
1400 +     * @param k2 the second mapping's key
1401 +     * @param v2 the second mapping's value
1402 +     * @param k3 the third mapping's key
1403 +     * @param v3 the third mapping's value
1404 +     * @param k4 the fourth mapping's key
1405 +     * @param v4 the fourth mapping's value
1406 +     * @param k5 the fifth mapping's key
1407 +     * @param v5 the fifth mapping's value
1408 +     * @return a {@code Map} containing the specified mappings
1409 +     * @throws IllegalArgumentException if there are any duplicate keys
1410 +     * @throws NullPointerException if any key or value is {@code null}
1411 +     *
1412 +     * @since 9
1413 +     */
1414 +    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) {
1415 +        Map<K, V> map = new HashMap<>(7); // specify number of buckets to avoid resizing
1416 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1417 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1418 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1419 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1420 +        map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5));
1421 +        if (map.size() != 5) {
1422 +            throw new IllegalArgumentException("duplicate keys");
1423 +        }
1424 +        return Collections.unmodifiableMap(map);
1425 +    }
1426 +
1427 +    /**
1428 +     * Returns an immutable map containing six mappings.
1429 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1430 +     *
1431 +     * @param <K> the {@code Map}'s key type
1432 +     * @param <V> the {@code Map}'s value type
1433 +     * @param k1 the first mapping's key
1434 +     * @param v1 the first mapping's value
1435 +     * @param k2 the second mapping's key
1436 +     * @param v2 the second mapping's value
1437 +     * @param k3 the third mapping's key
1438 +     * @param v3 the third mapping's value
1439 +     * @param k4 the fourth mapping's key
1440 +     * @param v4 the fourth mapping's value
1441 +     * @param k5 the fifth mapping's key
1442 +     * @param v5 the fifth mapping's value
1443 +     * @param k6 the sixth mapping's key
1444 +     * @param v6 the sixth mapping's value
1445 +     * @return a {@code Map} containing the specified mappings
1446 +     * @throws IllegalArgumentException if there are any duplicate keys
1447 +     * @throws NullPointerException if any key or value is {@code null}
1448 +     *
1449 +     * @since 9
1450 +     */
1451 +    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,
1452 +                               K k6, V v6) {
1453 +        Map<K, V> map = new HashMap<>(9); // specify number of buckets to avoid resizing
1454 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1455 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1456 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1457 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1458 +        map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5));
1459 +        map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6));
1460 +        if (map.size() != 6) {
1461 +            throw new IllegalArgumentException("duplicate keys");
1462 +        }
1463 +        return Collections.unmodifiableMap(map);
1464 +    }
1465 +
1466 +    /**
1467 +     * Returns an immutable map containing seven mappings.
1468 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1469 +     *
1470 +     * @param <K> the {@code Map}'s key type
1471 +     * @param <V> the {@code Map}'s value type
1472 +     * @param k1 the first mapping's key
1473 +     * @param v1 the first mapping's value
1474 +     * @param k2 the second mapping's key
1475 +     * @param v2 the second mapping's value
1476 +     * @param k3 the third mapping's key
1477 +     * @param v3 the third mapping's value
1478 +     * @param k4 the fourth mapping's key
1479 +     * @param v4 the fourth mapping's value
1480 +     * @param k5 the fifth mapping's key
1481 +     * @param v5 the fifth mapping's value
1482 +     * @param k6 the sixth mapping's key
1483 +     * @param v6 the sixth mapping's value
1484 +     * @param k7 the seventh mapping's key
1485 +     * @param v7 the seventh 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) {
1494 +        Map<K, V> map = new HashMap<>(10); // specify number of buckets to avoid resizing
1495 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1496 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1497 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1498 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1499 +        map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5));
1500 +        map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6));
1501 +        map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7));
1502 +        if (map.size() != 7) {
1503 +            throw new IllegalArgumentException("duplicate keys");
1504 +        }
1505 +        return Collections.unmodifiableMap(map);
1506 +    }
1507 +
1508 +    /**
1509 +     * Returns an immutable map containing eight mappings.
1510 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1511 +     *
1512 +     * @param <K> the {@code Map}'s key type
1513 +     * @param <V> the {@code Map}'s value type
1514 +     * @param k1 the first mapping's key
1515 +     * @param v1 the first mapping's value
1516 +     * @param k2 the second mapping's key
1517 +     * @param v2 the second mapping's value
1518 +     * @param k3 the third mapping's key
1519 +     * @param v3 the third mapping's value
1520 +     * @param k4 the fourth mapping's key
1521 +     * @param v4 the fourth mapping's value
1522 +     * @param k5 the fifth mapping's key
1523 +     * @param v5 the fifth mapping's value
1524 +     * @param k6 the sixth mapping's key
1525 +     * @param v6 the sixth mapping's value
1526 +     * @param k7 the seventh mapping's key
1527 +     * @param v7 the seventh mapping's value
1528 +     * @param k8 the eighth mapping's key
1529 +     * @param v8 the eighth mapping's value
1530 +     * @return a {@code Map} containing the specified mappings
1531 +     * @throws IllegalArgumentException if there are any duplicate keys
1532 +     * @throws NullPointerException if any key or value is {@code null}
1533 +     *
1534 +     * @since 9
1535 +     */
1536 +    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,
1537 +                               K k6, V v6, K k7, V v7, K k8, V v8) {
1538 +        Map<K, V> map = new HashMap<>(11); // specify number of buckets to avoid resizing
1539 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1540 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1541 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1542 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1543 +        map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5));
1544 +        map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6));
1545 +        map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7));
1546 +        map.put(Objects.requireNonNull(k8), Objects.requireNonNull(v8));
1547 +        if (map.size() != 8) {
1548 +            throw new IllegalArgumentException("duplicate keys");
1549 +        }
1550 +        return Collections.unmodifiableMap(map);
1551 +    }
1552 +
1553 +    /**
1554 +     * Returns an immutable map containing nine mappings.
1555 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1556 +     *
1557 +     * @param <K> the {@code Map}'s key type
1558 +     * @param <V> the {@code Map}'s value type
1559 +     * @param k1 the first mapping's key
1560 +     * @param v1 the first mapping's value
1561 +     * @param k2 the second mapping's key
1562 +     * @param v2 the second mapping's value
1563 +     * @param k3 the third mapping's key
1564 +     * @param v3 the third mapping's value
1565 +     * @param k4 the fourth mapping's key
1566 +     * @param v4 the fourth mapping's value
1567 +     * @param k5 the fifth mapping's key
1568 +     * @param v5 the fifth mapping's value
1569 +     * @param k6 the sixth mapping's key
1570 +     * @param v6 the sixth mapping's value
1571 +     * @param k7 the seventh mapping's key
1572 +     * @param v7 the seventh mapping's value
1573 +     * @param k8 the eighth mapping's key
1574 +     * @param v8 the eighth mapping's value
1575 +     * @param k9 the ninth mapping's key
1576 +     * @param v9 the ninth mapping's value
1577 +     * @return a {@code Map} containing the specified mappings
1578 +     * @throws IllegalArgumentException if there are any duplicate keys
1579 +     * @throws NullPointerException if any key or value is {@code null}
1580 +     *
1581 +     * @since 9
1582 +     */
1583 +    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,
1584 +                               K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9) {
1585 +        Map<K, V> map = new HashMap<>(13); // specify number of buckets to avoid resizing
1586 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1587 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1588 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1589 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1590 +        map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5));
1591 +        map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6));
1592 +        map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7));
1593 +        map.put(Objects.requireNonNull(k8), Objects.requireNonNull(v8));
1594 +        map.put(Objects.requireNonNull(k9), Objects.requireNonNull(v9));
1595 +        if (map.size() != 9) {
1596 +            throw new IllegalArgumentException("duplicate keys");
1597 +        }
1598 +        return Collections.unmodifiableMap(map);
1599 +    }
1600 +
1601 +    /**
1602 +     * Returns an immutable map containing ten mappings.
1603 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1604 +     *
1605 +     * @param <K> the {@code Map}'s key type
1606 +     * @param <V> the {@code Map}'s value type
1607 +     * @param k1 the first mapping's key
1608 +     * @param v1 the first mapping's value
1609 +     * @param k2 the second mapping's key
1610 +     * @param v2 the second mapping's value
1611 +     * @param k3 the third mapping's key
1612 +     * @param v3 the third mapping's value
1613 +     * @param k4 the fourth mapping's key
1614 +     * @param v4 the fourth mapping's value
1615 +     * @param k5 the fifth mapping's key
1616 +     * @param v5 the fifth mapping's value
1617 +     * @param k6 the sixth mapping's key
1618 +     * @param v6 the sixth mapping's value
1619 +     * @param k7 the seventh mapping's key
1620 +     * @param v7 the seventh mapping's value
1621 +     * @param k8 the eighth mapping's key
1622 +     * @param v8 the eighth mapping's value
1623 +     * @param k9 the ninth mapping's key
1624 +     * @param v9 the ninth mapping's value
1625 +     * @param k10 the tenth mapping's key
1626 +     * @param v10 the tenth mapping's value
1627 +     * @return a {@code Map} containing the specified mappings
1628 +     * @throws IllegalArgumentException if there are any duplicate keys
1629 +     * @throws NullPointerException if any key or value is {@code null}
1630 +     *
1631 +     * @since 9
1632 +     */
1633 +    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,
1634 +                               K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10) {
1635 +        Map<K, V> map = new HashMap<>(14); // specify number of buckets to avoid resizing
1636 +        map.put(Objects.requireNonNull(k1), Objects.requireNonNull(v1));
1637 +        map.put(Objects.requireNonNull(k2), Objects.requireNonNull(v2));
1638 +        map.put(Objects.requireNonNull(k3), Objects.requireNonNull(v3));
1639 +        map.put(Objects.requireNonNull(k4), Objects.requireNonNull(v4));
1640 +        map.put(Objects.requireNonNull(k5), Objects.requireNonNull(v5));
1641 +        map.put(Objects.requireNonNull(k6), Objects.requireNonNull(v6));
1642 +        map.put(Objects.requireNonNull(k7), Objects.requireNonNull(v7));
1643 +        map.put(Objects.requireNonNull(k8), Objects.requireNonNull(v8));
1644 +        map.put(Objects.requireNonNull(k9), Objects.requireNonNull(v9));
1645 +        map.put(Objects.requireNonNull(k10), Objects.requireNonNull(v10));
1646 +        if (map.size() != 10) {
1647 +            throw new IllegalArgumentException("duplicate keys");
1648 +        }
1649 +        return Collections.unmodifiableMap(map);
1650 +    }
1651 +
1652 +    /**
1653 +     * Returns an immutable map containing keys and values extracted from the given entries.
1654 +     * The entries themselves are not stored in the map.
1655 +     * See <a href="#immutable">Immutable Map Static Factory Methods</a> for details.
1656 +     *
1657 +     * @apiNote
1658 +     * It is convenient to create the map entries using the {@link Map#entry Map.entry()} method.
1659 +     * For example,
1660 +     *
1661 +     * <pre>{@code
1662 +     *     import static java.util.Map.entry;
1663 +     *
1664 +     *     Map<Integer,String> map = Map.ofEntries(
1665 +     *         entry(1, "a"),
1666 +     *         entry(2, "b"),
1667 +     *         entry(3, "c"),
1668 +     *         ...
1669 +     *         entry(26, "z"));
1670 +     * }</pre>
1671 +     *
1672 +     * @param <K> the {@code Map}'s key type
1673 +     * @param <V> the {@code Map}'s value type
1674 +     * @param entries {@code Map.Entry}s containing the keys and values from which the map is populated
1675 +     * @return a {@code Map} containing the specified mappings
1676 +     * @throws IllegalArgumentException if there are any duplicate keys
1677 +     * @throws NullPointerException if any entry, key, or value is {@code null}, or if
1678 +     *         the {@code entries} array is {@code null}
1679 +     *
1680 +     * @see Map#entry Map.entry()
1681 +     * @since 9
1682 +     */
1683 +    @SafeVarargs
1684 +    @SuppressWarnings("varargs")
1685 +    static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries) {
1686 +        Map<K, V> map = new HashMap<>(entries.length * 4 / 3 + 1); // throws NPE if entries is null
1687 +        for (Entry<? extends K, ? extends V> e : entries) {
1688 +            // next line throws NPE if e is null
1689 +            map.put(Objects.requireNonNull(e.getKey()), Objects.requireNonNull(e.getValue()));
1690 +        }
1691 +        if (map.size() != entries.length) {
1692 +            throw new IllegalArgumentException("duplicate keys");
1693 +        }
1694 +        return Collections.unmodifiableMap(map);
1695 +    }
1696 +
1697 +    /**
1698 +     * Returns an immutable {@link Entry} containing the given key and value.
1699 +     * These entries are suitable for populating {@code Map} instances using the
1700 +     * {@link Map#ofEntries Map.ofEntries()} method.
1701 +     * The {@code Entry} instances created by this method have the following characteristics:
1702 +     *
1703 +     * <ul>
1704 +     * <li>They disallow {@code null} keys and values. Attempts to create them using a {@code null}
1705 +     * key or value result in {@code NullPointerException}.
1706 +     * <li>They are immutable. Calls to {@link Entry#setValue Entry.setValue()}
1707 +     * on a returned {@code Entry} result in {@code UnsupportedOperationException}.
1708 +     * <li>They are not serializable.
1709 +     * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
1710 +     * Callers should make no assumptions about the identity of the returned instances.
1711 +     * This method is free to create new instances or reuse existing ones. Therefore,
1712 +     * identity-sensitive operations on these instances (reference equality ({@code ==}),
1713 +     * identity hash code, and synchronization) are unreliable and should be avoided.
1714 +     * </ul>
1715 +     *
1716 +     * @apiNote
1717 +     * For a serializable {@code Entry}, see {@link AbstractMap.SimpleEntry} or
1718 +     * {@link AbstractMap.SimpleImmutableEntry}.
1719 +     *
1720 +     * @param <K> the key's type
1721 +     * @param <V> the value's type
1722 +     * @param k the key
1723 +     * @param v the value
1724 +     * @return an {@code Entry} containing the specified key and value
1725 +     * @throws NullPointerException if the key or value is {@code null}
1726 +     *
1727 +     * @see Map#ofEntries Map.ofEntries()
1728 +     * @since 9
1729 +     */
1730 +    static <K, V> Entry<K, V> entry(K k, V v) {
1731 +        // KeyValueHolder checks for nulls
1732 +        return new KeyValueHolder<>(k, v);
1733 +    }
1734   }

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines