org.jboss.util.collection

Interface NavigableMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Superinterfaces:

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

All Known Subinterfaces:

ConcurrentNavigableMap<K,V>

All Known Implementing Classes:

ConcurrentSkipListMap, ConcurrentSkipListMap.ConcurrentSkipListSubMap

public interface NavigableMap<K,V>
extends java.util.SortedMap<K,V>

A SortedMap extended with navigation methods returning the closest matches for given search targets. Methods lowerEntry, floorEntry, ceilingEntry, and higherEntry return Map.Entry objects associated with keys respectively less than, less than or equal, greater than or equal, and greater than a given key, returning null if there is no such key. Similarly, methods lowerKey, floorKey, ceilingKey, and higherKey return only the associated keys. All of these methods are designed for locating, not traversing entries.

A NavigableMap may be viewed and traversed in either ascending or descending key order. The Map methods keySet and entrySet return ascending views, and the additional methods descendingKeySet and descendingEntrySet return descending views. The performance of ascending traversals is likely to be faster than descending traversals. Notice that it is possible to perform subrannge traversals in either direction using SubMap.

This interface additionally defines methods firstEntry, pollFirstEntry, lastEntry, and pollLastEntry that return and/or remove the least and greatest mappings, if any exist, else returning null.

Implementations of entry-returning methods are expected to return Map.Entry pairs representing snapshots of mappings at the time they were produced, and thus generally do not support the optional Entry.setValue method. Note however that it is possible to change mappings in the associated map using method put.

Nested Class Summary

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

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

Method Summary

Modifier and Type	Method and Description
java.util.Map.Entry<K,V>	ceilingEntry(K key) Returns a key-value mapping associated with the least key greater than or equal to the given key, or null if there is no such entry.
K	ceilingKey(K key) Returns least key greater than or equal to the given key, or null if there is no such key.
java.util.Set<java.util.Map.Entry<K,V>>	descendingEntrySet() Returns a set view of the mappings contained in this map, in descending key order.
java.util.Set<K>	descendingKeySet() Returns a set view of the keys contained in this map, in descending key order.
java.util.Map.Entry<K,V>	firstEntry() Returns a key-value mapping associated with the least key in this map, or null if the map is empty.
java.util.Map.Entry<K,V>	floorEntry(K key) Returns a key-value mapping associated with the greatest key less than or equal to the given key, or null if there is no such entry.
K	floorKey(K key) Returns the greatest key less than or equal to the given key, or null if there is no such key.
NavigableMap<K,V>	headMap(K toKey) Returns a view of the portion of this map whose keys are strictly less than toKey.
java.util.Map.Entry<K,V>	higherEntry(K key) Returns a key-value mapping associated with the least key strictly greater than the given key, or null if there is no such entry.
K	higherKey(K key) Returns the least key strictly greater than the given key, or null if there is no such key.
java.util.Map.Entry<K,V>	lastEntry() Returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.
java.util.Map.Entry<K,V>	lowerEntry(K key) Returns a key-value mapping associated with the greatest key strictly less than the given key, or null if there is no such entry.
K	lowerKey(K key) Returns the greatest key strictly less than the given key, or null if there is no such key.
java.util.Map.Entry<K,V>	pollFirstEntry() Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.
java.util.Map.Entry<K,V>	pollLastEntry() Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.
NavigableMap<K,V>	subMap(K fromKey, K toKey) Returns a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive.
NavigableMap<K,V>	tailMap(K fromKey) Returns a view of the portion of this map whose keys are greater than or equal to fromKey.

Methods inherited from interface java.util.SortedMap

comparator, entrySet, firstKey, keySet, lastKey, values

Methods inherited from interface java.util.Map

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

Method Detail

ceilingEntry

java.util.Map.Entry<K,V> ceilingEntry(K key)

Returns a key-value mapping associated with the least key greater than or equal to the given key, or null if there is no such entry.

Parameters:

key - the key.

Returns:

an Entry associated with ceiling of given key, or null if there is no such Entry.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

ceilingKey

K ceilingKey(K key)

Returns least key greater than or equal to the given key, or null if there is no such key.

Parameters:

key - the key.

Returns:

the ceiling key, or null if there is no such key.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

lowerEntry

java.util.Map.Entry<K,V> lowerEntry(K key)

Returns a key-value mapping associated with the greatest key strictly less than the given key, or null if there is no such entry.

Parameters:

key - the key.

Returns:

an Entry with greatest key less than the given key, or null if there is no such Entry.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

lowerKey

K lowerKey(K key)

