org.apache.commons.collections.map

## Class ListOrderedMap

- java.lang.Object
- - org.apache.commons.collections.map.AbstractMapDecorator
  - - org.apache.commons.collections.map.ListOrderedMap

- All Implemented Interfaces:
    Serializable, Map, IterableMap, OrderedMap

      public class ListOrderedMap
      extends AbstractMapDecorator
      implements OrderedMap, 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.

  This class is Serializable from Commons Collections 3.1.

  Since:
    Commons Collections 3.0
  Version:
    $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
  Author:
    Henri Yandell, Stephen Colebourne, Matt Benson
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `Map.Entry`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected List` | `insertOrder` Internal list to hold the sequence of objects

    - ### Fields inherited from class org.apache.commons.collections.map.AbstractMapDecorator

      `map`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `ListOrderedMap()` Constructs a new empty `ListOrderedMap` that decorates a `HashMap`.
    `protected` | `ListOrderedMap(Map map)` Constructor that wraps (not copies).

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `List` | `asList()` Gets an unmodifiable List view of the keys which changes as the map changes.
    `void` | `clear()`
    `static OrderedMap` | `decorate(Map map)` Factory method to create an ordered map.
    `Set` | `entrySet()` Gets a view over the entries in the map.
    `Object` | `firstKey()` Gets the first key in this map by insert order.
    `Object` | `get(int index)` Gets the key at the specified index.
    `Object` | `getValue(int index)` Gets the value at the specified index.
    `int` | `indexOf(Object key)` Gets the index of the specified key.
    `List` | `keyList()` Gets a view over the keys in the map as a List.
    `Set` | `keySet()` Gets a view over the keys in the map.
    `Object` | `lastKey()` Gets the last key in this map by insert order.
    `MapIterator` | `mapIterator()` Obtains a `MapIterator` over the map.
    `Object` | `nextKey(Object key)` Gets the next key to the one specified using insert order.
    `OrderedMapIterator` | `orderedMapIterator()` Obtains an `OrderedMapIterator` over the map.
    `Object` | `previousKey(Object key)` Gets the previous key to the one specified using insert order.
    `Object` | `put(int index, Object key, Object value)` Puts a key-value mapping into the map at the specified index.
    `Object` | `put(Object key, Object value)`
    `void` | `putAll(Map map)`
    `Object` | `remove(int index)` Removes the element at the specified index.
    `Object` | `remove(Object key)`
    `Object` | `setValue(int index, Object value)` Sets the value at the specified index.
    `String` | `toString()` Returns the Map as a string.
    `List` | `valueList()` Gets a view over the values in the map as a List.
    `Collection` | `values()` Gets a view over the values in the map.

    - ### Methods inherited from class org.apache.commons.collections.map.AbstractMapDecorator

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

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

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

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

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

- - ### Field Detail

    - #### insertOrder

          protected final List insertOrder

      Internal list to hold the sequence of objects

  - ### Constructor Detail

    - #### ListOrderedMap

          public ListOrderedMap()

      Constructs a new empty `ListOrderedMap` that decorates a `HashMap`.
      Since:
        Commons Collections 3.1

    - #### ListOrderedMap

          protected ListOrderedMap(Map map)

      Constructor that wraps (not copies).
      Parameters:
        `map` - the map to decorate, must not be null
      Throws:
        `IllegalArgumentException` - if map is null

  - ### Method Detail

    - #### decorate

          public static OrderedMap decorate(Map map)

      Factory method to create an ordered map.

      An `ArrayList` is used to retain order.

      Parameters:
        `map` - the map to decorate, must not be null
      Throws:
        `IllegalArgumentException` - if map is null

    - #### mapIterator

          public MapIterator mapIterator()

      Description copied from interface: `IterableMap`
      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 cast to Map Entry objects.

           IterableMap map = new HashedMap();
           MapIterator it = map.mapIterator();
           while (it.hasNext()) {
             Object key = it.next();
             Object value = it.getValue();
             it.setValue("newValue");
           }

      Specified by:
        `mapIterator` in interface `IterableMap`
      Returns:
        a map iterator

    - #### orderedMapIterator

          public OrderedMapIterator orderedMapIterator()

      Description copied from interface: `OrderedMap`
      Obtains an `OrderedMapIterator` over the map.

      A ordered map iterator is an efficient way of iterating over maps in both directions.

           BidiMap map = new TreeBidiMap();
           MapIterator it = map.mapIterator();
           while (it.hasNext()) {
             Object key = it.next();
             Object value = it.getValue();
             it.setValue("newValue");
             Object previousKey = it.previous();
           }

      Specified by:
        `orderedMapIterator` in interface `OrderedMap`
      Returns:
        a map iterator

    - #### firstKey

          public Object firstKey()

      Gets the first key in this map by insert order.
      Specified by:
        `firstKey` in interface `OrderedMap`
      Returns:
        the first key currently in this map
      Throws:
        `NoSuchElementException` - if this map is empty

    - #### lastKey

          public Object lastKey()

      Gets the last key in this map by insert order.
      Specified by:
        `lastKey` in interface `OrderedMap`
      Returns:
        the last key currently in this map
      Throws:
        `NoSuchElementException` - if this map is empty

    - #### nextKey

          public Object 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`
      Parameters:
        `key` - the key to find previous for
      Returns:
        the next key, null if no match or at start

    - #### previousKey

          public Object 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`
      Parameters:
        `key` - the key to find previous for
      Returns:
        the previous key, null if no match or at start

    - #### put

          public Object put(Object key,
                   Object value)

      Specified by:
        `put` in interface `Map`
      Overrides:
        `put` in class `AbstractMapDecorator`

    - #### putAll

          public void putAll(Map map)

      Specified by:
        `putAll` in interface `Map`
      Overrides:
        `putAll` in class `AbstractMapDecorator`

    - #### remove

          public Object remove(Object key)

      Specified by:
        `remove` in interface `Map`
      Overrides:
        `remove` in class `AbstractMapDecorator`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `Map`
      Overrides:
        `clear` in class `AbstractMapDecorator`

    - #### keySet

          public Set 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 `Map`
      Overrides:
        `keySet` in class `AbstractMapDecorator`
      Returns:
        the fully modifiable collection view over the keys
      See Also:
        `keyList()`

    - #### keyList

          public List 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:
        Commons Collections 3.2
      See Also:
        `keySet()`

    - #### values

          public Collection 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 `Map`
      Overrides:
        `values` in class `AbstractMapDecorator`
      Returns:
        the fully modifiable collection view over the values
      See Also:
        `valueList()`

    - #### valueList

          public List 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:
        Commons Collections 3.2
      See Also:
        `values()`

    - #### entrySet

          public Set 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 `Map`
      Overrides:
        `entrySet` in class `AbstractMapDecorator`
      Returns:
        the fully modifiable set view over the entries

    - #### toString

          public String toString()

      Returns the Map as a string.
      Overrides:
        `toString` in class `AbstractMapDecorator`
      Returns:
        the Map as a String

    - #### get

          public Object 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 Object 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

    - #### setValue

          public Object setValue(int index,
                        Object value)

      Sets the value at the specified index.
      Parameters:
        `index` - the index of the value to set
      Returns:
        the previous value at that index
      Throws:
        `IndexOutOfBoundsException` - if the index is invalid
      Since:
        Commons Collections 3.2

    - #### put

          public Object put(int index,
                   Object key,
                   Object 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 ocurred.

      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
      Since:
        Commons Collections 3.2

    - #### remove

          public Object 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

    - #### asList

          public List 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()`

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