Top Description Inners Fields Constructors Methods
org.apache.commons.collections4.map

public Class LinkedMap<K, V>

extends AbstractLinkedMap<K, V>
implements Serializable, Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable, java.io.Serializable
Type Parameters
<K>
the type of the keys in this map
<V>
the type of the values in this map
Imports
java.io.IOException, .ObjectInputStream, .ObjectOutputStream, .Serializable, java.util.AbstractList, .Collection, .Iterator, .List, .ListIterator, .Map, java.util.function.Predicate, org.apache.commons.collections4.iterators.UnmodifiableIterator, .UnmodifiableListIterator, org.apache.commons.collections4.list.UnmodifiableList
A Map implementation that maintains the order of the entries. In this implementation order is maintained by original insertion.

This implementation improves on the JDK1.4 LinkedHashMap by adding the MapIterator functionality, additional convenience methods and allowing bidirectional iteration. It also implements OrderedMap. In addition, non-interface methods are provided to access the map by index.

The orderedMapIterator() method provides direct access to a bidirectional iterator. The iterators from the other views can also be cast to OrderedIterator if required.

All the available iterators can be reset back to the start by casting to ResettableIterator and calling reset().

The implementation is also designed to be subclassed, with lots of useful methods exposed.

Note that LinkedMap 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 java.util.Collections#synchronizedMap(Map). This class may throw exceptions when accessed by concurrent threads without synchronization.

Since
3.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
LinkedMap.LinkedMapList<K>

List view of map.

Field Summary

Modifier and TypeField and Description
private static final long
serialVersionUID

Serialisation version

Inherited from org.apache.commons.collections4.map.AbstractLinkedMap:
header

Constructor Summary

AccessConstructor and Description
public
LinkedMap()

Constructs a new empty map with default size and load factor.

public
LinkedMap(final int
the initial capacity
initialCapacity)

Constructs a new, empty map with the specified initial capacity.

public
LinkedMap(final int
the initial capacity
initialCapacity, final float
the load factor
loadFactor)

Constructs a new, empty map with the specified initial capacity and load factor.

public
LinkedMap(final Map<? extends K, ? extends V>
the map to copy
map)

Constructor copying elements from another map.

Method Summary

Modifier and TypeMethod and Description
public List<K>

Returns:

The ordered list of keys.
asList()

Gets an unmodifiable List view of the keys.

public LinkedMap<K, V>

Returns:

a shallow clone
clone()

Overrides org.apache.commons.collections4.map.AbstractHashedMap.clone.

Clones the map without cloning the keys or values.
public K

Returns:

the key at the specified index
get(final int
the index to retrieve
index)

Gets the key at the specified index.

public V

Returns:

the value at the specified index
getValue(final int
the index to retrieve
index)

Gets the value at the specified index.

public int

Returns:

the index, or -1 if not found
indexOf(Object
the key to find the index of
key)

Gets the index of the specified key.

private void
readObject(final ObjectInputStream
the input stream
in)

Read the map in using a custom routine.

public V

Returns:

the previous value corresponding the key, or null if none existed
remove(final int
the index of the object to remove
index)

Removes the element at the specified index.

private void
writeObject(final ObjectOutputStream
the output stream
out)

Write the map out using a custom routine.

Inherited from org.apache.commons.collections4.map.AbstractLinkedMap:
addEntryclearcontainsValuecreateEntrycreateEntrySetIteratorcreateKeySetIteratorcreateValuesIteratorentryAfterentryBeforefirstKeygetEntrygetEntryinitlastKeymapIteratornextKeypreviousKeyremoveEntry

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Serialisation version

Constructor Detail

LinkedMapback to summary
public LinkedMap()

Constructs a new empty map with default size and load factor.

LinkedMapback to summary
public LinkedMap(final int initialCapacity)

Constructs a new, empty map with the specified initial capacity.

Parameters
initialCapacity:int

the initial capacity

Exceptions
IllegalArgumentException:
if the initial capacity is negative
LinkedMapback to summary
public LinkedMap(final int initialCapacity, final float loadFactor)

Constructs a new, empty map with the specified initial capacity and load factor.

Parameters
initialCapacity:int

the initial capacity

loadFactor:float

the load factor

Exceptions
IllegalArgumentException:
  • if the initial capacity is negative
  • if the load factor is less than zero
LinkedMapback to summary
public LinkedMap(final Map<? extends K, ? extends V> map)

Constructor copying elements from another map.

Parameters
map:Map<? extends K, ? extends V>

the map to copy

Exceptions
NullPointerException:
if the map is null

Method Detail

asListback to summary
public List<K> asList()

Gets an unmodifiable List view of the keys.

