java9.util

Class Maps

java.lang.Object

java9.util.Maps

public final class Maps
extends Object

A place for the implementations of the new Java 9 static interface methods in the Map interface specified in JEP 269 "Unmodifiable Map Static Factory Methods".

Unmodifiable Maps

The Maps.of, Maps.ofEntries, and Maps.copyOf static factory methods provide a convenient way to create unmodifiable maps. The Map instances created by these methods have the following characteristics:

• They are unmodifiable. Keys and values cannot be added, removed, or updated. Calling any mutator method on the Map will always cause UnsupportedOperationException to be thrown. However, if the contained keys or values are themselves mutable, this may cause the Map to behave inconsistently or its contents to appear to change.
• They disallow null keys and values. Attempts to create them with null keys or values result in NullPointerException.
• They are serializable if all keys and values are serializable.
• They reject duplicate keys at creation time. Duplicate keys passed to a static factory method result in IllegalArgumentException.
• The iteration order of mappings is unspecified and is subject to change.
• They are value-based. Callers should make no assumptions about the identity of the returned instances. Factories are free to create new instances or reuse existing ones. Therefore, identity-sensitive operations on these instances (reference equality ( ==), identity hash code, and synchronization) are unreliable and should be avoided.

Since:

9

Method Summary

Modifier and Type	Method and Description
static <K,V> Map<K,V>	copyOf(Map<? extends K,? extends V> map) Returns an unmodifiable Map containing the entries of the given Map.
static <K,V> Map.Entry<K,V>	entry(K k, V v) Returns an unmodifiable Map.Entry containing the given key and value.
static <K,V> Map<K,V>	of() Returns an unmodifiable map containing zero mappings.
static <K,V> Map<K,V>	of(K k1, V v1) Returns an unmodifiable map containing a single mapping.
static <K,V> Map<K,V>	of(K k1, V v1, K k2, V v2) Returns an unmodifiable map containing two mappings.
static <K,V> Map<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3) Returns an unmodifiable map containing three mappings.
static <K,V> Map<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4) Returns an unmodifiable map containing four mappings.
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) Returns an unmodifiable map containing five mappings.
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, K k6, V v6) Returns an unmodifiable map containing six mappings.
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, K k6, V v6, K k7, V v7) Returns an unmodifiable map containing seven mappings.
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, K k6, V v6, K k7, V v7, K k8, V v8) Returns an unmodifiable map containing eight mappings.
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, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9) Returns an unmodifiable map containing nine mappings.
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, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10) Returns an unmodifiable map containing ten mappings.
static <K,V> Map<K,V>	ofEntries(Map.Entry<? extends K,? extends V>... entries) Returns an unmodifiable map containing keys and values extracted from the given entries.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

of

public static <K,V> Map<K,V> of()

Returns an unmodifiable map containing zero mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Returns:

an empty Map

Since:

9

of

public static <K,V> Map<K,V> of(K k1,
                                V v1)

Returns an unmodifiable map containing a single mapping. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the mapping's key

v1 - the mapping's value

Returns:

a Map containing the specified mapping

Throws:

NullPointerException - if the key or the value is null

Since:

9

of

public static <K,V> Map<K,V> of(K k1,
                                V v1,
                                K k2,
                                V v2)

Returns an unmodifiable map containing two mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if the keys are duplicates

NullPointerException - if any key or value is null

Since:

9

of

public static <K,V> Map<K,V> of(K k1,
                                V v1,
                                K k2,
                                V v2,
                                K k3,
                                V v3)

Returns an unmodifiable map containing three mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public static <K,V> Map<K,V> of(K k1,
                                V v1,
                                K k2,
                                V v2,
                                K k3,
                                V v3,
                                K k4,
                                V v4)

Returns an unmodifiable map containing four mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public 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)

Returns an unmodifiable map containing five mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

k5 - the fifth mapping's key

v5 - the fifth mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public 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,
                                K k6,
                                V v6)

Returns an unmodifiable map containing six mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

k5 - the fifth mapping's key

v5 - the fifth mapping's value

k6 - the sixth mapping's key

v6 - the sixth mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public 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,
                                K k6,
                                V v6,
                                K k7,
                                V v7)

Returns an unmodifiable map containing seven mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

k5 - the fifth mapping's key

v5 - the fifth mapping's value

k6 - the sixth mapping's key

v6 - the sixth mapping's value

k7 - the seventh mapping's key

v7 - the seventh mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public 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,
                                K k6,
                                V v6,
                                K k7,
                                V v7,
                                K k8,
                                V v8)

