Интерфейс SequencedMap<K,V>

Параметры типа:: K - тип ключей, хранящихся в этой карте; V - тип отображаемых значений

Все супертипы:: Map<K,V>

Все известные подтипы:: ConcurrentNavigableMap<K,V>, NavigableMap<K,V>, SortedMap<K,V>

Все известные классы-реализации:: ConcurrentSkipListMap, LinkedHashMap, TreeMap

public interface SequencedMap<K,V> extends Map<K,V>

Карта с определённым порядком обхода, поддерживающая операции с обоих концов и допускающая обращение порядка. Порядок обхода элементов SequencedMap аналогичен порядку элементов SequencedCollection, но порядок задаётся для отображений, а не для отдельных элементов.

Групповые операции над этой картой, включая методы forEach и replaceAll, обрабатывают отображения этой карты в порядке обхода.

Коллекции-представления, предоставляемые методами keySet, values, entrySet, sequencedKeySet, sequencedValues и sequencedEntrySet, отражают порядок обхода этой карты. Хотя возвращаемые методами keySet, values и entrySet значения не являются типами последовательных коллекций, элементы этих коллекций-представлений отражают порядок обхода этой карты. Таким образом, итераторы, возвращаемые следующими инструкциями,

    var it1 = sequencedMap.entrySet().iterator();
    var it2 = sequencedMap.sequencedEntrySet().iterator();

оба предоставляют отображения sequencedMap в порядке обхода этой карты.

Этот интерфейс предоставляет методы для добавления, получения и удаления отображений с любого конца порядка обхода карты.

Этот интерфейс также определяет метод reversed(), который предоставляет представление этой карты в обратном порядке. В представлении с обратным порядком понятия первого и последнего, а также последующего и предыдущего элементов меняются местами. Первое отображение этой карты является последним отображением представления с обратным порядком, и наоборот. Последующее отображение для некоторого отображения в этой карте является предыдущим отображением в представлении с обратным порядком, и наоборот. Все методы, учитывающие порядок обхода карты, работают так, как если бы порядок обхода был обратным. Например, метод forEach представления с обратным порядком сообщает об отображениях в порядке от последнего отображения этой карты к первому. Кроме того, все коллекции-представления представления с обратным порядком отражают обратный порядок обхода этой карты. Например,

    var itr = sequencedMap.reversed().entrySet().iterator();

предоставляет отображения этой карты в обратном порядке обхода, то есть от последнего отображения к первому. Наличие метода reversed и его влияние на семантику порядка всех применимых методов и представлений позволяют удобно перебирать, искать, копировать и передавать в поток отображения этой карты как в прямом, так и в обратном порядке.

Представление карты с обратным порядком, как правило, не является сериализуемым, даже если исходная карта сериализуема.

Экземпляры Map.Entry, полученные при переборе представления Map.entrySet(), представления sequencedEntrySet() и его представления с обратным порядком, сохраняют связь с базовой картой. Эта связь гарантируется только во время перебора. Не определено, сохраняется ли связь за пределами перебора. Если базовая карта это допускает, вызов метода setValue элемента Entry изменит значение базового отображения. Однако не определено, будут ли изменения значения в базовом отображении видны в экземпляре Entry.

Методы firstEntry(), lastEntry(), pollFirstEntry() и pollLastEntry() возвращают экземпляры Map.Entry, представляющие снимки отображений на момент вызова. Они не поддерживают изменение базовой карты с помощью необязательного метода setValue.

В зависимости от реализации экземпляры Entry, полученные другими способами, могут быть связаны с базовой картой или не связаны с ней. Например, рассмотрим Entry, полученный следующим образом:

    var entry = sequencedMap.sequencedEntrySet().getFirst();

Этот интерфейс не определяет, будет ли метод setValue полученного таким образом Entry обновлять отображение в базовой карте, выбрасывать исключение или отражать изменения базовой карты в этом Entry.

Этот интерфейс предъявляет к методам equals и hashCode те же требования, что и Map.equals и Map.hashCode. Таким образом, Map и SequencedMap считаются равными тогда и только тогда, когда они содержат одинаковые отображения, независимо от порядка.

