Apache Commons Collections 4.4 · org.apache.commons.collections4.map.DefaultedMap

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 java.util.Collections#synchronizedMap(Map). This class may throw exceptions when accessed by concurrent threads without synchronization.

Field Summary

Modifier and Type	Field and Description
private static final long	serialVersionUID Serialization version
private final Transformer<? super K, ? extends V>	value The transformer to use if the map does not contain a key

Inherited from org.apache.commons.collections4.map.AbstractMapDecorator:: map

Constructor Summary

Access	Constructor and Description
public	DefaultedMap(final V the default value to return when the key is not found defaultValue) Constructs a new empty `DefaultedMap` that decorates a `HashMap`.
public	DefaultedMap(final Transformer<? super K, ? extends V> transformer to use to generate missing values. defaultValueTransformer) Constructs a new empty `DefaultedMap` that decorates a `HashMap`.
protected	DefaultedMap(final Map<K, V> the map to decorate, must not be null map, final Transformer<? super K, ? extends V> the value transformer to use defaultValueTransformer) Constructor that wraps (not copies).

Method Summary

Modifier and Type	Method and Description
public static < the key type K, the value type V> DefaultedMap<K, V>	Returns: a new defaulting map defaultedMap(final Map<K, V> the map to decorate, must not be null map, final V the default value to return when the key is not found defaultValue) Factory method to create a defaulting map.
public static < the key type K, the value type V> DefaultedMap<K, V>	Returns: a new defaulting map defaultedMap(final Map<K, V> the map to decorate, must not be null map, final Factory<? extends V> the factory to use to create entries, must not be null factory) Factory method to create a defaulting map.
public static < the key type K, the value type V> Map<K, V>	Returns: a new defaulting map defaultedMap(final Map<K, V> the map to decorate, must not be null map, final Transformer<? super K, ? extends V> the transformer to use as a factory to create entries, must not be null transformer) Factory method to create a defaulting map.
public V	get(final Object the key whose associated value is to be returned key) Overrides org.apache.commons.collections4.map.AbstractMapDecorator.get. Implements java.util.Map.get, org.apache.commons.collections4.Get.get. Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.
private void	readObject(final ObjectInputStream the input stream in) Read the map in using a custom routine.
private void	writeObject(final ObjectOutputStream the output stream out) Write the map out using a custom routine.

Inherited from org.apache.commons.collections4.map.AbstractMapDecorator:: clear containsKey containsValue decorated entrySet equals hashCode isEmpty keySet put putAll remove size toString values

Field Detail

serialVersionUID	back to summary
private static final long serialVersionUID Serialization version

value	back to summary
private final Transformer<? super K, ? extends V> value The transformer to use if the map does not contain a key

Constructor Detail

DefaultedMap back to summary