Returns an unmodifiable map containing eight mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

k5 - the fifth mapping's key

v5 - the fifth mapping's value

k6 - the sixth mapping's key

v6 - the sixth mapping's value

k7 - the seventh mapping's key

v7 - the seventh mapping's value

k8 - the eighth mapping's key

v8 - the eighth mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public 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,
                                K k6,
                                V v6,
                                K k7,
                                V v7,
                                K k8,
                                V v8,
                                K k9,
                                V v9)

Returns an unmodifiable map containing nine mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

k5 - the fifth mapping's key

v5 - the fifth mapping's value

k6 - the sixth mapping's key

v6 - the sixth mapping's value

k7 - the seventh mapping's key

v7 - the seventh mapping's value

k8 - the eighth mapping's key

v8 - the eighth mapping's value

k9 - the ninth mapping's key

v9 - the ninth mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

of

public 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,
                                K k6,
                                V v6,
                                K k7,
                                V v7,
                                K k8,
                                V v8,
                                K k9,
                                V v9,
                                K k10,
                                V v10)

Returns an unmodifiable map containing ten mappings. See Unmodifiable Maps for details.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

k1 - the first mapping's key

v1 - the first mapping's value

k2 - the second mapping's key

v2 - the second mapping's value

k3 - the third mapping's key

v3 - the third mapping's value

k4 - the fourth mapping's key

v4 - the fourth mapping's value

k5 - the fifth mapping's key

v5 - the fifth mapping's value

k6 - the sixth mapping's key

v6 - the sixth mapping's value

k7 - the seventh mapping's key

v7 - the seventh mapping's value

k8 - the eighth mapping's key

v8 - the eighth mapping's value

k9 - the ninth mapping's key

v9 - the ninth mapping's value

k10 - the tenth mapping's key

v10 - the tenth mapping's value

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any key or value is null

Since:

9

ofEntries

@SafeVarargs
public static <K,V> Map<K,V> ofEntries(Map.Entry<? extends K,? extends V>... entries)

Returns an unmodifiable map containing keys and values extracted from the given entries. The entries themselves are not stored in the map. See Unmodifiable Maps for details.

API Note:
It is convenient to create the map entries using the Maps.entry() method. For example,

 
     import static java.util.Maps.entry;

     Map<Integer,String> map = Maps.ofEntries(
         entry(1, "a"),
         entry(2, "b"),
         entry(3, "c"),
         ...
         entry(26, "z"));
 

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

entries - Map.Entrys containing the keys and values from which the map is populated

Returns:

a Map containing the specified mappings

Throws:

IllegalArgumentException - if there are any duplicate keys

NullPointerException - if any entry, key, or value is null, or if the entries array is null

Since:

9

See Also:

Maps.entry()

entry

public static <K,V> Map.Entry<K,V> entry(K k,
                                         V v)

Returns an unmodifiable Map.Entry containing the given key and value. These entries are suitable for populating Map instances using the Maps.ofEntries() method. The Entry instances created by this method have the following characteristics:

• They disallow null keys and values. Attempts to create them using a null key or value result in NullPointerException.
• They are unmodifiable. Calls to Entry.setValue() on a returned Entry result in UnsupportedOperationException.
• They are not serializable.
• They are value-based. Callers should make no assumptions about the identity of the returned instances. This method is free to create new instances or reuse existing ones. Therefore, identity-sensitive operations on these instances (reference equality (==), identity hash code, and synchronization) are unreliable and should be avoided.

API Note:
For a serializable Entry, see AbstractMap.SimpleEntry or AbstractMap.SimpleImmutableEntry.

Type Parameters:

K - the key's type

V - the value's type

Parameters:

k - the key

v - the value

Returns:

an Entry containing the specified key and value

Throws:

NullPointerException - if the key or value is null

Since:

9

See Also:

Maps.ofEntries()

copyOf

public static <K,V> Map<K,V> copyOf(Map<? extends K,? extends V> map)

Returns an unmodifiable Map containing the entries of the given Map. The given Map must not be null, and it must not contain any null keys or values. If the given Map is subsequently modified, the returned Map will not reflect such modifications.

Implementation Note: If the given Map is an unmodifiable Map, calling copyOf will generally not create a copy.

Type Parameters:

K - the Map's key type

V - the Map's value type

Parameters:

map - the map from which entries are drawn, must be non-null

Returns:

a Map containing the entries of the given Map

Throws:

NullPointerException - if map is null, or if it contains any null keys or values

Since:

10