Этот класс входит в состав Java Collections Framework.

Начиная с:: 21

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в интерфейсе Map

Map.Entry<K,V>

Краткое описание методов

Модификатор и тип	Метод	Описание
`default Map.Entry<K,V>`	`firstEntry()`	Возвращает первое отображение «ключ-значение» в этой карте или `null`, если карта пуста.
`default Map.Entry<K,V>`	`lastEntry()`	Возвращает последнее отображение «ключ-значение» в этой карте или `null`, если карта пуста.
`default Map.Entry<K,V>`	`pollFirstEntry()`	Удаляет и возвращает первое отображение «ключ-значение» в этой карте или `null`, если карта пуста (необязательная операция).
`default Map.Entry<K,V>`	`pollLastEntry()`	Удаляет и возвращает последнее отображение «ключ-значение» в этой карте или `null`, если карта пуста (необязательная операция).
`default V`	`putFirst(K k, V v)`	Вставляет заданное отображение в карту, если его там ещё нет, или заменяет значение отображения, если оно уже есть (необязательная операция).
`default V`	`putLast(K k, V v)`	Вставляет заданное отображение в карту, если его там ещё нет, или заменяет значение отображения, если оно уже есть (необязательная операция).
`SequencedMap<K,V>`	`reversed()`	Возвращает представление этой карты в обратном порядке.
`default SequencedSet<Map.Entry<K,V>>`	`sequencedEntrySet()`	Возвращает `SequencedSet` представление `entrySet` этой карты.
`default SequencedSet<K>`	`sequencedKeySet()`	Возвращает `SequencedSet` представление `keySet` этой карты.
`default SequencedCollection<V>`	`sequencedValues()`	Возвращает `SequencedCollection` представление коллекции `values` этой карты.

Методы, объявленные в интерфейсе Map

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

Подробное описание методов

reversed

SequencedMap<K,V> reversed()

Возвращает представление этой карты в обратном порядке. Порядок обхода отображений в возвращаемом представлении обратен порядку обхода отображений в этой карте. Обратный порядок влияет на все операции, чувствительные к порядку, в том числе на операции над коллекциями-представлениями возвращаемого представления. Если реализация допускает изменение этого представления, изменения «передаются» базовой карте. В зависимости от реализации изменения базовой карты могут быть видны в этом представлении с обратным порядком или не видны.

Возвращает:: представление этой карты в обратном порядке

firstEntry

default Map.Entry<K,V> firstEntry()

Возвращает первое отображение «ключ-значение» в этой карте или null, если карта пуста.

Требования к реализации:: Реализация в этом интерфейсе получает итератор множества entrySet этой карты. Если итератор содержит элемент, возвращается его неизменяемая копия. В противном случае возвращается null.
Возвращает:: первое отображение «ключ-значение» или null, если эта карта пуста

lastEntry

default Map.Entry<K,V> lastEntry()

Возвращает последнее отображение «ключ-значение» в этой карте или null, если карта пуста.

Требования к реализации:: Реализация в этом интерфейсе получает итератор множества entrySet представления этой карты с обратным порядком. Если итератор содержит элемент, возвращается его неизменяемая копия. В противном случае возвращается null.
Возвращает:: последнее отображение «ключ-значение» или null, если эта карта пуста

pollFirstEntry

default Map.Entry<K,V> pollFirstEntry()

Удаляет и возвращает первое отображение «ключ-значение» в этой карте или null, если карта пуста (необязательная операция).

Требования к реализации:: Реализация в этом интерфейсе получает итератор множества entrySet этой карты. Если итератор содержит элемент, она вызывает remove для итератора, а затем возвращает неизменяемую копию этого элемента. В противном случае возвращается null.
Возвращает:: удалённую первую запись этой карты или null, если эта карта пуста
Выбрасывает:: UnsupportedOperationException - если эта реализация коллекции не поддерживает данную операцию

pollLastEntry

default Map.Entry<K,V> pollLastEntry()

Удаляет и возвращает последнее отображение «ключ-значение» в этой карте или null, если карта пуста (необязательная операция).