DefaultedMap	back to summary
public DefaultedMap(final 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:V the default value to return when the key is not found

public DefaultedMap(final 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:V: the default value to return when the key is not found

DefaultedMap back to summary

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

public DefaultedMap(final Transformer<? super K, ? extends V> defaultValueTransformer)

Constructs a new empty DefaultedMap that decorates a HashMap.

Parameters

defaultValueTransformer:Transformer<? super K, ? extends V>: transformer to use to generate missing values.

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

DefaultedMap

back to summary

protected DefaultedMap(final Map<K, V> map, final Transformer<? super K, ? extends V> defaultValueTransformer)

Constructor that wraps (not copies).

Parameters

map:Map<K, V>: the map to decorate, must not be null
defaultValueTransformer:Transformer<? super K, ? extends V>: the value transformer to use

Exceptions

NullPointerException:: if map or transformer is null

Method Detail

defaultedMap	back to summary
public static <K, V> DefaultedMap<K, V> defaultedMap(final Map<K, V> map, final V defaultValue) Factory method to create a defaulting map. The value specified is returned when a missing key is found. Parameters <K> the key type <V> the value type map:Map<K, V> the map to decorate, must not be null defaultValue:V the default value to return when the key is not found Returns:DefaultedMap<K, V> a new defaulting map Exceptions NullPointerException: if map is null Since 4.0

defaultedMap

back to summary

public static <K, V> DefaultedMap<K, V> defaultedMap(final Map<K, V> map, final V defaultValue)

Factory method to create a defaulting map.

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

Parameters

<K>: the key type
<V>: the value type
map:Map<K, V>: the map to decorate, must not be null
defaultValue:V: the default value to return when the key is not found

Returns:DefaultedMap<K, V>

a new defaulting map

Exceptions

NullPointerException:: if map is null

Since

4.0

defaultedMap	back to summary
public static <K, V> DefaultedMap<K, V> defaultedMap(final Map<K, V> map, final 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. Parameters <K> the key type <V> the value type map:Map<K, V> the map to decorate, must not be null factory:Factory<? extends V> the factory to use to create entries, must not be null Returns:DefaultedMap<K, V> a new defaulting map Exceptions NullPointerException: if map or factory is null Since 4.0

defaultedMap

back to summary

public static <K, V> DefaultedMap<K, V> defaultedMap(final Map<K, V> map, final 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.

Parameters

<K>: the key type
<V>: the value type
map:Map<K, V>: the map to decorate, must not be null
factory:Factory<? extends V>: the factory to use to create entries, must not be null

Returns:DefaultedMap<K, V>

a new defaulting map

Exceptions

NullPointerException:: if map or factory is null

Since

4.0

defaultedMap	back to summary
public static <K, V> Map<K, V> defaultedMap(final Map<K, V> map, final 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. Parameters <K> the key type <V> the value type map:Map<K, V> the map to decorate, must not be null transformer:Transformer<? super K, ? extends V> the transformer to use as a factory to create entries, must not be null Returns:Map<K, V> a new defaulting map Exceptions NullPointerException: if map or factory is null Since 4.0

defaultedMap

back to summary

public static <K, V> Map<K, V> defaultedMap(final Map<K, V> map, final 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.

Parameters

<K>: the key type
<V>: the value type
map:Map<K, V>: the map to decorate, must not be null
transformer:Transformer<? super K, ? extends V>: the transformer to use as a factory to create entries, must not be null

Returns:Map<K, V>

a new defaulting map

Exceptions

NullPointerException:: if map or factory is null

Since

4.0

get back to summary

get	back to summary
public V get(final Object key) Overrides org.apache.commons.collections4.map.AbstractMapDecorator.get. Implements java.util.Map.get, org.apache.commons.collections4.Get.get. Doc from java.util.Map.get. Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key. More formally, if this map contains a mapping from a key `k` to a value `v` such that `Objects.equals(key, k)`, then this method returns `v`; otherwise it returns `null`. (There can be at most one such mapping.) If this map permits null values, then a return value of `null` does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to `null`. The `containsKey` operation may be used to distinguish these two cases. Parameters key:Object the key whose associated value is to be returned Returns:V the value to which the specified key is mapped, or `null` if this map contains no mapping for the key Annotations @Override @SuppressWarnings:unchecked

public V get(final Object key)

Overrides org.apache.commons.collections4.map.AbstractMapDecorator.get.

Implements java.util.Map.get, org.apache.commons.collections4.Get.get.

Doc from java.util.Map.get.

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

More formally, if this map contains a mapping from a key k to a value v such that Objects.equals(key, k), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

If this map permits null values, then a return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

Parameters

key:Object: the key whose associated value is to be returned

Returns:V

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Annotations

@Override
@SuppressWarnings:unchecked

readObject	back to summary
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException Read the map in using a custom routine. Parameters in:ObjectInputStream the input stream Annotations @SuppressWarnings:unchecked Exceptions IOException: if an error occurs while reading from the stream ClassNotFoundException: if an object read from the stream can not be loaded

readObject

back to summary

private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException

Read the map in using a custom routine.

Parameters

in:ObjectInputStream: the input stream

Annotations

@SuppressWarnings:unchecked

Exceptions

IOException:: if an error occurs while reading from the stream
ClassNotFoundException:: if an object read from the stream can not be loaded

writeObject	back to summary
private void writeObject(final ObjectOutputStream out) throws IOException Write the map out using a custom routine. Parameters out:ObjectOutputStream the output stream Exceptions IOException: if an error occurs while writing to the stream

writeObject

back to summary

private void writeObject(final ObjectOutputStream out) throws IOException

Write the map out using a custom routine.

Parameters

out:ObjectOutputStream: the output stream

Exceptions

IOException:: if an error occurs while writing to the stream

public Class DefaultedMap<K, V>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail