K
- the type of keys maintained by this mapV
- the type of mapped valuesMap<K,V>
ConcurrentNavigableMap<K,V>
, NavigableMap<K,V>
, SortedMap<K,V>
ConcurrentSkipListMap
, LinkedHashMap
, TreeMap
public interface SequencedMap<K,V> extends Map<K,V>
SequencedMap
is similar to that of the elements of a SequencedCollection
, but the ordering applies to mappings instead of individual elements. The bulk operations on this map, including the forEach
and the replaceAll
methods, operate on this map's mappings in encounter order.
The view collections provided by the keySet
, values
, entrySet
, sequencedKeySet
, sequencedValues
, and sequencedEntrySet
methods all reflect the encounter order of this map. Even though the return values of the keySet
, values
, and entrySet
methods are not sequenced types, the elements in those view collections do reflect the encounter order of this map. Thus, the iterators returned by the statements
var it1 = sequencedMap.entrySet().iterator();
var it2 = sequencedMap.sequencedEntrySet().iterator();
sequencedMap
in that map's encounter order. This interface provides methods to add mappings, to retrieve mappings, and to remove mappings at either end of the map's encounter order.
This interface also defines the reversed()
method, which provides a reverse-ordered view of this map. In the reverse-ordered view, the concepts of first and last are inverted, as are the concepts of successor and predecessor. The first mapping of this map is the last mapping of the reverse-ordered view, and vice-versa. The successor of some mapping in this map is its predecessor in the reversed view, and vice-versa. All methods that respect the encounter order of the map operate as if the encounter order is inverted. For instance, the forEach
method of the reversed view reports the mappings in order from the last mapping of this map to the first. In addition, all of the view collections of the reversed view also reflect the inverse of this map's encounter order. For example,
var itr = sequencedMap.reversed().entrySet().iterator();
reversed
method, and its impact on the ordering semantics of all applicable methods and views, allow convenient iteration, searching, copying, and streaming of this map's mappings in either forward order or reverse order. A map's reverse-ordered view is generally not serializable, even if the original map is serializable.
The Map.Entry
instances obtained by iterating the Map.entrySet()
view, the sequencedEntrySet()
view, and its reverse-ordered view, maintain a connection to the underlying map. This connection is guaranteed only during the iteration. It is unspecified whether the connection is maintained outside of the iteration. If the underlying map permits it, calling an Entry's setValue
method will modify the value of the underlying mapping. It is, however, unspecified whether modifications to the value in the underlying mapping are visible in the Entry
instance.
The methods firstEntry()
, lastEntry()
, pollFirstEntry()
, and pollLastEntry()
return Map.Entry
instances that represent snapshots of mappings as of the time of the call. They do not support mutation of the underlying map via the optional setValue
method.
Depending upon the implementation, the Entry
instances returned by other means might or might not be connected to the underlying map. For example, consider an Entry
obtained in the following manner:
var entry = sequencedMap.sequencedEntrySet().getFirst();
setValue
method of the Entry
thus obtained will update a mapping in the underlying map, or whether it will throw an exception, or whether changes to the underlying map are visible in that Entry
. This interface has the same requirements on the equals
and hashCode
methods as defined by Map.equals
and Map.hashCode
. Thus, a Map
and a SequencedMap
will compare equals if and only if they have equal mappings, irrespective of ordering.
This class is a member of the Java Collections Framework.
Modifier and Type | Method | Description |
---|---|---|
default Map.Entry |
firstEntry() |
Returns the first key-value mapping in this map, or null if the map is empty. |
default Map.Entry |
lastEntry() |
Returns the last key-value mapping in this map, or null if the map is empty. |
default Map.Entry |
pollFirstEntry() |
Removes and returns the first key-value mapping in this map, or null if the map is empty (optional operation). |
default Map.Entry |
pollLastEntry() |
Removes and returns the last key-value mapping in this map, or null if the map is empty (optional operation). |
default V |
putFirst |
Inserts the given mapping into the map if it is not already present, or replaces the value of a mapping if it is already present (optional operation). |
default V |
putLast |
Inserts the given mapping into the map if it is not already present, or replaces the value of a mapping if it is already present (optional operation). |
SequencedMap |
reversed() |
Returns a reverse-ordered view of this map. |
default SequencedSet |
sequencedEntrySet() |
Returns a SequencedSet view of this map's entrySet . |
default SequencedSet |
sequencedKeySet() |
Returns a SequencedSet view of this map's keySet . |
default SequencedCollection |
sequencedValues() |
Returns a SequencedCollection view of this map's values collection. |
clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values
SequencedMap<K,V> reversed()
default Map.Entry<K,V> firstEntry()
null
if the map is empty.null
if this map is emptydefault Map.Entry<K,V> lastEntry()
null
if the map is empty.null
if this map is emptydefault Map.Entry<K,V> pollFirstEntry()
null
if the map is empty (optional operation).remove
on the iterator and then returns an unmodifiable copy of that element. Otherwise, it returns null.null
if this map is emptyUnsupportedOperationException
- if this collection implementation does not support this operationdefault Map.Entry<K,V> pollLastEntry()
null
if the map is empty (optional operation).remove
on the iterator and then returns an unmodifiable copy of that element. Otherwise, it returns null.null
if this map is emptyUnsupportedOperationException
- if this collection implementation does not support this operationdefault V putFirst(K k, V v)
UnsupportedOperationException
.k
- the keyv
- the valueUnsupportedOperationException
- if this collection implementation does not support this operationdefault V putLast(K k, V v)
UnsupportedOperationException
.k
- the keyv
- the valueUnsupportedOperationException
- if this collection implementation does not support this operationdefault SequencedSet<K> sequencedKeySet()
SequencedSet
view of this map's keySet
.SequencedSet
instance that behaves as follows. Its add
and addAll
methods throw UnsupportedOperationException
. Its reversed
method returns the sequencedKeySet
view of the reversed
view of this map. Each of its other methods calls the corresponding method of the keySet
view of this map.SequencedSet
view of this map's keySet
default SequencedCollection<V> sequencedValues()
SequencedCollection
view of this map's values
collection.SequencedCollection
instance that behaves as follows. Its add
and addAll
methods throw UnsupportedOperationException
. Its reversed
method returns the sequencedValues
view of the reversed
view of this map. Its equals
and hashCode
methods are inherited from Object
. Each of its other methods calls the corresponding method of the values
view of this map.SequencedCollection
view of this map's values
collectiondefault SequencedSet<Map.Entry<K,V>> sequencedEntrySet()
SequencedSet
view of this map's entrySet
.SequencedSet
instance that behaves as follows. Its add
and addAll
methods throw UnsupportedOperationException
. Its reversed
method returns the sequencedEntrySet
view of the reversed
view of this map. Each of its other methods calls the corresponding method of the entrySet
view of this map.SequencedSet
view of this map's entrySet
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/SequencedMap.html