Package org.apache.commons.collections4.map

# Class ListOrderedMap<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.ListOrderedMap<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>`, `OrderedMap<K,V>`, `Put<K,V>`

public class ListOrderedMap<K,V> extends AbstractMapDecorator<K,V> implements OrderedMap<K,V>, Serializable
Decorates a `Map` to ensure that the order of addition is retained using a `List` to maintain order.

The order will be used via the iterators and toArray methods on the views. The order is also returned by the `MapIterator`. The `orderedMapIterator()` method accesses an iterator that can iterate both forwards and backwards through the map. In addition, non-interface methods are provided to access the map by index.

If an object is added to the Map for a second time, it will remain in the original position in the iteration.

Note that ListOrderedMap 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.

Note that ListOrderedMap doesn't work with `IdentityHashMap`, `CaseInsensitiveMap`, or similar maps that violate the general contract of `Map`. The `ListOrderedMap` (or, more precisely, the underlying `List`) is relying on `equals()`. This is fine, as long as the decorated `Map` is also based on `equals()`, and `hashCode()`, which `IdentityHashMap`, and `CaseInsensitiveMap` don't: The former uses `==`, and the latter uses `equals()` on a lower-cased key.

This class is `Serializable` starting with Commons Collections 3.1.

Since:
  3.0
See Also:
  - Serialized Form

- ## Nested Class Summary

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

  `Map.Entry<K extends Object,V extends Object>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `ListOrderedMap()`
  Constructs a new empty `ListOrderedMap` that decorates a `HashMap`.
  `protected`
  `ListOrderedMap(Map<K,V> map)`
  Constructor that wraps (not copies).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<K>`
  `asList()`
  Gets an unmodifiable List view of the keys which changes as the map changes.
  `void`
  `clear()`
  `Set<Map.Entry<K,V>>`
  `entrySet()`
  Gets a view over the entries in the map.
  `K`
  `firstKey()`
  Gets the first key in this map by insert order.
  `K`
  `get(int index)`
  Gets the key at the specified index.
  `V`
  `getValue(int index)`
  Gets the value at the specified index.
  `int`
  `indexOf(Object key)`
  Gets the index of the specified key.
  `List<K>`
  `keyList()`
  Gets a view over the keys in the map as a List.
  `Set<K>`
  `keySet()`
  Gets a view over the keys in the map.
  `K`
  `lastKey()`
  Gets the last key in this map by insert order.
  `static <K, V> ListOrderedMap<K,V>`
  `listOrderedMap(Map<K,V> map)`
  Factory method to create an ordered map.
  `OrderedMapIterator<K,V>`
  `mapIterator()`
  Obtains a `MapIterator` over the map.
  `K`
  `nextKey(Object key)`
  Gets the next key to the one specified using insert order.
  `K`
  `previousKey(Object key)`
  Gets the previous key to the one specified using insert order.
  `V`
  `put(int index, K key, V value)`
  Puts a key-value mapping into the map at the specified index.
  `V`
  `put(K key, V value)`
  Note that the return type is Object, rather than V as in the Map interface.
  `void`
  `putAll(int index, Map<? extends K,? extends V> map)`
  Puts the values contained in a supplied Map into the Map starting at the specified index.
  `void`
  `putAll(Map<? extends K,? extends V> map)`
  `V`
  `remove(int index)`
  Removes the element at the specified index.
  `V`
  `remove(Object key)`
  `V`
  `setValue(int index, V value)`
  Sets the value at the specified index.
  `String`
  `toString()`
  Returns the Map as a string.
  `List<V>`
  `valueList()`
  Gets a view over the values in the map as a List.
  `Collection<V>`
  `values()`
  Gets a view over the values in the map.

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

  `containsKey, containsValue, decorated, equals, get, hashCode, isEmpty, size`

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

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

  ### Methods inherited from interface org.apache.commons.collections4.Get

  `containsKey, containsValue, get, isEmpty, size`

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

  `compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size`

- ## Constructor Details

  - ### ListOrderedMap

    public ListOrderedMap()
    Constructs a new empty `ListOrderedMap` that decorates a `HashMap`.
    Since:
      3.1

  - ### ListOrderedMap

    protected ListOrderedMap(Map<K,V> map)
    Constructor that wraps (not copies).
    Parameters:
      `map` - the map to decorate, must not be null
    Throws:
      `NullPointerException` - if map is null