The returned list is unmodifiable because changes to the values of the list (using java.util.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:List<K>

The ordered list of keys.

See Also
keySet()
cloneback to summary
public LinkedMap<K, V> clone()

Overrides org.apache.commons.collections4.map.AbstractHashedMap.clone.

Clones the map without cloning the keys or values.

Returns:LinkedMap<K, V>

a shallow clone

Annotations
@Override
getback to summary
public K get(final int index)

Gets the key at the specified index.

Parameters
index:int

the index to retrieve

Returns:K

the key at the specified index

Exceptions
IndexOutOfBoundsException:
if the index is invalid
getValueback to summary
public V getValue(final int index)

Gets the value at the specified index.

Parameters
index:int

the index to retrieve

Returns:V

the value at the specified index

Exceptions
IndexOutOfBoundsException:
if the index is invalid
indexOfback to summary
public int indexOf(Object key)

Gets the index of the specified key.

Parameters
key:Object

the key to find the index of

Returns:int

the index, or -1 if not found

readObjectback to summary
private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException

Read the map in using a custom routine.

Parameters
in:ObjectInputStream

the input stream

Exceptions
IOException:
if an error occurs while reading from the stream
ClassNotFoundException:
if an object read from the stream can not be loaded
removeback to summary
public V remove(final int index)

Removes the element at the specified index.

Parameters
index:int

the index of the object to remove

Returns:V

the previous value corresponding the key, or null if none existed

Exceptions
IndexOutOfBoundsException:
if the index is invalid
writeObjectback to summary
private void writeObject(final ObjectOutputStream out) throws IOException

Write the map out using a custom routine.

Parameters
out:ObjectOutputStream

the output stream

Exceptions
IOException:
if an error occurs while writing to the stream
org.apache.commons.collections4.map back to summary

pack-priv Class LinkedMap.LinkedMapList<K>

extends AbstractList<K>
Class Inheritance
List view of map.

Field Summary

Modifier and TypeField and Description
private final LinkedMap<K, ?>
parent

Inherited from java.util.AbstractList:
modCount

Constructor Summary

AccessConstructor and Description
pack-priv
LinkedMapList(final LinkedMap<K, ?> parent)

Method Summary

Modifier and TypeMethod and Description
public void
clear()

Overrides java.util.AbstractList.clear.

Implements java.util.List.clear, java.util.Collection.clear.

Removes all of the elements from this list (optional operation).
public boolean
contains(final Object
element whose presence in this list is to be tested
obj)

Overrides java.util.AbstractCollection.contains.

Implements java.util.List.contains, java.util.Collection.contains.

Returns true if this list contains the specified element.
public boolean
containsAll(final Collection<?>
collection to be checked for containment in this list
coll)

Overrides java.util.AbstractCollection.containsAll.

Implements java.util.List.containsAll, java.util.Collection.containsAll.

Returns true if this list contains all of the elements of the specified collection.
public K
get(final int
index of the element to return
index)

Implements abstract java.util.AbstractList.get.

Implements java.util.List.get.

Returns the element at the specified position in this list.
public int
indexOf(final Object
element to search for
obj)

Overrides java.util.AbstractList.indexOf.

Implements java.util.List.indexOf.

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
public Iterator<K>
iterator()

Overrides java.util.AbstractList.iterator.

Implements java.util.List.iterator, java.util.Collection.iterator.

Returns an iterator over the elements in this list in proper sequence.
public int
lastIndexOf(final Object
element to search for
obj)

Overrides java.util.AbstractList.lastIndexOf.

Implements java.util.List.lastIndexOf.

Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
public ListIterator<K>
listIterator()

Overrides java.util.AbstractList.listIterator.

Implements java.util.List.listIterator.

Returns a list iterator over the elements in this list (in proper sequence).
public ListIterator<K>
listIterator(final int
index of the first element to be returned from the list iterator (by a call to next)
fromIndex)

Overrides java.util.AbstractList.listIterator.

Implements java.util.List.listIterator.

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list.
public K
remove(final int
the index of the element to be removed
index)

Overrides java.util.AbstractList.remove.

Implements java.util.List.remove.

Removes the element at the specified position in this list (optional operation).
public boolean
remove(final Object
element to be removed from this list, if present
obj)

Overrides java.util.AbstractCollection.remove.

Implements java.util.List.remove, java.util.Collection.remove.

Removes the first occurrence of the specified element from this list, if it is present (optional operation).
public boolean
removeAll(final Collection<?>
collection containing elements to be removed from this list
coll)

Overrides java.util.AbstractCollection.removeAll.

Implements java.util.List.removeAll, java.util.Collection.removeAll.

Removes from this list all of its elements that are contained in the specified collection (optional operation).
public boolean
removeIf(final Predicate<? super K>
a predicate which returns true for elements to be removed
filter)

Overrides default java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate.
public boolean
retainAll(final Collection<?>
collection containing elements to be retained in this list
coll)

Overrides java.util.AbstractCollection.retainAll.

Implements java.util.List.retainAll, java.util.Collection.retainAll.

Retains only the elements in this list that are contained in the specified collection (optional operation).
public int
size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.List.size, java.util.Collection.size.

Returns the number of elements in this list.
public List<K>
subList(final int
low endpoint (inclusive) of the subList
fromIndexInclusive, final int
high endpoint (exclusive) of the subList
toIndexExclusive)

Overrides java.util.AbstractList.subList.

Implements java.util.List.subList.

Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive.
public Object[]
toArray()

Overrides java.util.AbstractCollection.toArray.

Implements java.util.List.toArray, java.util.Collection.toArray.

Returns an array containing all of the elements in this list in proper sequence (from first to last element).
public <T> T[]
toArray(final T[]
the array into which the elements of this list are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
array)

Overrides java.util.AbstractCollection.toArray.

Implements java.util.List.toArray, java.util.Collection.toArray.

Returns an array containing all of the elements in this list in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array.
Inherited from java.util.AbstractList:
addaddaddAllequalshashCoderemoveRangeset

Field Detail

parentback to summary
private final LinkedMap<K, ?> parent

Constructor Detail

LinkedMapListback to summary
pack-priv LinkedMapList(final LinkedMap<K, ?> parent)

Method Detail

clearback to summary
public void clear()

Overrides java.util.AbstractList.clear.

Implements java.util.List.clear, java.util.Collection.clear.

Doc from java.util.AbstractList.clear.

Removes all of the elements from this list (optional operation). The list will be empty after this call returns.

Annotations
@Override
containsback to summary
public boolean contains(final Object obj)

Overrides java.util.AbstractCollection.contains.

Implements java.util.List.contains, java.util.Collection.contains.

Doc from java.util.List.contains.

Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that Objects.equals(o, e).

Parameters
obj:Object

element whose presence in this list is to be tested

Returns:boolean

true if this list contains the specified element

Annotations
@Override
containsAllback to summary
public boolean containsAll(final Collection<?> coll)

Overrides java.util.AbstractCollection.containsAll.

Implements java.util.List.containsAll, java.util.Collection.containsAll.

Doc from java.util.List.containsAll.

Returns true if this list contains all of the elements of the specified collection.

Parameters
coll:Collection<?>

collection to be checked for containment in this list

Returns:boolean

true if this list contains all of the elements of the specified collection

Annotations
@Override
getback to summary
public K get(final int index)

Implements abstract java.util.AbstractList.get.

Implements java.util.List.get.

Doc from java.util.AbstractList.get.

Returns the element at the specified position in this list.

Parameters
index:int

Doc from java.util.List.get.

index of the element to return

Returns:K

Doc from java.util.List.get.

the element at the specified position in this list

Annotations
@Override
indexOfback to summary
public int indexOf(final Object obj)

Overrides java.util.AbstractList.indexOf.

Implements java.util.List.indexOf.

Doc from java.util.AbstractList.indexOf.

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the lowest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.

Parameters
obj:Object

Doc from java.util.List.indexOf.

element to search for

Returns:int

Doc from java.util.List.indexOf.

the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element

Annotations
@Override
iteratorback to summary
public Iterator<K> iterator()

Overrides java.util.AbstractList.iterator.

Implements java.util.List.iterator, java.util.Collection.iterator.

Doc from java.util.AbstractList.iterator.

Returns an iterator over the elements in this list in proper sequence.

Returns:Iterator<K>

an iterator over the elements in this list in proper sequence

Annotations
@Override
lastIndexOfback to summary
public int lastIndexOf(final Object obj)

Overrides java.util.AbstractList.lastIndexOf.

Implements java.util.List.lastIndexOf.

Doc from java.util.AbstractList.lastIndexOf.

Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the highest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.

Parameters
obj:Object

Doc from java.util.List.lastIndexOf.

element to search for

Returns:int

Doc from java.util.List.lastIndexOf.

the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element

Annotations
@Override
listIteratorback to summary
public ListIterator<K> listIterator()

Overrides java.util.AbstractList.listIterator.

Implements java.util.List.listIterator.

Doc from java.util.AbstractList.listIterator.

Returns a list iterator over the elements in this list (in proper sequence).

Returns:ListIterator<K>

Doc from java.util.List.listIterator.

a list iterator over the elements in this list (in proper sequence)

Annotations
@Override
listIteratorback to summary
public ListIterator<K> listIterator(final int fromIndex)

Overrides java.util.AbstractList.listIterator.

Implements java.util.List.listIterator.

Doc from java.util.AbstractList.listIterator.

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list. The specified index indicates the first element that would be returned by an initial call to next. An initial call to previous would return the element with the specified index minus one.

Parameters
fromIndex:int

Doc from java.util.List.listIterator.

index of the first element to be returned from the list iterator (by a call to next)

Returns:ListIterator<K>

Doc from java.util.List.listIterator.

a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list

Annotations
@Override
removeback to summary
public K remove(final int index)

Overrides java.util.AbstractList.remove.

Implements java.util.List.remove.

Doc from java.util.AbstractList.remove.

Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

Parameters
index:int

Doc from java.util.List.remove.

the index of the element to be removed

Returns:K

Doc from java.util.List.remove.

the element previously at the specified position

Annotations
@Override
removeback to summary
public boolean remove(final Object obj)

Overrides java.util.AbstractCollection.remove.

Implements java.util.List.remove, java.util.Collection.remove.

Doc from java.util.List.remove.

Removes the first occurrence of the specified element from this list, if it is present (optional operation). If this list does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that Objects.equals(o, get(i)) (if such an element exists). Returns true if this list contained the specified element (or equivalently, if this list changed as a result of the call).

Parameters
obj:Object

element to be removed from this list, if present

Returns:boolean

true if this list contained the specified element

Annotations
@Override
removeAllback to summary
public boolean removeAll(final Collection<?> coll)

Overrides java.util.AbstractCollection.removeAll.

Implements java.util.List.removeAll, java.util.Collection.removeAll.

Doc from java.util.List.removeAll.

Removes from this list all of its elements that are contained in the specified collection (optional operation).

Parameters
coll:Collection<?>

collection containing elements to be removed from this list

Returns:boolean

true if this list changed as a result of the call

Annotations
@Override
removeIfback to summary
public boolean removeIf(final Predicate<? super K> filter)

Overrides default java.util.Collection.removeIf.

Doc from java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate. Errors or runtime exceptions thrown during iteration or by the predicate are relayed to the caller.

Parameters
filter:Predicate<? super K>

a predicate which returns true for elements to be removed

Returns:boolean

true if any elements were removed

Annotations
@Override
Since
4.4
retainAllback to summary
public boolean retainAll(final Collection<?> coll)

Overrides java.util.AbstractCollection.retainAll.

Implements java.util.List.retainAll, java.util.Collection.retainAll.

Doc from java.util.List.retainAll.

Retains only the elements in this list that are contained in the specified collection (optional operation). In other words, removes from this list all of its elements that are not contained in the specified collection.

Parameters
coll:Collection<?>

collection containing elements to be retained in this list

Returns:boolean

true if this list changed as a result of the call

Annotations
@Override
sizeback to summary
public int size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.List.size, java.util.Collection.size.

Doc from java.util.List.size.

Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:int

the number of elements in this list

Annotations
@Override
subListback to summary
public List<K> subList(final int fromIndexInclusive, final int toIndexExclusive)

Overrides java.util.AbstractList.subList.

Implements java.util.List.subList.

Doc from java.util.AbstractList.subList.

Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive. (If fromIndex and toIndex are equal, the returned list is empty.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list.

This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a list can be used as a range operation by passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list: 

list.subList(from, to).clear();
Similar idioms may be constructed for indexOf and lastIndexOf, and all of the algorithms in the Collections class can be applied to a subList.

The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.)

Parameters
fromIndexInclusive:int

Doc from java.util.List.subList.

low endpoint (inclusive) of the subList

toIndexExclusive:int

Doc from java.util.List.subList.

high endpoint (exclusive) of the subList

Returns:List<K>

Doc from java.util.List.subList.

a view of the specified range within this list

Annotations
@Override
toArrayback to summary
public Object[] toArray()

Overrides java.util.AbstractCollection.toArray.

Implements java.util.List.toArray, java.util.Collection.toArray.

Doc from java.util.List.toArray.

Returns an array containing all of the elements in this list in proper sequence (from first to last element).

The returned array will be "safe" in that no references to it are maintained by this list. (In other words, this method must allocate a new array even if this list is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Returns:Object[]

an array containing all of the elements in this list in proper sequence

Annotations
@Override
toArrayback to summary
public <T> T[] toArray(final T[] array)

Overrides java.util.AbstractCollection.toArray.

Implements java.util.List.toArray, java.util.Collection.toArray.

Doc from java.util.List.toArray.

Returns an array containing all of the elements in this list in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array. If the list fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this list.

If the list fits in the specified array with room to spare (i.e., the array has more elements than the list), the element in the array immediately following the end of the list is set to null. (This is useful in determining the length of the list only if the caller knows that the list does not contain any null elements.)

Like the toArray() method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs.

Suppose x is a list known to contain only strings. The following code can be used to dump the list into a newly allocated array of String: 

String[] y = x.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in function to toArray().
Parameters
<T>

Doc from java.util.Collection.toArray. the component type of the array to contain the collection

array:T[]

the array into which the elements of this list are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:T[]

an array containing the elements of this list

Annotations
@Override