## 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:
  IterableMap, Map, OrderedMap, Serializable

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.

This class is Serializable from Commons Collections 3.1.

Since:
  Commons Collections 3.0
Version:
  $Revision: 1.16 $ $Date: 2004/06/07 21:51:39 $
Author:
  Henri Yandell, Stephen Colebourne
See Also:
  Serialized Form

Nested Class Summary

Nested classes inherited from class java.util.Map
`Map.Entry`

Field Summary
`protected List` `insertOrder` Internal list to hold the sequence of objects

Fields inherited from class org.apache.commons.collections.map.AbstractMapDecorator
`map`

Constructor Summary
`` `ListOrderedMap()` Constructs a new empty `ListOrderedMap` that decorates a `HashMap`.
`protected` `ListOrderedMap(Map map)` Constructor that wraps (not copies).

Method Summary
`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()`
`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.
`Set` `keySet()`
`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(Object key, Object value)`
`void` `putAll(Map map)`
`Object` `remove(int index)` Removes the element at the specified index.
`Object` `remove(Object key)`
`String` `toString()` Returns the Map as a string.
`Collection` `values()`

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()

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

### values

    public Collection values()

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

### entrySet

    public Set entrySet()

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

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

### remove

    public Object remove(int index)

  Removes the element at the specified index.

  Parameters:
    `index` - the index of the object to remove
  Returns:
    the previous value corresponding the `key`, 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 `keySet()`.

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

Copyright © 2001-2005 Apache Software Foundation. All Rights Reserved.