org.apache.commons.collections.map
Class ListOrderedMap<K,V>

java.lang.Object
  org.apache.commons.collections.map.AbstractMapDecorator<K,V>
      org.apache.commons.collections.map.ListOrderedMap<K,V>

All Implemented Interfaces:

Serializable, Map<K,V>, IterableMap<K,V>, OrderedMap<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.

This class is Serializable from Commons Collections 3.1.

Since:

Commons Collections 3.0

Version:

$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:35:56 $

Author:

Henri Yandell, Matt Hall, John Watkinson, Stephen Colebourne

See Also:

Serialized Form

Nested Class Summary

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

Map.Entry<K,V>

Field Summary

protected List<K>

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<K,V> 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 <K,V> OrderedMap<K,V>	decorate(Map<K,V> map) Factory method to create an ordered map.
Set	entrySet()
K	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<K>	keySet()
K	lastKey() Gets the last key in this map by insert order.
MapIterator<K,V>	mapIterator() Obtains a MapIterator over the map.
K	nextKey(K key) Gets the next key to the one specified using insert order.
OrderedMapIterator<K,V>	orderedMapIterator() Obtains an OrderedMapIterator over the map.
K	previousKey(K key) Gets the previous key to the one specified using insert order.
V	put(K key, V value)
void	putAll(Map<? extends K,? extends V> map)
Object	remove(int index) Removes the element at the specified index.
V	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<K> 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<K,V> 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 <K,V> OrderedMap<K,V> decorate(Map<K,V> 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<K,V> 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<K,V>

Returns:

a map iterator

orderedMapIterator

public OrderedMapIterator<K,V> 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<K,V>

Returns:

a map iterator

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

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

nextKey

public K nextKey(K 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(K 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(K key,
             V value)

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMapDecorator<K,V>

putAll

public void putAll(Map<? extends K,? extends V> map)

Specified by:

putAll in interface Map<K,V>

Overrides:

putAll in class AbstractMapDecorator<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

Overrides:

remove in class AbstractMapDecorator<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractMapDecorator<K,V>

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

Overrides:

keySet in class AbstractMapDecorator<K,V>

values

public Collection values()

Specified by:

values in interface Map<K,V>

Overrides:

values in class AbstractMapDecorator<K,V>

entrySet

public Set entrySet()

Specified by:

entrySet in interface Map<K,V>

Overrides:

entrySet in class AbstractMapDecorator<K,V>

toString

public String toString()

Returns the Map as a string.

Overrides:

toString in class AbstractMapDecorator<K,V>

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