java8.util

Class Maps2

java.lang.Object

java8.util.Maps2

public final class Maps2
extends Object

A place for the new Java 9 JEP 269 "Immutable Map Static Factory Methods" in the Map interface.

Immutable Map Static Factory Methods

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

• They are structurally immutable. Keys and values cannot be added, removed, or updated. Calling any mutator method 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.

Method Summary

Modifier and Type	Method and Description
static <K,V> Map.Entry<K,V>	entry(K k, V v) Returns an immutable Map.Entry containing the given key and value.
static <K,V> Map<K,V>	of() Returns an immutable map containing zero mappings.
static <K,V> Map<K,V>	of(K k1, V v1) Returns an immutable map containing a single mapping.
static <K,V> Map<K,V>	of(K k1, V v1, K k2, V v2) Returns an immutable 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 immutable 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 immutable 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 immutable 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 immutable 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 immutable 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 immutable 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 immutable 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 immutable map containing ten mappings.
static <K,V> Map<K,V>	ofEntries(Map.Entry<? extends K,? extends V>... entries) Returns an immutable 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 immutable map containing zero mappings. See Immutable Map Static Factory Methods 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 immutable map containing a single mapping. See Immutable Map Static Factory Methods 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 immutable map containing two mappings. See Immutable Map Static Factory Methods 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 immutable map containing three mappings. See Immutable Map Static Factory Methods 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 immutable map containing four mappings. See Immutable Map Static Factory Methods 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 immutable map containing five mappings. See Immutable Map Static Factory Methods 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 immutable map containing six mappings. See Immutable Map Static Factory Methods 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 immutable map containing seven mappings. See Immutable Map Static Factory Methods 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 immutable map containing eight mappings. See Immutable Map Static Factory Methods 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 immutable map containing nine mappings. See Immutable Map Static Factory Methods 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 immutable map containing ten mappings. See Immutable Map Static Factory Methods 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

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

Returns an immutable map containing keys and values extracted from the given entries. The entries themselves are not stored in the map. See Immutable Map Static Factory Methods 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 immutable 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 immutable. 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()