Package org.apache.commons.collections4.map

# Class DefaultedMap<K,V>

java.lang.Object
org.apache.commons.collections4.map.AbstractIterableMap<K,V>
org.apache.commons.collections4.map.AbstractMapDecorator<K,V>
org.apache.commons.collections4.map.DefaultedMap<K,V>

Type Parameters:
  `K` - the type of the keys in this map
  `V` - the type of the values in this map

All Implemented Interfaces:
  `Serializable`, `Map<K,V>`, `Get<K,V>`, `IterableGet<K,V>`, `IterableMap<K,V>`, `Put<K,V>`

public class DefaultedMap<K,V> extends AbstractMapDecorator<K,V> implements Serializable
Decorates another `Map` returning a default value if the map does not contain the requested key.

When the `get(Object)` method is called with a key that does not exist in the map, this map will return the default value specified in the constructor/factory. Only the get method is altered, so the `Map.containsKey(Object)` can be used to determine if a key really is in the map or not.

The defaulted value is not added to the map. Compare this behavior with `LazyMap`, which does add the value to the map (via a Transformer).

For instance:

     Map map = new DefaultedMap("NULL");
     Object obj = map.get("Surname");
     // obj == "NULL"

After the above code is executed the map is still empty.

Note that DefaultedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. The simplest approach is to wrap this map using `Collections.synchronizedMap(Map)`. This class may throw exceptions when accessed by concurrent threads without synchronization.

Since:
  3.2
See Also:
  - `LazyMap`
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface java.util.Map

  `Map.Entry<K,V>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DefaultedMap(Map<K,V> map, Transformer<? super K,? extends V> defaultValueTransformer)`
  Constructor that wraps (not copies).
  ``
  `DefaultedMap(Transformer<? super K,? extends V> defaultValueTransformer)`
  Constructs a new empty `DefaultedMap` that decorates a `HashMap`.
  ``
  `DefaultedMap(V defaultValue)`
  Constructs a new empty `DefaultedMap` that decorates a `HashMap`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <K, V> DefaultedMap<K,V>`
  `defaultedMap(Map<K,V> map, Factory<? extends V> factory)`
  Factory method to create a defaulting map.
  `static <K, V> Map<K,V>`
  `defaultedMap(Map<K,V> map, Transformer<? super K,? extends V> transformer)`
  Factory method to create a defaulting map.
  `static <K, V> DefaultedMap<K,V>`
  `defaultedMap(Map<K,V> map, V defaultValue)`
  Factory method to create a defaulting map.
  `V`
  `get(Object key)`
  Gets a value at a given key.

  ### Methods inherited from class org.apache.commons.collections4.map.AbstractMapDecorator

  `clear, containsKey, containsValue, decorated, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, toString, values`

  ### Methods inherited from class org.apache.commons.collections4.map.AbstractIterableMap

  `mapIterator`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Constructor Details

  - ### DefaultedMap

    protected DefaultedMap(Map<K,V> map, Transformer<? super K,? extends V> defaultValueTransformer)
    Constructor that wraps (not copies).
    Parameters:
      `map` - the map to decorate, must not be null
      `defaultValueTransformer` - the value transformer to use
    Throws:
      `NullPointerException` - if map or transformer is null

  - ### DefaultedMap

    public DefaultedMap(Transformer<? super K,? extends V> defaultValueTransformer)
    Constructs a new empty `DefaultedMap` that decorates a `HashMap`.
    Parameters:
      `defaultValueTransformer` - transformer to use to generate missing values.

  - ### DefaultedMap

    public DefaultedMap(V defaultValue)
    Constructs a new empty `DefaultedMap` that decorates a `HashMap`.

    The object passed in will be returned by the map whenever an unknown key is requested.

    Parameters:
      `defaultValue` - the default value to return when the key is not found

- ## Method Details

  - ### defaultedMap

    public static <K, V> DefaultedMap<K,V> defaultedMap(Map<K,V> map, Factory<? extends V> factory)
    Factory method to create a defaulting map.

    The factory specified is called when a missing key is found. The result will be returned as the result of the map get(key) method.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the map to decorate, must not be null
      `factory` - the factory to use to create entries, must not be null
    Returns:
      a new defaulting map
    Throws:
      `NullPointerException` - if map or factory is null
    Since:
      4.0

  - ### defaultedMap

    public static <K, V> Map<K,V> defaultedMap(Map<K,V> map, Transformer<? super K,? extends V> transformer)
    Factory method to create a defaulting map.

    The transformer specified is called when a missing key is found. The key is passed to the transformer as the input, and the result will be returned as the result of the map get(key) method.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the map to decorate, must not be null
      `transformer` - the transformer to use as a factory to create entries, must not be null
    Returns:
      a new defaulting map
    Throws:
      `NullPointerException` - if map or transformer is null
    Since:
      4.0

  - ### defaultedMap

    public static <K, V> DefaultedMap<K,V> defaultedMap(Map<K,V> map, V defaultValue)
    Factory method to create a defaulting map.

    The value specified is returned when a missing key is found.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the map to decorate, must not be null
      `defaultValue` - the default value to return when the key is not found
    Returns:
      a new defaulting map
    Throws:
      `NullPointerException` - if map is null
    Since:
      4.0

  - ### get

    public V get(Object key)
    Description copied from interface: `Get`
    Gets a value at a given key.
    Specified by:
      `get` in interface `Get<K,V>`
    Specified by:
      `get` in interface `Map<K,V>`
    Overrides:
      `get` in class `AbstractMapDecorator<K,V>`
    Parameters:
      `key` - the key whose associated value is to be returned
    Returns:
      the value to which the specified key is mapped, or `null` if this map contains no mapping for the key
    See Also:
      - `Map.get(Object)`