Требования к реализации:: Реализация в этом интерфейсе получает итератор множества entrySet представления этой карты с обратным порядком. Если итератор содержит элемент, она вызывает remove для итератора, а затем возвращает неизменяемую копию этого элемента. В противном случае возвращается null.
Возвращает:: удалённую последнюю запись этой карты или null, если эта карта пуста
Выбрасывает:: UnsupportedOperationException - если эта реализация коллекции не поддерживает данную операцию

putFirst

default V putFirst(K k, V v)

Вставляет заданное отображение в карту, если его там ещё нет, или заменяет значение отображения, если оно уже есть (необязательная операция). После успешного завершения этой операции заданное отображение будет присутствовать в этой карте и станет первым отображением в порядке обхода этой карты.

Требования к реализации:: Реализация в этом интерфейсе всегда выбрасывает UnsupportedOperationException.
Параметры:: k - ключ; v - значение
Возвращает:: значение, ранее связанное с k, или null, если такого значения не было
Выбрасывает:: UnsupportedOperationException - если эта реализация коллекции не поддерживает данную операцию

putLast

default V putLast(K k, V v)

Вставляет заданное отображение в карту, если его там ещё нет, или заменяет значение отображения, если оно уже есть (необязательная операция). После успешного завершения этой операции заданное отображение будет присутствовать в этой карте и станет последним отображением в порядке обхода этой карты.

Требования к реализации:: Реализация в этом интерфейсе всегда выбрасывает UnsupportedOperationException.
Параметры:: k - ключ; v - значение
Возвращает:: значение, ранее связанное с k, или null, если такого значения не было
Выбрасывает:: UnsupportedOperationException - если эта реализация коллекции не поддерживает данную операцию

sequencedKeySet

default SequencedSet<K> sequencedKeySet()

Возвращает SequencedSet представление keySet этой карты.

Требования к реализации:: Реализация в этом интерфейсе возвращает экземпляр SequencedSet со следующим поведением. Его методы add, addAll, addFirst и addLast выбрасывают UnsupportedOperationException. Методы getFirst и getLast реализованы с использованием соответственно методов firstEntry и lastEntry этого интерфейса. Методы removeFirst и removeLast реализованы с использованием соответственно методов pollFirstEntry и pollLastEntry этого интерфейса. Метод reversed возвращает представление sequencedKeySet представления reversed этой карты. Каждый из остальных его методов вызывает соответствующий метод представления keySet этой карты.
Возвращает:: SequencedSet представление keySet

sequencedValues

default SequencedCollection<V> sequencedValues()

Возвращает SequencedCollection представление коллекции values этой карты.

Требования к реализации:: Реализация в этом интерфейсе возвращает экземпляр SequencedCollection со следующим поведением. Его методы add, addAll, addFirst и addLast выбрасывают UnsupportedOperationException. Методы getFirst и getLast реализованы с использованием соответственно методов firstEntry и lastEntry этого интерфейса. Методы removeFirst и removeLast реализованы с использованием соответственно методов pollFirstEntry и pollLastEntry этого интерфейса. Метод reversed возвращает представление sequencedValues представления reversed этой карты. Методы equals и hashCode наследуются от Object. Каждый из остальных его методов вызывает соответствующий метод представления values этой карты.
Возвращает:: SequencedCollection представление коллекции values этой карты

sequencedEntrySet

default SequencedSet<Map.Entry<K,V>> sequencedEntrySet()

Возвращает SequencedSet представление entrySet этой карты.

Требования к реализации:: Реализация в этом интерфейсе возвращает экземпляр SequencedSet со следующим поведением. Его методы add, addAll, addFirst и addLast выбрасывают UnsupportedOperationException. Методы getFirst и getLast реализованы с использованием соответственно методов firstEntry и lastEntry этого интерфейса. Методы removeFirst и removeLast реализованы с использованием соответственно методов pollFirstEntry и pollLastEntry этого интерфейса. Метод reversed возвращает представление sequencedEntrySet представления reversed этой карты. Каждый из остальных его методов вызывает соответствующий метод представления entrySet этой карты.
Возвращает:: SequencedSet представление entrySet

© 1993, 2025, 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/25/docs/api/java.base/java/util/SequencedMap.html