Интерфейс 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.

Методы 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.

Since:: 21

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

Вложенные классы/интерфейсы, объявленные в интерфейсе java.util.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()`	Возвращает видовое представление набора пар «ключ-значение» этой карты.
`default SequencedSet<K>`	`sequencedKeySet()`	Возвращает видовое представление набора ключей этой карты.
`default SequencedCollection<V>`	`sequencedValues()`	Возвращает видовое представление коллекции значений этой карты.

Методы, объявленные в интерфейсе java.util.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()

Возвращает упорядоченное представление набора ключей (keySet) этого отображения.

Требования к реализации:: Реализация в этом интерфейсе возвращает экземпляр, который ведет себя следующим образом. Его методы add и addAll выбрасывают UnsupportedOperationException. Его метод reversed возвращает представление упорядоченного набора ключей (sequencedKeySet) обратного представления (reversed) этого отображения. Каждый из его других методов вызывает соответствующий метод представления набора ключей (keySet) этого отображения.
Возвращает:: упорядоченное представление набора ключей (keySet) этого отображения

sequencedValues

default SequencedCollection<V> sequencedValues()

Возвращает упорядоченное представление коллекции значений (values) этого отображения.

Требования к реализации:: Реализация в этом интерфейсе возвращает экземпляр, который ведет себя следующим образом. Его методы add и addAll выбрасывают UnsupportedOperationException. Его метод reversed возвращает представление упорядоченной коллекции значений (sequencedValues) обратного представления (reversed) этого отображения. Его методы equals и hashCode унаследованы от Object. Каждый из его других методов вызывает соответствующий метод представления коллекции значений (values) этого отображения.
Возвращает:: упорядоченное представление коллекции значений (values) этого отображения

sequencedEntrySet

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

Возвращает упорядоченное представление набора элементов (entrySet) этого отображения.

Требования к реализации:: Реализация в этом интерфейсе возвращает экземпляр, который ведет себя следующим образом. Его методы add и addAll выбрасывают UnsupportedOperationException. Его метод reversed возвращает представление упорядоченного набора элементов (sequencedEntrySet) обратного представления (reversed) этого отображения. Каждый из его других методов вызывает соответствующий метод представления набора элементов (entrySet) этого отображения.
Возвращает:: упорядоченное представление набора элементов (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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/SequencedMap.html