- ## Method Details

  - ### listOrderedMap

    public static <K, V> ListOrderedMap<K,V> listOrderedMap(Map<K,V> map)
    Factory method to create an ordered map.

    An `ArrayList` is used to retain order.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the map to decorate, must not be null
    Returns:
      a new list ordered map
    Throws:
      `NullPointerException` - if map is null
    Since:
      4.0

  - ### asList

    public List<K> asList()
    Gets an unmodifiable List view of the keys which changes as the map changes.

    The returned list is unmodifiable because changes to the values of the list (using `ListIterator.set(Object)`) will effectively remove the value from the list and reinsert that value at the end of the list, which is an unexpected side effect of changing the value of a list. This occurs because changing the key, changes when the mapping is added to the map and thus where it appears in the list.

    An alternative to this method is to use the better named `keyList()` or `keySet()`.

    Returns:
      The ordered list of keys.
    See Also:
      - `keyList()`
      - `keySet()`

  - ### clear

    public void clear()
    Specified by:
      `clear` in interface `Map<K,V>`
    Specified by:
      `clear` in interface `Put<K,V>`
    Overrides:
      `clear` in class `AbstractMapDecorator<K,V>`
    See Also:
      - `Map.clear()`

  - ### entrySet

    public Set<Map.Entry<K,V>> entrySet()
    Gets a view over the entries in the map.

    The Set will be ordered by object insertion into the map.

    Specified by:
      `entrySet` in interface `Get<K,V>`
    Specified by:
      `entrySet` in interface `Map<K,V>`
    Overrides:
      `entrySet` in class `AbstractMapDecorator<K,V>`
    Returns:
      the fully modifiable set view over the entries
    See Also:
      - `Map.entrySet()`

  - ### firstKey

    public K firstKey()
    Gets the first key in this map by insert order.
    Specified by:
      `firstKey` in interface `OrderedMap<K,V>`
    Returns:
      the first key currently in this map
    Throws:
      `NoSuchElementException` - if this map is empty

  - ### get

    public K get(int index)
    Gets the key at the specified index.
    Parameters:
      `index` - the index to retrieve
    Returns:
      the key at the specified index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### getValue

    public V getValue(int index)
    Gets the value at the specified index.
    Parameters:
      `index` - the index to retrieve
    Returns:
      the key at the specified index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### indexOf

    public int indexOf(Object key)
    Gets the index of the specified key.
    Parameters:
      `key` - the key to find the index of
    Returns:
      the index, or -1 if not found

  - ### keyList

    public List<K> keyList()
    Gets a view over the keys in the map as a List.

    The List will be ordered by object insertion into the map. The List is unmodifiable.

    Returns:
      the unmodifiable list view over the keys
    Since:
      3.2
    See Also:
      - `keySet()`

  - ### keySet

    public Set<K> keySet()
    Gets a view over the keys in the map.

    The Collection will be ordered by object insertion into the map.

    Specified by:
      `keySet` in interface `Get<K,V>`
    Specified by:
      `keySet` in interface `Map<K,V>`
    Overrides:
      `keySet` in class `AbstractMapDecorator<K,V>`
    Returns:
      the fully modifiable collection view over the keys
    See Also:
      - `keyList()`

  - ### lastKey

    public K lastKey()
    Gets the last key in this map by insert order.
    Specified by:
      `lastKey` in interface `OrderedMap<K,V>`
    Returns:
      the last key currently in this map
    Throws:
      `NoSuchElementException` - if this map is empty

  - ### mapIterator

    public OrderedMapIterator<K,V> mapIterator()
    Description copied from class: `AbstractIterableMap`
    Obtains a `MapIterator` over the map.

    A map iterator is an efficient way of iterating over maps. There is no need to access the entry set or use Map Entry objects.

         IterableMap<String,Integer> map = new HashedMap<String,Integer>();
         MapIterator<String,Integer> it = map.mapIterator();
         while (it.hasNext()) {
           String key = it.next();
           Integer value = it.getValue();
           it.setValue(value + 1);
         }

    Specified by:
      `mapIterator` in interface `IterableGet<K,V>`
    Specified by:
      `mapIterator` in interface `OrderedMap<K,V>`
    Overrides:
      `mapIterator` in class `AbstractIterableMap<K,V>`
    Returns:
      a map iterator

  - ### nextKey

    public K nextKey(Object key)
    Gets the next key to the one specified using insert order. This method performs a list search to find the key and is O(n).
    Specified by:
      `nextKey` in interface `OrderedMap<K,V>`
    Parameters:
      `key` - the key to find previous for
    Returns:
      the next key, null if no match or at start

  - ### previousKey

    public K previousKey(Object key)
    Gets the previous key to the one specified using insert order. This method performs a list search to find the key and is O(n).
    Specified by:
      `previousKey` in interface `OrderedMap<K,V>`
    Parameters:
      `key` - the key to find previous for
    Returns:
      the previous key, null if no match or at start

  - ### put

    public V put(int index, K key, V value)
    Puts a key-value mapping into the map at the specified index.

    If the map already contains the key, then the original mapping is removed and the new mapping added at the specified index. The remove may change the effect of the index. The index is always calculated relative to the original state of the map.

    Thus, the steps are: (1) remove the existing key-value mapping, then (2) insert the new key-value mapping at the position it would have been inserted had the remove not occurred.

    Parameters:
      `index` - the index at which the mapping should be inserted
      `key` - the key
      `value` - the value
    Returns:
      the value previously mapped to the key
    Throws:
      `IndexOutOfBoundsException` - if the index is out of range [0, size]
    Since:
      3.2

  - ### put

    public V put(K key, V value)
    Description copied from interface: `Put`
    Note that the return type is Object, rather than V as in the Map interface. See the class Javadoc for further info.
    Specified by:
      `put` in interface `Map<K,V>`
    Specified by:
      `put` in interface `Put<K,V>`
    Overrides:
      `put` in class `AbstractMapDecorator<K,V>`
    Parameters:
      `key` - key with which the specified value is to be associated
      `value` - value to be associated with the specified key
    Returns:
      the previous value associated with `key`, or `null` if there was no mapping for `key`. (A `null` return can also indicate that the map previously associated `null` with `key`, if the implementation supports `null` values.)
    See Also:
      - `Map.put(Object, Object)`

  - ### putAll

    public void putAll(int index, Map<? extends K,? extends V> map)
    Puts the values contained in a supplied Map into the Map starting at the specified index.
    Parameters:
      `index` - the index in the Map to start at.
      `map` - the Map containing the entries to be added.
    Throws:
      `IndexOutOfBoundsException` - if the index is out of range [0, size]

  - ### putAll

    public void putAll(Map<? extends K,? extends V> map)
    Specified by:
      `putAll` in interface `Map<K,V>`
    Specified by:
      `putAll` in interface `Put<K,V>`
    Overrides:
      `putAll` in class `AbstractMapDecorator<K,V>`
    Parameters:
      `map` - mappings to be stored in this map
    See Also:
      - `Map.putAll(Map)`

  - ### remove

    public V remove(int index)
    Removes the element at the specified index.
    Parameters:
      `index` - the index of the object to remove
    Returns:
      the removed value, or `null` if none existed
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### remove

    public V remove(Object key)
    Specified by:
      `remove` in interface `Get<K,V>`
    Specified by:
      `remove` in interface `Map<K,V>`
    Overrides:
      `remove` in class `AbstractMapDecorator<K,V>`
    Parameters:
      `key` - key whose mapping is to be removed from the map
    Returns:
      the previous value associated with `key`, or `null` if there was no mapping for `key`.
    See Also:
      - `Map.remove(Object)`

  - ### setValue

    public V setValue(int index, V value)
    Sets the value at the specified index.
    Parameters:
      `index` - the index of the value to set
      `value` - the new value to set
    Returns:
      the previous value at that index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    Since:
      3.2

  - ### toString

    public String toString()
    Returns the Map as a string.
    Overrides:
      `toString` in class `AbstractMapDecorator<K,V>`
    Returns:
      the Map as a String

  - ### valueList

    public List<V> valueList()
    Gets a view over the values in the map as a List.

    The List will be ordered by object insertion into the map. The List supports remove and set, but does not support add.

    Returns:
      the partially modifiable list view over the values
    Since:
      3.2
    See Also:
      - `values()`

  - ### values

    public Collection<V> values()
    Gets a view over the values in the map.

    The Collection will be ordered by object insertion into the map.

    From Commons Collections 3.2, this Collection can be cast to a list, see `valueList()`

    Specified by:
      `values` in interface `Get<K,V>`
    Specified by:
      `values` in interface `Map<K,V>`
    Overrides:
      `values` in class `AbstractMapDecorator<K,V>`
    Returns:
      the fully modifiable collection view over the values
    See Also:
      - `valueList()`