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>

- 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 behaviour 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
  Version:
    $Id: DefaultedMap.java 1479407 2013-05-05 22:07:53Z tn $
  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 and 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

    Methods
    Modifier and Type | Method and 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)`

    - ### 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`

- - ### Constructor Detail

    - #### 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

    - #### 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

          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:
        `IllegalArgumentException` - if map or transformer is null

  - ### Method Detail

    - #### 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:
        `IllegalArgumentException` - if map is null
      Since:
        4.0

    - #### 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:
        `IllegalArgumentException` - 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:
        `IllegalArgumentException` - if map or factory is null
      Since:
        4.0

    - #### get

          public V get(Object key)

      Specified by:
        `get` in interface `Map<K,V>`
      Specified by:
        `get` in interface `Get<K,V>`
      Overrides:
        `get` in class `AbstractMapDecorator<K,V>`
      See Also:
        `Map.get(Object)`

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.