public class

ListOrderedMap

extends AbstractMapDecorator
implements Serializable OrderedMap
java.lang.Object
   ↳ org.apache.commons.collections.map.AbstractMapDecorator
     ↳ org.apache.commons.collections.map.ListOrderedMap

Class Overview

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

This class is Serializable from Commons Collections 3.1.

Summary

Fields
protected final List insertOrder Internal list to hold the sequence of objects
[Expand]
Inherited Fields
From class org.apache.commons.collections.map.AbstractMapDecorator
Public Constructors
ListOrderedMap()
Constructs a new empty ListOrderedMap that decorates a HashMap.
Protected Constructors
ListOrderedMap(Map map)
Constructor that wraps (not copies).
Public Methods
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.
[Expand]
Inherited Methods
From class org.apache.commons.collections.map.AbstractMapDecorator
From class java.lang.Object
From interface java.util.Map
From interface org.apache.commons.collections.IterableMap
From interface org.apache.commons.collections.OrderedMap

Fields

protected final List insertOrder

Internal list to hold the sequence of objects

Public Constructors

public ListOrderedMap ()

Constructs a new empty ListOrderedMap that decorates a HashMap.

Protected Constructors

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

Public Methods

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

public void clear ()

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

public Set entrySet ()

Gets a view over the entries in the map.

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

Returns
  • the fully modifiable set view over the entries

public Object firstKey ()

Gets the first key in this map by insert order.

Returns
  • the first key currently in this map
Throws
NoSuchElementException if this map is empty

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

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

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

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
See Also

public Set keySet ()

Gets a view over the keys in the map.

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

Returns
  • the fully modifiable collection view over the keys
See Also

public Object lastKey ()

Gets the last key in this map by insert order.

Returns
  • the last key currently in this map
Throws
NoSuchElementException if this map is empty

public MapIterator mapIterator ()

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");
 }

Returns
  • a map iterator

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

Parameters
key the key to find previous for
Returns
  • the next key, null if no match or at start

public OrderedMapIterator orderedMapIterator ()

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

Returns
  • a map iterator

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

Parameters
key the key to find previous for
Returns
  • the previous key, null if no match or at start

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

public Object put (Object key, Object value)

public void putAll (Map map)

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

public Object remove (Object key)

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

public String toString ()

Returns the Map as a string.

Returns
  • the Map as a String

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
See Also

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

Returns
  • the fully modifiable collection view over the values
See Also