org.apache.commons.collections4.map

Class ListOrderedMap<K,V>

java.lang.Object

org.apache.commons.collections4.map.AbstractIterableMap<K,V>

org.apache.commons.collections4.map.AbstractMapDecorator<K,V>

org.apache.commons.collections4.map.ListOrderedMap<K,V>

Type Parameters:

K - the type of the keys in this map

V - the type of the values in this map

All Implemented Interfaces:

java.io.Serializable, java.util.Map<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, OrderedMap<K,V>, Put<K,V>

public class ListOrderedMap<K,V>
extends AbstractMapDecorator<K,V>
implements OrderedMap<K,V>, 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.

Note that ListOrderedMap doesn't work with IdentityHashMap, CaseInsensitiveMap, or similar maps that violate the general contract of Map. The ListOrderedMap (or, more precisely, the underlying List) is relying on equals(). This is fine, as long as the decorated Map is also based on equals(), and hashCode(), which IdentityHashMap, and CaseInsensitiveMap don't: The former uses ==, and the latter uses equals() on a lower-cased key.

This class is Serializable starting with Commons Collections 3.1.

Since:

3.0

See Also:

Serialized Form

Nested Class Summary

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

java.util.Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
ListOrderedMap() Constructs a new empty ListOrderedMap that decorates a HashMap.

Method Summary

Modifier and Type	Method and Description
java.util.List<K>	asList() Gets an unmodifiable List view of the keys which changes as the map changes.
void	clear()
java.util.Set<java.util.Map.Entry<K,V>>	entrySet() Gets a view over the entries in the map.
K	firstKey() Gets the first key in this map by insert order.
K	get(int index) Gets the key at the specified index.
V	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<K>	keyList() Gets a view over the keys in the map as a List.
java.util.Set<K>	keySet() Gets a view over the keys in the map.
K	lastKey() Gets the last key in this map by insert order.
static <K,V> ListOrderedMap<K,V>	listOrderedMap(java.util.Map<K,V> map) Factory method to create an ordered map.
OrderedMapIterator<K,V>	mapIterator() Obtains a MapIterator over the map.
K	nextKey(java.lang.Object key) Gets the next key to the one specified using insert order.
K	previousKey(java.lang.Object key) Gets the previous key to the one specified using insert order.
V	put(int index, K key, V value) Puts a key-value mapping into the map at the specified index.
V	put(K key, V value) Note that the return type is Object, rather than V as in the Map interface.
void	putAll(int index, java.util.Map<? extends K,? extends V> map) Puts the values contained in a supplied Map into the Map starting at the specified index.
void	putAll(java.util.Map<? extends K,? extends V> map)
V	remove(int index) Removes the element at the specified index.
V	remove(java.lang.Object key)
V	setValue(int index, V value) Sets the value at the specified index.
java.lang.String	toString() Returns the Map as a string.
java.util.List<V>	valueList() Gets a view over the values in the map as a List.
java.util.Collection<V>	values() Gets a view over the values in the map.

Methods inherited from class org.apache.commons.collections4.map.AbstractMapDecorator

containsKey, containsValue, equals, get, hashCode, isEmpty, size

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size

Methods inherited from interface org.apache.commons.collections4.Get

containsKey, containsValue, get, isEmpty, size

Constructor Detail

ListOrderedMap

public ListOrderedMap()

Constructs a new empty ListOrderedMap that decorates a HashMap.

Since:

3.1

Method Detail

listOrderedMap

public static <K,V> ListOrderedMap<K,V> listOrderedMap(java.util.Map<K,V> map)

Factory method to create an ordered map.

An ArrayList is used to retain order.

Type Parameters:

K - the key type

V - the value type

Parameters:

map - the map to decorate, must not be null

Returns:

a new list ordered map

Throws:

java.lang.NullPointerException - if map is null

Since:

4.0

mapIterator

public OrderedMapIterator<K,V> mapIterator()

Description copied from class: AbstractIterableMap

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 use Map Entry objects.

 IterableMap<String,Integer> map = new HashedMap<String,Integer>();
 MapIterator<String,Integer> it = map.mapIterator();
 while (it.hasNext()) {
   String key = it.next();
   Integer value = it.getValue();
   it.setValue(value + 1);
 }
 

Specified by:

mapIterator in interface IterableGet<K,V>

Specified by:

mapIterator in interface OrderedMap<K,V>

Overrides:

mapIterator in class AbstractIterableMap<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:

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

java.util.NoSuchElementException - if this map is empty

nextKey

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

Description copied from interface: Put

Note that the return type is Object, rather than V as in the Map interface. See the class Javadoc for further info.

Specified by:

put in interface java.util.Map<K,V>

Specified by:

put in interface Put<K,V>

Overrides:

put in class AbstractMapDecorator<K,V>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key, if the implementation supports null values.)

See Also:

Map.put(Object, Object)

putAll

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

Specified by:

putAll in interface java.util.Map<K,V>

Specified by:

putAll in interface Put<K,V>

Overrides:

putAll in class AbstractMapDecorator<K,V>

Parameters:

map - mappings to be stored in this map

See Also:

Map.putAll(Map)

putAll

public void putAll(int index,
                   java.util.Map<? extends K,? extends V> map)

Puts the values contained in a supplied Map into the Map starting at the specified index.

Parameters:

index - the index in the Map to start at.

map - the Map containing the entries to be added.

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range [0, size]

remove

public V remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map<K,V>

Specified by:

remove in interface Get<K,V>

Overrides:

remove in class AbstractMapDecorator<K,V>

Parameters:

key - key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or null if there was no mapping for key.

See Also:

Map.remove(Object)

clear

public void clear()

Specified by:

clear in interface java.util.Map<K,V>

Specified by:

clear in interface Put<K,V>

Overrides:

clear in class AbstractMapDecorator<K,V>

See Also:

Map.clear()

keySet

public java.util.Set<K> 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<K,V>

Specified by:

keySet in interface Get<K,V>

Overrides:

keySet in class AbstractMapDecorator<K,V>

Returns:

the fully modifiable collection view over the keys

See Also:

keyList()

keyList

public java.util.List<K> 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:

3.2

See Also:

keySet()

values

public java.util.Collection<V> 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<K,V>

Specified by:

values in interface Get<K,V>

Overrides:

values in class AbstractMapDecorator<K,V>

Returns:

the fully modifiable collection view over the values

See Also:

valueList()

valueList

public java.util.List<V> 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:

3.2

See Also:

values()

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> 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<K,V>

Specified by:

entrySet in interface Get<K,V>

Overrides:

entrySet in class AbstractMapDecorator<K,V>

Returns:

the fully modifiable set view over the entries

See Also:

Map.entrySet()

toString

public java.lang.String toString()

Returns the Map as a string.

Overrides:

toString in class AbstractMapDecorator<K,V>

Returns:

the Map as a String

get

public K 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 V 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 V setValue(int index,
                  V value)

Sets the value at the specified index.

Parameters:

index - the index of the value to set

value - the new value to set

Returns:

the previous value at that index

Throws:

java.lang.IndexOutOfBoundsException - if the index is invalid

Since:

3.2

put

public V put(int index,
             K key,
             V 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 occurred.

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 [0, size]

Since:

3.2

remove

public V 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<K> 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()