Returns the greatest key strictly less than the given key, or null if there is no such key.

Parameters:

key - the key.

Returns:

the greatest key less than the given key, or null if there is no such key.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

floorEntry

java.util.Map.Entry<K,V> floorEntry(K key)

Returns a key-value mapping associated with the greatest key less than or equal to the given key, or null if there is no such entry.

Parameters:

key - the key.

Returns:

an Entry associated with floor of given key, or null if there is no such Entry.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

floorKey

K floorKey(K key)

Returns the greatest key less than or equal to the given key, or null if there is no such key.

Parameters:

key - the key.

Returns:

the floor of given key, or null if there is no such key.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

higherEntry

java.util.Map.Entry<K,V> higherEntry(K key)

Returns a key-value mapping associated with the least key strictly greater than the given key, or null if there is no such entry.

Parameters:

key - the key.

Returns:

an Entry with least key greater than the given key, or null if there is no such Entry.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

higherKey

K higherKey(K key)

Returns the least key strictly greater than the given key, or null if there is no such key.

Parameters:

key - the key.

Returns:

the least key greater than the given key, or null if there is no such key.

Throws:

java.lang.ClassCastException - if key cannot be compared with the keys currently in the map.

java.lang.NullPointerException - if key is null and this map does not support null keys.

firstEntry

java.util.Map.Entry<K,V> firstEntry()

Returns a key-value mapping associated with the least key in this map, or null if the map is empty.

Returns:

an Entry with least key, or null if the map is empty.

lastEntry

java.util.Map.Entry<K,V> lastEntry()

Returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

Returns:

an Entry with greatest key, or null if the map is empty.

pollFirstEntry

java.util.Map.Entry<K,V> pollFirstEntry()

Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.

Returns:

the removed first entry of this map, or null if the map is empty.

pollLastEntry

java.util.Map.Entry<K,V> pollLastEntry()

Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

Returns:

the removed last entry of this map, or null if the map is empty.

descendingKeySet

java.util.Set<K> descendingKeySet()

Returns a set view of the keys contained in this map, in descending key order. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Returns:

a set view of the keys contained in this map.

descendingEntrySet

java.util.Set<java.util.Map.Entry<K,V>> descendingEntrySet()

Returns a set view of the mappings contained in this map, in descending key order. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Returns:

a set view of the mappings contained in this map.

subMap

NavigableMap<K,V> subMap(K fromKey,
                         K toKey)

Returns a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive. (If fromKey and toKey are equal, the returned sorted map is empty.) The returned sorted map is backed by this map, so changes in the returned sorted map are reflected in this map, and vice-versa.

Specified by:

subMap in interface java.util.SortedMap<K,V>

Parameters:

fromKey - low endpoint (inclusive) of the subMap.

toKey - high endpoint (exclusive) of the subMap.

Returns:

a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive.

Throws:

java.lang.ClassCastException - if fromKey and toKey cannot be compared to one another using this map's comparator (or, if the map has no comparator, using natural ordering).

java.lang.IllegalArgumentException - if fromKey is greater than toKey.

java.lang.NullPointerException - if fromKey or toKey is null and this map does not support null keys.

headMap

NavigableMap<K,V> headMap(K toKey)

Returns a view of the portion of this map whose keys are strictly less than toKey. The returned sorted map is backed by this map, so changes in the returned sorted map are reflected in this map, and vice-versa.

Specified by:

headMap in interface java.util.SortedMap<K,V>

Parameters:

toKey - high endpoint (exclusive) of the headMap.

Returns:

a view of the portion of this map whose keys are strictly less than toKey.

Throws:

java.lang.ClassCastException - if toKey is not compatible with this map's comparator (or, if the map has no comparator, if toKey does not implement Comparable).

java.lang.NullPointerException - if toKey is null and this map does not support null keys.

tailMap

NavigableMap<K,V> tailMap(K fromKey)

Returns a view of the portion of this map whose keys are greater than or equal to fromKey. The returned sorted map is backed by this map, so changes in the returned sorted map are reflected in this map, and vice-versa.

Specified by:

tailMap in interface java.util.SortedMap<K,V>

Parameters:

fromKey - low endpoint (inclusive) of the tailMap.

Returns:

a view of the portion of this map whose keys are greater than or equal to fromKey.

Throws:

java.lang.ClassCastException - if fromKey is not compatible with this map's comparator (or, if the map has no comparator, if fromKey does not implement Comparable).

java.lang.NullPointerException - if fromKey is null and this map does not support null keys.