org.apache.commons.collections.map
Class ListOrderedMap

java.lang.Object
  extended by org.apache.commons.collections.map.AbstractMapDecorator
      extended by 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.

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/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()
           
 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.Set keySet()
           
 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(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.String toString()
          Returns the Map as a string.
 java.util.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 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()
Specified by:
keySet in interface java.util.Map
Overrides:
keySet in class AbstractMapDecorator

values

public java.util.Collection values()
Specified by:
values in interface java.util.Map
Overrides:
values in class AbstractMapDecorator

entrySet

public java.util.Set entrySet()
Specified by:
entrySet in interface java.util.Map
Overrides:
entrySet in class AbstractMapDecorator

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

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 previous value corresponding the key, 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 keySet().

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


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