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:

java.io.Serializable, java.util.Map, IterableMap, OrderedMap

public class ListOrderedMap
extends AbstractMapDecorator
implements OrderedMap, java.io.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 13:33:15 +0100 (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

java.util.Map.Entry

Field Summary

protected java.util.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(java.util.Map map) Constructor that wraps (not copies).

Method Summary

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

Constructor that wraps (not copies).

Parameters:

map - the map to decorate, must not be null

Throws:

java.lang.IllegalArgumentException - if map is null

Method Detail

decorate

public static OrderedMap decorate(java.util.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:

java.lang.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 java.lang.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:

java.util.NoSuchElementException - if this map is empty

lastKey

public java.lang.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:

java.util.NoSuchElementException - if this map is empty

nextKey

public java.lang.Object nextKey(java.lang.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 java.lang.Object previousKey(java.lang.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 java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Specified by:

put in interface java.util.Map

Overrides:

put in class AbstractMapDecorator

putAll

public void putAll(java.util.Map map)

Specified by:

putAll in interface java.util.Map

Overrides:

putAll in class AbstractMapDecorator

remove

public java.lang.Object remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map

Overrides:

remove in class AbstractMapDecorator

clear

public void clear()

Specified by:

clear in interface java.util.Map

Overrides:

clear in class AbstractMapDecorator

keySet

public java.util.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 java.util.Map

Overrides:

keySet in class AbstractMapDecorator

Returns:

the fully modifiable collection view over the keys

See Also:

keyList()

keyList

public java.util.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 java.util.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 java.util.Map

Overrides:

values in class AbstractMapDecorator

Returns:

the fully modifiable collection view over the values

See Also:

valueList()

valueList

public java.util.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 java.util.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 java.util.Map

Overrides:

entrySet in class AbstractMapDecorator

Returns:

the fully modifiable set view over the entries

toString

public java.lang.String toString()

Returns the Map as a string.

Overrides:

toString in class AbstractMapDecorator

Returns:

the Map as a String

get

public java.lang.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:

java.lang.IndexOutOfBoundsException - if the index is invalid

getValue

public java.lang.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:

java.lang.IndexOutOfBoundsException - if the index is invalid

indexOf

public int indexOf(java.lang.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 java.lang.Object setValue(int index,
                                 java.lang.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:

java.lang.IndexOutOfBoundsException - if the index is invalid

Since:

Commons Collections 3.2

put

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

java.lang.IndexOutOfBoundsException - if the index is out of range

Since:

Commons Collections 3.2

remove

public java.lang.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:

java.lang.IndexOutOfBoundsException - if the index is invalid

asList

public java.util.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()